.. _onemkl_blas_axpby:

axpby
=====

Computes a vector-scalar product added to a scaled-vector.

Description
***********

The ``axpby`` routines compute two scalar-vector products and add them:

.. math::

       y \leftarrow beta * y + alpha * x 

where:

- ``x`` and ``y`` are vectors of ``n`` elements

- ``alpha`` and ``beta`` are scalars

``axpby`` supports the following precisions:

.. list-table::
   :header-rows: 1

   * -  T
   * -  ``float``
   * -  ``double``
   * -  ``std::complex<float>``
   * -  ``std::complex<double>``

axpby (Buffer Version)
**********************

Syntax
------

.. code-block:: cpp

    namespace oneapi::mkl::blas::column_major {
      void axpby(sycl::queue &queue,
                 std::int64_t n, 
                 T alpha,
                 sycl::buffer<T,1> &x, 
                 std::int64_t incx,
                 T beta,
                 sycl::buffer<T,1> &y, 
                 std::int64_t incy);
      }

.. code-block:: cpp

    namespace oneapi::mkl::blas::row_major {
      void axpby(sycl::queue &queue,
                 std::int64_t n, 
                 T alpha,
                 sycl::buffer<T,1> &x, 
                 std::int64_t incx,
                 T beta,
                 sycl::buffer<T,1> &y, 
                 std::int64_t incy);
      }

Input Parameters
----------------

queue
   The queue where the routine should be executed.

n
   Number of elements in vectors ``x`` and ``y``.

alpha
   Specifies the scalar ``alpha``.

x
   Buffer holding input vector ``x``. Size of the buffer must be at least 1 + (``n`` - 1)*abs(``incx``)). See :ref:`matrix-storage` for more details.

incx
   Stride between two consecutive elements of vector ``x``.

beta
   Specifies the scalar ``beta``.

y
   Buffer holding input vector ``y``. Size of the buffer must be at least 1 + (``n`` - 1)*abs(``incy``)). See :ref:`matrix-storage` for more details.

incy
   Stride between two consecutive elements of vector ``y``.

Output Parameters
-----------------

y
   Buffer holding updated vector ``y``.


axpby (USM Version)
*******************

Syntax
------

.. code-block:: cpp

    namespace oneapi::mkl::blas::column_major {
      sycl::event axpby(sycl::queue &queue,
                        std::int64_t n, 
                        T alpha,
                        const T *x, 
                        std::int64_t incx,
                        T beta,
                        T *y, 
                        std::int64_t incy,
                        const std::vector<event> &dependencies = {});
      }

.. code-block:: cpp

    namespace oneapi::mkl::blas::row_major {
      sycl::event axpby(sycl::queue &queue,
                        std::int64_t n, 
                        T alpha,
                        const T *x, 
                        std::int64_t incx,
                        T beta,
                        T *y, 
                        std::int64_t incy,
                        const std::vector<event> &dependencies = {});
      }

Input Parameters
----------------

queue
   The queue where the routine should be executed.

n
   Number of elements in vectors ``x`` and ``y``.

alpha
   Specifies the scalar ``alpha``.

x
   Pointer to the input vector ``x``. Size of the array must be at least 1 + (``n`` - 1)*abs(``incx``)). See :ref:`matrix-storage` for more details.

incx
   Stride between two consecutive elements of vector ``x``.

beta
   Specifies the scalar ``beta``.

y
   Pointer to the input vector ``y``. Size of the array must be at least 1 + (``n`` - 1)*abs(``incy``)). See :ref:`matrix-storage` for more details.

incy
   Stride between two consecutive elements of vector ``y``.

dependencies
   List of events to wait for before starting computation, if any. If omitted, defaults to no dependencies.

Output Parameters
-----------------

y
   Array holding updated vector ``y``.

Return Values
-------------

Output event to wait on to ensure computation is complete.