Skip to content

Commit 84ec400

Browse files
baeseung-intelbaeseung-intel
authored
[oneMKL][spblas] update the spec for several spblas routines (#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.
1 parent 2a1f109 commit 84ec400

File tree

8 files changed

+107
-231
lines changed

8 files changed

+107
-231
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -191,7 +191,7 @@ gemm (USM version)
191191
const std::int64_t columns,
192192
const std::int64_t ldb,
193193
const fp beta,
194-
const fp *C,
194+
fp *C,
195195
const std::int64_t ldc,
196196
const std::vector<sycl::event> &dependencies = {});
197197

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ gemv (USM version)
126126
oneapi::mkl::sparse::matrix_handle_t A_handle,
127127
const fp *x,
128128
const fp beta,
129-
const fp *y,
129+
fp *y,
130130
const std::vector<sycl::event> &dependencies = {});
131131
132132
}

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

Lines changed: 9 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -17,65 +17,6 @@ and performs optimizations. Optimized data is then stored in
1717
the handle.
1818

1919

20-
.. _onemkl_sparse_optimize_gemv_buffer:
21-
22-
optimize_gemv (Buffer version)
23-
------------------------------
24-
25-
.. rubric:: Syntax
26-
27-
.. code-block:: cpp
28-
29-
namespace oneapi::mkl::sparse {
30-
31-
void optimize_gemv (sycl::queue &queue,
32-
oneapi::mkl::transpose transpose_val,
33-
oneapi::mkl::sparse::matrix_handle_t handle);
34-
35-
}
36-
37-
.. container:: section
38-
39-
.. rubric:: Input Parameters
40-
41-
queue
42-
Specifies the SYCL command queue which will be used for SYCL
43-
kernels execution.
44-
45-
46-
transpose_val
47-
Specifies operation ``op()`` on input matrix. The possible options
48-
are described in :ref:`onemkl_enum_transpose` enum class.
49-
50-
51-
handle
52-
Handle to object containing sparse matrix and other internal
53-
data. Created using the
54-
oneapi::mkl::sparse::set_csr_data routine.
55-
56-
57-
.. container:: section
58-
59-
.. rubric:: Throws
60-
:class: sectiontitle
61-
62-
This routine shall throw the following exceptions if the associated condition is detected.
63-
An implementation may throw additional implementation-specific exception(s)
64-
in case of error conditions not covered here.
65-
66-
| :ref:`oneapi::mkl::computation_error<onemkl_exception_computation_error>`
67-
| :ref:`oneapi::mkl::device_bad_alloc<onemkl_exception_device_bad_alloc>`
68-
| :ref:`oneapi::mkl::host_bad_alloc<onemkl_exception_host_bad_alloc>`
69-
| :ref:`oneapi::mkl::invalid_argument<onemkl_exception_invalid_argument>`
70-
| :ref:`oneapi::mkl::unimplemented<onemkl_exception_unimplemented>`
71-
| :ref:`oneapi::mkl::uninitialized<onemkl_exception_uninitialized>`
72-
| :ref:`oneapi::mkl::unsupported_device<onemkl_exception_unsupported_device>`
73-
74-
.. _onemkl_sparse_optimize_gemv_usm:
75-
76-
optimize_gemv (USM version)
77-
---------------------------
78-
7920
.. rubric:: Syntax
8021

8122
.. code-block:: cpp
@@ -85,7 +26,7 @@ optimize_gemv (USM version)
8526
sycl::event optimize_gemv (sycl::queue &queue,
8627
oneapi::mkl::transpose transpose_val,
8728
oneapi::mkl::sparse::matrix_handle_t handle,
88-
std::vector<sycl::event> &dependencies);
29+
const std::vector<sycl::event> &dependencies = {});
8930
9031
}
9132
@@ -113,6 +54,14 @@ optimize_gemv (USM version)
11354
List of events that oneapi::mkl::sparse::optimize_gemv routine depends on.
11455

11556

57+
.. container:: section
58+
59+
.. rubric:: Output Parameters
60+
:class: sectiontitle
61+
62+
handle
63+
Handle might be updated with some internal optimized data by this routine.
64+
11665
.. container:: section
11766

11867
.. rubric:: Throws

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

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,29 @@ The oneapi::mkl::sparse::init_matrix_handle function initializes the
2424
2525
namespace oneapi::mkl::sparse {
2626
27-
void init_matrix_handle (oneapi::mkl::sparse::matrix_handle_t *handle);
27+
void init_matrix_handle (oneapi::mkl::sparse::matrix_handle_t *p_handle);
2828
2929
}
3030
31+
32+
.. container:: section
33+
34+
.. rubric:: Input parameters
35+
36+
p_handle
37+
The address of the sparse::matrix_handle_t ``p_handle`` object to be initialized.
38+
This initialization routine must only be called on an uninitialized matrix_handle_t object.
39+
40+
41+
.. container:: section
42+
43+
.. rubric:: Output parameters
44+
45+
p_handle
46+
On return, the address is updated to point to a newly allocated and initialized matrix_handle_t object
47+
that can be filled and used to perform sparse BLAS operations.
48+
49+
3150
.. container:: section
3251

