Skip to content

Commit b260b06

Browse files
baeseung-intelspencerpatty
baeseung-intel
and
spencerpatty
authored
[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 <[email protected]>
1 parent d6f0898 commit b260b06

File tree

3 files changed

+312
-0
lines changed

3 files changed

+312
-0
lines changed

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

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
.. SPDX-FileCopyrightText: 2023 Intel Corporation
2+
..
3+
.. SPDX-License-Identifier: CC-BY-4.0
4+
5+
.. _onemkl_sparse_optimize_gemm:
6+
7+
optimize_gemm
8+
=============
9+
10+
Performs internal optimizations for oneapi::mkl::sparse::gemm by analyzing
11+
the matrix structure.
12+
13+
.. rubric:: Description and Assumptions
14+
15+
The oneapi::mkl::sparse::optimize_gemm routine analyzes matrix structure
16+
and performs optimizations. Optimized data is then stored in
17+
the handle.
18+
19+
In contrast to other optimization routines in Sparse BLAS domain
20+
which are done solely based on the sparse matrix pattern,
21+
two versions of the ``sparse::optimize_gemm`` routine are provided for preparing different
22+
optimizations for ``sparse::gemm`` routine. In particular, if the shape
23+
of the dense matrix right hand side, :math:`B`, is unknown or widely varying in
24+
subsequent calls to ``sparse::gemm`` then a user might reasonably
25+
only wish to perform optimizations for ``:sparse::gemm`` with respect
26+
to the sparse matrix structure. However, if one or more particular shapes of :math:`B`
27+
is available, then each :math:`B` shape can be provided as an additional hint
28+
along with the sparse matrix pattern in the call to ``sparse::optimize_gemm``. This
29+
second version of the API with :math:`B` shape should be callable one or
30+
more times and may allow libraries to provide more targeted performance
31+
optimizations.
32+
33+
.. _onemkl_sparse_optimize_gemm_A:
34+
35+
optimize_gemm (based on Sparse Matrix)
36+
--------------------------------------
37+
38+
.. rubric:: Syntax
39+
40+
.. code-block:: cpp
41+
42+
namespace oneapi::mkl::sparse {
43+
44+
sycl::event optimize_gemm (sycl::queue &queue,
45+
oneapi::mkl::transpose transpose_A,
46+
oneapi::mkl::sparse::matrix_handle_t A_handle,
47+
const std::vector<sycl::event> &dependencies = {});
48+
49+
}
50+
51+
.. container:: section
52+
53+
.. rubric:: Input Parameters
54+
55+
queue
56+
Specifies the SYCL command queue which will be used for SYCL
57+
kernels execution.
58+
59+
60+
transpose_A
61+
Specifies operation ``op()`` on input matrix :math:`A`. The possible options
62+
are described in :ref:`onemkl_enum_transpose` enum class.
63+
64+
65+
A_handle
66+
Handle to object containing sparse matrix and other internal
67+
data. Created using the
68+
oneapi::mkl::sparse::set_csr_data routine.
69+
70+
71+
dependencies
72+
List of events that oneapi::mkl::sparse::optimize_gemm routine depends on.
73+
74+
75+
.. container:: section
76+
77+
.. rubric:: Output Parameters
78+
:class: sectiontitle
79+
80+
handle
81+
Handle might be updated with some internal optimized data by this routine.
82+
83+
.. container:: section
84+
85+
.. rubric:: Throws
86+
:class: sectiontitle
87+
88+
This routine shall throw the following exceptions if the associated condition is detected.
89+
An implementation may throw additional implementation-specific exception(s)
90+
in case of error conditions not covered here.
91+
92+
| :ref:`oneapi::mkl::computation_error<onemkl_exception_computation_error>`
93+
| :ref:`oneapi::mkl::device_bad_alloc<onemkl_exception_device_bad_alloc>`
94+
| :ref:`oneapi::mkl::host_bad_alloc<onemkl_exception_host_bad_alloc>`
95+
| :ref:`oneapi::mkl::invalid_argument<onemkl_exception_invalid_argument>`
96+
| :ref:`oneapi::mkl::unimplemented<onemkl_exception_unimplemented>`
97+
| :ref:`oneapi::mkl::uninitialized<onemkl_exception_uninitialized>`
98+
| :ref:`oneapi::mkl::unsupported_device<onemkl_exception_unsupported_device>`
99+
100+
.. container:: section
101+
102+
.. rubric:: Return Values
103+
:class: sectiontitle
104+
105+
Output event that can be waited upon or added as a
106+
dependency for the completion of optimize_gemm routine.
107+
108+
109+
.. _onemkl_sparse_optimize_gemm_AB:
110+
111+
optimize_gemm (based on Both Input Matrices)
112+
--------------------------------------------
113+
114+
.. rubric:: Syntax
115+
116+
.. code-block:: cpp
117+
118+
namespace oneapi::mkl::sparse {
119+
120+
sycl::event optimize_gemm (sycl::queue &queue,
121+
oneapi::mkl::transpose transpose_A,
122+
oneapi::mkl::transpose transpose_B,
123+
oneapi::mkl::layout dense_matrix_layout,
124+
const std::int64_t columns,
125+
oneapi::mkl::sparse::matrix_handle_t A_handle,
126+
const std::vector<sycl::event> &dependencies = {});
127+
128+
}
129+
130+
.. container:: section
131+
132+
.. rubric:: Input Parameters
133+
134+
queue
135+
Specifies the SYCL command queue which will be used for SYCL
136+
kernels execution.
137+
138+
139+
transpose_A
140+
Specifies operation ``op()`` on input matrix :math:`A`. The possible options
141+
are described in :ref:`onemkl_enum_transpose` enum class.
142+
143+
144+
transpose_B
145+
Specifies operation ``op()`` on input matrix :math:`B`. The possible options
146+
are described in :ref:`onemkl_enum_transpose` enum class.
147+
148+
149+
dense_matrix_layout
150+
Specifies the storage scheme in memory for the dense matrices. Note that this layout applies to both :math:`B` and :math:`C` dense matrices.
151+
The possible options are described in :ref:`onemkl_enum_layout` enum class.
152+
153+
154+
columns
155+
Number of columns of matrix :math:`C`.
156+
157+
158+
handle
159+
Handle to object containing sparse matrix and other internal
160+
data. Created using the
161+
oneapi::mkl::sparse::set_csr_data routine.
162+
163+
164+
dependencies
165+
List of events that oneapi::mkl::sparse::optimize_gemm routine depends on.
166+
167+
168+
.. container:: section
169+
170+
.. rubric:: Output Parameters
171+
:class: sectiontitle
172+
173+
handle
174+
Handle might be updated with some internal optimized data by this routine.
175+
176+
.. container:: section
177+
178+
.. rubric:: Throws
179+
:class: sectiontitle
180+
181+
This routine shall throw the following exceptions if the associated condition is detected.
182+
An implementation may throw additional implementation-specific exception(s)
183+
in case of error conditions not covered here.
184+
185+
| :ref:`oneapi::mkl::computation_error<onemkl_exception_computation_error>`
186+
| :ref:`oneapi::mkl::device_bad_alloc<onemkl_exception_device_bad_alloc>`
187+
| :ref:`oneapi::mkl::host_bad_alloc<onemkl_exception_host_bad_alloc>`
188+
| :ref:`oneapi::mkl::invalid_argument<onemkl_exception_invalid_argument>`
189+
| :ref:`oneapi::mkl::unimplemented<onemkl_exception_unimplemented>`
190+
| :ref:`oneapi::mkl::uninitialized<onemkl_exception_uninitialized>`
191+
| :ref:`oneapi::mkl::unsupported_device<onemkl_exception_unsupported_device>`
192+
193+
.. container:: section
194+
195+
.. rubric:: Return Values
196+
:class: sectiontitle
197+
198+
Output event that can be waited upon or added as a
199+
dependency for the completion of optimize_gemm routine.
200+
201+
202+
.. container:: familylinks
203+
204+
205+
.. container:: parentlink
206+
207+
208+
**Parent topic:** :ref:`onemkl_spblas`

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,14 @@ Sparse BLAS
2727
- Fills the internal CSR data structure
2828
* - :ref:`onemkl_sparse_optimize_gemv`
2929
- Optimize routine for gemv
30+
* - :ref:`onemkl_sparse_optimize_symv`
31+
- Optimize routine for symv
3032
* - :ref:`onemkl_sparse_optimize_trmv`
3133
- Optimize routine for trmv
3234
* - :ref:`onemkl_sparse_optimize_trsv`
3335
- Optimize routine for trsv
36+
* - :ref:`onemkl_sparse_optimize_gemm`
37+
- Optimize routine for gemm
3438
* - :ref:`onemkl_sparse_gemv`
3539
- Sparse matrix-dense vector product using a general sparse matrix
3640
* - :ref:`onemkl_sparse_gemvdot`
@@ -56,10 +60,12 @@ Sparse BLAS
5660
releasematrixhandle
5761
setcsrstructure
5862
gemm
63+
gemmoptimize
5964
gemv
6065
gemvdot
6166
gemvoptimize
6267
symv
68+
symvoptimize
6369
trmv
6470
trmvoptimize
6571
trsv

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

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
.. SPDX-FileCopyrightText: 2023 Intel Corporation
2+
..
3+
.. SPDX-License-Identifier: CC-BY-4.0
4+
5+
.. _onemkl_sparse_optimize_symv:
6+
7+
optimize_symv
8+
=============
9+
10+
Performs internal optimizations for oneapi::mkl::sparse::symv by analyzing
11+
the matrix structure.
12+
13+
.. rubric:: Description and Assumptions
14+
15+
The oneapi::mkl::sparse::optimize_symv routine analyzes matrix structure
16+
and performs optimizations. Optimized data is then stored in
17+
the handle.
18+
19+
20+
.. rubric:: Syntax
21+
22+
.. code-block:: cpp
23+
24+
namespace oneapi::mkl::sparse {
25+
26+
sycl::event optimize_symv (sycl::queue &queue,
27+
oneapi::mkl::uplo uplo_val,
28+
oneapi::mkl::sparse::matrix_handle_t handle,
29+
const std::vector<sycl::event> &dependencies = {});
30+
}
31+
32+
.. container:: section
33+
34+
35+
.. rubric:: Input Parameters
36+
37+
38+
queue
39+
Specifies the SYCL command queue which will be used for SYCL
40+
kernels execution.
41+
42+
43+
uplo_val
44+
Specifies which part is to be processed. The possible options are
45+
described in :ref:`onemkl_enum_uplo` enum class.
46+
47+
48+
handle
49+
Handle to object containing sparse matrix and other internal
50+
data. Created using the
51+
oneapi::mkl::sparse::set_csr_data routine.
52+
53+
54+
dependencies
55+
List of events that oneapi::mkl::sparse::optimize_symv routine depends on.
56+
57+
58+
.. container:: section
59+
60+
.. rubric:: Output Parameters
61+
:class: sectiontitle
62+
63+
handle
64+
Handle might be updated with some internal optimized data by this routine.
65+
66+
.. container:: section
67+
68+
.. rubric:: Throws
69+
:class: sectiontitle
70+
71+
This routine shall throw the following exceptions if the associated condition is detected.
72+
An implementation may throw additional implementation-specific exception(s)
73+
in case of error conditions not covered here.
74+
75+
| :ref:`oneapi::mkl::computation_error<onemkl_exception_computation_error>`
76+
| :ref:`oneapi::mkl::device_bad_alloc<onemkl_exception_device_bad_alloc>`
77+
| :ref:`oneapi::mkl::host_bad_alloc<onemkl_exception_host_bad_alloc>`
78+
| :ref:`oneapi::mkl::invalid_argument<onemkl_exception_invalid_argument>`
79+
| :ref:`oneapi::mkl::unimplemented<onemkl_exception_unimplemented>`
80+
| :ref:`oneapi::mkl::uninitialized<onemkl_exception_uninitialized>`
81+
| :ref:`oneapi::mkl::unsupported_device<onemkl_exception_unsupported_device>`
82+
83+
.. container:: section
84+
85+
.. rubric:: Return Values
86+
:class: sectiontitle
87+
88+
Output event that can be waited upon or added as a
89+
dependency for the completion of optimize_symv routine.
90+
91+
92+
.. container:: familylinks
93+
94+
95+
.. container:: parentlink
96+
97+
98+
**Parent topic:** :ref:`onemkl_spblas`

0 commit comments

Comments
 (0)