Skip to content

Commit d06919c

Browse files
andrewtbarkerandrewtbarker
authored
[docs] [BLAS] make documentation consistent with oneAPI spec (#145)
* [docs] [BLAS] make documentation consistent with oneAPI spec * [docs] [BLAS] remove not-yet-implemented span API from docs
1 parent 1c8c47a commit d06919c

File tree

13 files changed

+2603
-8
lines changed

13 files changed

+2603
-8
lines changed

‎docs/domains/blas/axpby.rst‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
.. _onemkl_blas_axpby:
2+
3+
axpby
4+
=====
5+
6+
Computes a vector-scalar product added to a scaled-vector.
7+
8+
.. _onemkl_blas_axpby_description:
9+
10+
.. rubric:: Description
11+
12+
The ``axpby`` routines compute two scalar-vector product and add them:
13+
14+
.. math::
15+
16+
y \leftarrow beta * y + alpha * x
17+
18+
where ``x`` and ``y`` are vectors of ``n`` elements and ``alpha`` and ``beta`` are scalars.
19+
20+
``axpby`` supports the following precisions.
21+
22+
.. list-table::
23+
:header-rows: 1
24+
25+
* - T
26+
* - ``float``
27+
* - ``double``
28+
* - ``std::complex<float>``
29+
* - ``std::complex<double>``
30+
31+
.. _onemkl_blas_axpby_buffer:
32+
33+
axpby (Buffer Version)
34+
----------------------
35+
36+
.. rubric:: Syntax
37+
38+
.. code-block:: cpp
39+
40+
namespace oneapi::mkl::blas::column_major {
41+
void axpby(sycl::queue &queue,
42+
std::int64_t n,
43+
T alpha,
44+
sycl::buffer<T,1> &x, std::int64_t incx,
45+
T beta,
46+
sycl::buffer<T,1> &y, std::int64_t incy)
47+
}
48+
.. code-block:: cpp
49+
50+
namespace oneapi::mkl::blas::row_major {
51+
void axpby(sycl::queue &queue,
52+
std::int64_t n,
53+
T alpha,
54+
sycl::buffer<T,1> &x, std::int64_t incx,
55+
T beta,
56+
sycl::buffer<T,1> &y, std::int64_t incy)
57+
}
58+
59+
.. container:: section
60+
61+
.. rubric:: Input Parameters
62+
63+
queue
64+
The queue where the routine should be executed.
65+
66+
n
67+
Number of elements in vector ``x`` and ``y``.
68+
69+
alpha
70+
Specifies the scalar ``alpha``.
71+
72+
x
73+
Buffer holding input vector ``x``. The buffer must be of size at least
74+
(1 + (``n`` – 1)*abs(``incx``)). See :ref:`matrix-storage` for
75+
more details.
76+
77+
incx
78+
Stride between two consecutive elements of the ``x`` vector.
79+
80+
beta
81+
Specifies the scalar ``beta``.
82+
83+
y
84+
Buffer holding input vector ``y``. The buffer must be of size at least
85+
(1 + (``n`` – 1)*abs(``incy``)). See :ref:`matrix-storage` for
86+
more details.
87+
88+
incy
89+
Stride between two consecutive elements of the ``y`` vector.
90+
91+
.. container:: section
92+
93+
.. rubric:: Output Parameters
94+
95+
y
96+
Buffer holding the updated vector ``y``.
97+
98+
99+
.. _onemkl_blas_axpby_usm:
100+
101+
axpby (USM Version)
102+
-------------------
103+
104+
.. rubric:: Syntax
105+
106+
.. code-block:: cpp
107+
108+
namespace oneapi::mkl::blas::column_major {
109+
sycl::event axpby(sycl::queue &queue,
110+
std::int64_t n,
111+
T alpha,
112+
const T *x, std::int64_t incx,
113+
const T beta,
114+
T *y, std::int64_t incy,
115+
const std::vector<sycl::event> &dependencies = {})
116+
}
117+
.. code-block:: cpp
118+
119+
namespace oneapi::mkl::blas::row_major {
120+
sycl::event axpby(sycl::queue &queue,
121+
std::int64_t n,
122+
T alpha,
123+
const T *x, std::int64_t incx,
124+
const T beta,
125+
T *y, std::int64_t incy,
126+
const std::vector<sycl::event> &dependencies = {})
127+
}
128+
129+
.. container:: section
130+
131+
.. rubric:: Input Parameters
132+
133+
queue
134+
The queue where the routine should be executed.
135+
136+
n
137+
Number of elements in vector ``x`` and ``y``.
138+
139+
alpha
140+
Specifies the scalar alpha.
141+
142+
beta
143+
Specifies the scalar beta.
144+
145+
x
146+
Pointer to the input vector ``x``. The allocated memory must be
147+
of size at least (1 + (``n`` – 1)*abs(``incx``)). See
148+
:ref:`matrix-storage` for more details.
149+
150+
incx
151+
Stride between consecutive elements of the ``x`` vector.
152+
153+
y
154+
Pointer to the input vector ``y``. The allocated memory must be
155+
of size at least (1 + (``n`` – 1)*abs(``incy``)). See
156+
:ref:`matrix-storage` for more details.
157+
158+
incy
159+
Stride between consecutive elements of the ``y`` vector.
160+
161+
dependencies
162+
List of events to wait for before starting computation, if any.
163+
If omitted, defaults to no dependencies.
164+
165+
.. container:: section
166+
167+
.. rubric:: Output Parameters
168+
169+
y
170+
Array holding the updated vector ``y``.
171+
172+
.. container:: section
173+
174+
.. rubric:: Return Values
175+
176+
Output event to wait on to ensure computation is complete.
177+
178+
179+
**Parent topic:** :ref:`blas-like-extensions`
180+

‎docs/domains/blas/axpy_batch.rst‎

Lines changed: 105 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,109 @@ operation adds a scalar-vector product to a vector.
2424
* - ``std::complex<float>``
2525
* - ``std::complex<double>``
2626

27+
.. _onemkl_blas_axpy_batch_buffer:
28+
29+
axpy_batch (Buffer Version)
30+
---------------------------
31+
32+
.. rubric:: Description
33+
34+
The buffer version of ``axpy_batch`` supports only the strided API.
35+
36+
The strided API operation is defined as:
37+
::
38+
39+
for i = 0 … batch_size – 1
40+
X and Y are vectors at offset i * stridex, i * stridey in x and y
41+
Y := alpha * X + Y
42+
end for
43+
44+
where:
45+
46+
``alpha`` is scalar,
47+
48+
``X`` and ``Y`` are vectors.
49+
50+
**Strided API**
51+
52+
.. rubric:: Syntax
53+
54+
.. code-block:: cpp
55+
56+
namespace oneapi::mkl::blas::column_major {
57+
void axpy_batch(sycl::queue &queue,
58+
std::int64_t n,
59+
T alpha,
60+
sycl::buffer<T,
61+
1> &x,
62+
std::int64_t incx,
63+
std::int64_t stridex,
64+
sycl::buffer<T,
65+
1> &y,
66+
std::int64_t incy,
67+
std::int64_t stridey,
68+
std::int64_t batch_size)
69+
}
70+
.. code-block:: cpp
71+
72+
namespace oneapi::mkl::blas::row_major {
73+
void axpy_batch(sycl::queue &queue,
74+
std::int64_t n,
75+
T alpha,
76+
sycl::buffer<T,
77+
1> &x,
78+
std::int64_t incx,
79+
std::int64_t stridex,
80+
sycl::buffer<T,
81+
1> &y,
82+
std::int64_t incy,
83+
std::int64_t stridey,
84+
std::int64_t batch_size)
85+
}
86+
87+
.. container:: section
88+
89+
.. rubric:: Input Parameters
90+
91+
queue
92+
The queue where the routine should be executed.
93+
94+
n
95+
Number of elements in ``X`` and ``Y``.
96+
97+
alpha
98+
Specifies the scalar ``alpha``.
99+
100+
x
101+
Buffer holding input vectors ``X`` with size ``stridex`` * ``batch_size``.
102+
103+
incx
104+
Stride of vector ``X``.
105+
106+
stridex
107+
Stride between different ``X`` vectors.
108+
109+
y
110+
Buffer holding input/output vectors ``Y`` with size ``stridey`` * ``batch_size``.
111+
112+
incy
113+
Stride of vector ``Y``.
114+
115+
stridey
116+
Stride between different ``Y`` vectors.
117+
118+
batch_size
119+
Specifies the number of ``axpy`` operations to perform.
120+
121+
.. container:: section
122+
123+
.. rubric:: Output Parameters
124+
125+
y
126+
Output buffer, overwritten by ``batch_size`` ``axpy`` operations of the form
127+
``alpha`` * ``X`` + ``Y``.
128+
129+
27130
.. _onemkl_blas_axpy_batch_usm:
28131

29132
axpy_batch (USM Version)
@@ -117,15 +220,15 @@ The total number of vectors in ``x`` and ``y`` are given by the ``batch_size`` p
117220

118221
x
119222
Array of pointers to input vectors ``X`` with size ``total_batch_count``.
120-
The size of array allocated for the ``X`` vector of the group ``i`` must be at least (1 + (``n[i]`` – 1)*abs(``incx[i]``))``.
223+
The size of array allocated for the ``X`` vector of the group ``i`` must be at least (1 + (``n[i]`` – 1)*abs(``incx[i]``)).
121224
See :ref:`matrix-storage` for more details.
122225

123226
incx
124227
Array of ``group_count`` integers. ``incx[i]`` specifies the stride of vector ``X`` in group ``i``.
125228

126229
y
127230
Array of pointers to input/output vectors ``Y`` with size ``total_batch_count``.
128-
The size of array allocated for the ``Y`` vector of the group ``i`` must be at least (1 + (``n[i]`` – 1)*abs(``incy[i]``))``.
231+
The size of array allocated for the ``Y`` vector of the group ``i`` must be at least (1 + (``n[i]`` – 1)*abs(``incy[i]``)).
129232
See :ref:`matrix-storage` for more details.
130233

131234
incy

‎docs/domains/blas/blas-like-extensions.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,12 @@ BLAS-like Extensions
4242
:hidden:
4343

4444
axpy_batch
45+
axpby
46+
copy_batch
47+
dgmm_batch
4548
gemm_batch
49+
gemv_batch
50+
syrk_batch
4651
trsm_batch
4752
gemmt
4853
gemm_bias

‎docs/domains/blas/blas.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,5 @@ oneMKL provides DPC++ interfaces to the Basic Linear Algebra Subprograms (BLAS)
1313
blas-level-3-routines.rst
1414
blas-like-extensions.rst
1515

16+
17+
**Parent topic:** :ref:`onemkl_dense_linear_algebra`

0 commit comments

Comments
 (0)