3352
.. rubric:: Throws
@@ -50,4 +69,4 @@ The oneapi::mkl::sparse::init_matrix_handle function initializes the
5069
.. container:: parentlink
5170

5271

53-
**Parent topic:** :ref:`onemkl_spblas`
72+
**Parent topic:** :ref:`onemkl_spblas`

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

Lines changed: 25 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -26,26 +26,43 @@ before releasing any data in case of USM.
2626
2727
namespace oneapi::mkl::sparse {
2828
29-
void release_matrix_handle (oneapi::mkl::sparse::matrix_handle_t handle,
30-
const std::vector<sycl::event> &dependencies = {});
29+
sycl::event release_matrix_handle (sycl::queue &queue,
30+
oneapi::mkl::sparse::matrix_handle_t *p_handle,
31+
const std::vector<sycl::event> &dependencies = {});
3132
3233
}
3334
3435
.. container:: section
3536

3637

37-
.. rubric:: Input parameter
38+
.. rubric:: Input parameters
3839

40+
queue
41+
The SYCL command queue which will be used for SYCL kernels execution.
3942

40-
handle
41-
Handle to object containing sparse matrix and other internal
42-
data. Created using one of the
43+
p_handle
44+
The address of the sparse::matrix_handle_t ``p_handle`` object to be released, containing sparse matrix and other internal
45+
data. Initialized with oneapi::mkl::sparse::init_matrix_handle routine, and filled with user data using one of the
4346
oneapi::mkl::sparse::set_<sparse_matrix_type>_structure routines.
4447

4548
dependencies
46-
List of events that ``handle`` depends on.
47-
The call waits on the events(if any) before resetting the ``handle`` to default values.
49+
List of events that ``p_handle`` depends on.
50+
The call waits on the events(if any) before resetting the ``p_handle`` to default values.
4851

52+
.. container:: section
53+
54+
.. rubric:: Output parameters
55+
56+
p_handle
57+
The address of the sparse::matrix_handle_t ``p_handle`` that will be scheduled to be updated to point to a null object
58+
and the passed in handle will be scheduled for deallocation and cleanup.
59+
60+
.. container:: section
61+
62+
.. rubric:: Return Values
63+
64+
sycl::event
65+
SYCL event which can be waited upon or added as a dependency for the completion of the deallocation and cleanup routines.
4966

5067
.. container:: section
5168

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

Lines changed: 32 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,8 @@ set_csr_data (Buffer version)
3131
3232
namespace oneapi::mkl::sparse {
3333
34-
void set_csr_data (oneapi::mkl::sparse::matrix_handle_t handle,
34+
void set_csr_data (sycl::queue &queue,
35+
oneapi::mkl::sparse::matrix_handle_t handle,
3536
intType num_rows,
3637
intType num_cols,
3738
oneapi::mkl::index_base index,
@@ -45,6 +46,9 @@ set_csr_data (Buffer version)
4546

4647
.. rubric:: Input Parameters
4748

49+
queue
50+
The SYCL command queue which will be used for SYCL kernel execution.
51+
4852
handle
4953
Handle to object containing sparse matrix and other internal
5054
data for subsequent DPC++ Sparse BLAS operations.
@@ -122,20 +126,25 @@ set_csr_data (USM version)
122126
123127
namespace oneapi::mkl::sparse {
124128
125-
void set_csr_data (oneapi::mkl::sparse::matrix_handle_t handle,
126-
intType num_rows,
127-
intType num_cols,
128-
oneapi::mkl::index_base index,
129-
intType *row_ptr,
130-
intType *col_ind,
131-
fp *val);
129+
sycl::event set_csr_data (sycl::queue &queue,
130+
oneapi::mkl::sparse::matrix_handle_t handle,
131+
intType num_rows,
132+
intType num_cols,
133+
oneapi::mkl::index_base index,
134+
intType *row_ptr,
135+
intType *col_ind,
136+
fp *val,
137+
const std::vector<sycl::event> &dependencies = {});
132138
133139
}
134140
135141
.. container:: section
136142

137143
.. rubric:: Input Parameters
138144

145+
queue
146+
The SYCL command queue which will be used for SYCL kernel execution.
147+
139148
handle
140149
Handle to object containing sparse matrix and other internal
141150
data for subsequent DPC++ Sparse BLAS operations.
@@ -173,17 +182,28 @@ set_csr_data (USM version)
173182
non-zero elements of the input matrix. Refer to
174183
:ref:`onemkl_sparse_csr` format for detailed description of ``val``
175184

185+
dependencies
186+
A vector of type const std::vector<sycl::event> & containing the list of events
187+
that the oneapi::mkl::sparse::set_csr_data routine depends on.
176188

177189
.. container:: section
178190

179191
.. rubric:: Output Parameters
180192
:class: sectiontitle
181193

182194

183-
handle
184-
Handle to object containing sparse matrix and other internal
185-
data for subsequent SYCL Sparse BLAS operations.
195+
handle
196+
Handle to object containing sparse matrix and other internal
197+
data for subsequent SYCL Sparse BLAS operations.
198+
199+
.. container:: section
200+
201+
.. rubric:: Return Values
202+
:class: sectiontitle
186203

204+
sycl::event
205+
A sycl::event that can be used to track the completion of asynchronous events
206+
that were enqueued during the API call that continue the chain of events from the input dependencies.
187207

188208
.. container:: section
189209

@@ -208,4 +228,4 @@ handle
208228
.. container:: parentlink
209229

210230

211-
**Parent topic:** :ref:`onemkl_spblas`
231+
**Parent topic:** :ref:`onemkl_spblas`

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

Lines changed: 9 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -17,79 +17,6 @@ and performs optimizations. Optimized data is then stored in
1717
the handle.
1818

1919

20-
.. _onemkl_sparse_optimize_trmv_buffer:
21-
22-
optimize_trmv (Buffer version)
23-
------------------------------
24-
25-
.. rubric:: Syntax
26-
27-
.. code-block:: cpp
28-
29-
namespace oneapi::mkl::sparse {
30-
31-
void optimize_trmv (sycl::queue &queue,
32-
oneapi::mkl::uplo uplo_val,
33-
oneapi::mkl::transpose transpose_val,
34-
oneapi::mkl::diag diag_val,
35-
oneapi::mkl::sparse::matrix_handle_t handle);
36-
}
37-
38-
.. container:: section
39-
40-
41-
.. rubric:: Input Parameters
42-
43-
44-
queue
45-
Specifies the SYCL command queue which will be used for SYCL
46-
kernels execution.
47-
48-
49-
uplo_val
50-
Specifies which part is to be processed. The possible options are
51-
described in :ref:`onemkl_enum_uplo` enum class.
52-
53-
54-
transpose_val
55-
Specifies operation ``op()`` on input matrix. The possible options
56-
are described in :ref:`onemkl_enum_transpose` enum class.
57-
58-
59-
diag_val
60-
Specifies if the diagonal is unit or not. The possible options
61-
are described in :ref:`onemkl_enum_diag` enum class.
62-
63-
64-
handle
65-
Handle to object containing sparse matrix and other internal
66-
data. Created using the
67-
oneapi::mkl::sparse::set_csr_data routine.
68-
69-
70-
.. container:: section
71-
72-
.. rubric:: Throws
73-
:class: sectiontitle
74-
75-
This routine shall throw the following exceptions if the associated condition is detected.
76-
An implementation may throw additional implementation-specific exception(s)
77-
in case of error conditions not covered here.
78-
79-
| :ref:`oneapi::mkl::computation_error<onemkl_exception_computation_error>`
80-
| :ref:`oneapi::mkl::device_bad_alloc<onemkl_exception_device_bad_alloc>`
81-
| :ref:`oneapi::mkl::host_bad_alloc<onemkl_exception_host_bad_alloc>`
82-
| :ref:`oneapi::mkl::invalid_argument<onemkl_exception_invalid_argument>`
83-
| :ref:`oneapi::mkl::unimplemented<onemkl_exception_unimplemented>`
84-
| :ref:`oneapi::mkl::uninitialized<onemkl_exception_uninitialized>`
85-
| :ref:`oneapi::mkl::unsupported_device<onemkl_exception_unsupported_device>`
86-
87-
88-
.. _onemkl_sparse_optimize_trmv_usm:
89-
90-
optimize_trmv (USM version)
91-
---------------------------
92-
9320
.. rubric:: Syntax
9421

9522
.. code-block:: cpp
@@ -101,7 +28,7 @@ optimize_trmv (USM version)
10128
oneapi::mkl::transpose transpose_val,
10229
oneapi::mkl::diag diag_val,
10330
oneapi::mkl::sparse::matrix_handle_t handle,
104-
std::vector<sycl::event> &dependencies);
31+
const std::vector<sycl::event> &dependencies = {});
10532
}
10633
10734
.. container:: section
@@ -140,6 +67,14 @@ optimize_trmv (USM version)
14067
List of events that oneapi::mkl::sparse::optimize_trmv routine depends on.
14168

14269

70+
.. container:: section
71+
72+
.. rubric:: Output Parameters
73+
:class: sectiontitle
74+
75+
handle
76+
Handle might be updated with some internal optimized data by this routine.
77+
14378
.. container:: section
14479

14580
.. rubric:: Throws

0 commit comments

Comments
 (0)