.. _oneapi-mkl-sparse-gemv:

oneapi::mkl::sparse::gemv
=========================


Computes a sparse matrix-dense vector product.


.. contents::
    :local:
    :depth: 1

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

.. note::
   Refer to :ref:`supported-types` for a list of supported ``<fp>`` and ``<intType>`` and 
   refer to :ref:`exceptions` for a detailed description of the exceptions thrown.

The ``oneapi::mkl::sparse::gemv`` routine computes a sparse matrix-dense vector product defined as

.. math::

    y \leftarrow \alpha \cdot\text{op}(A)\cdot x + \beta\cdot y


where :math:`\alpha` and :math:`\beta` are scalars, :math:`A` is a general sparse matrix of 
dimensions ``num_rows`` rows and ``num_cols`` columns and :math:`op()` is a matrix modifier:

.. math::

    \text{op}(A) = \begin{cases} A,& \text{ oneapi::mkl::transpose::nontrans}\\ A^{T},& \text{ oneapi::mkl::transpose::trans}\\A^{H},& \text{ oneapi::mkl::transpose::conjtrans} \end{cases}

The dense vectors :math:`x` and :math:`y` are appropriately sized based on matrix product 
dimensions of :math:`\text{op}(A)`.



API
***

Syntax
------

.. note::
   Currently, complex types are not supported.


**Using SYCL buffers:**


.. code-block:: cpp

    namespace oneapi::mkl::sparse {
        void gemv (
            cl::sycl::queue &queue,
            oneapi::mkl::transpose transpose_flag,
            const fp alpha,
            oneapi::mkl::sparse::matrix_handle_t handle,
            cl::sycl::buffer<fp, 1> &x,
            const fp beta,
            cl::sycl::buffer<fp, 1> &y)
    }


**Using USM pointers:**


.. code-block:: cpp

    namespace oneapi::mkl::sparse {
        cl::sycl::event gemv (
            cl::sycl::queue &queue,
            oneapi::mkl::transpose transpose_flag,
            const fp alpha,
            oneapi::mkl::sparse::matrix_handle_t handle,
            const fp *x,
            fp beta,
            fp *y,
            const std::vector<cl::sycl::event> &dependencies= {})
    }



Include Files
-------------

-  oneapi/mkl/spblas.hpp


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

queue
   Specifies the SYCL command queue which will be used for SYCL
   kernels execution.


transpose_flag
   Specifies operation ``op()`` on input matrix.

   .. list-table::
      :header-rows: 0

      * -  ``oneapi::mkl::transpose::nontrans``
        -  Non-transpose, :math:`\text{op}(A) = A`.
      * -  ``oneapi::mkl::transpose::trans``
        -  Transpose, :math:`\text{op}(A) = A^{T}`.
      * -  ``oneapi::mkl::transpose::conjtrans``
        -  Conjugate transpose, :math:`\text{op}(A) = A^{H}`.
 
   .. note::
      Currently, the only supported case for ``operation`` is ``oneapi::mkl::transpose::nontrans``.


alpha
   Specifies the scalar, :math:`\alpha`.


handle
   Handle to object containing sparse matrix and other internal data.
   Created using one of the
   ``oneapi::mkl::sparse::set_<sparse_matrix_type>_data`` routines.

   .. note::
      Currently, the only supported case for ``<sparse_matrix_type>`` is csr.


x
   SYCL buffer or device-accessible USM pointer of size at least
   equal to the number of columns of input matrix if ``transpse_flag`` =
   ``oneapi::mkl::transpose::nontrans`` and at least the number of rows
   of input matrix otherwise.


beta
   Specifies the scalar, :math:`\beta`.


y
   SYCL buffer or device-accessible USM pointer of size at least
   equal to the number of rows of the input matrix if ``transpose_flag`` =
   ``oneapi::mkl::transpose::nontrans`` and at least the number of
   columns of the input matrix otherwise.


dependencies
   A vector of type ``std::vector<cl::sycl::event>``
   containing the list of events that the ``oneapi::mkl::sparse::gemv``
   routine depends on.


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

y
   Overwritten by the updated vector :math:`y`.


Return Values (USM Only)
------------------------

cl::sycl::event
   SYCL event which can be waited upon or added as a dependency for
   the completion of the ``gemv`` routine.


Examples
********

An example of how to use ``oneapi::mkl::sparse::gemv`` with SYCL buffers
or USM pointers can be found in the |O-MKL| installation directory,
under:


.. code-block::

   examples/dpcpp/sparse_blas/source/sparse_gemv.cpp


.. code-block::

   examples/dpcpp/sparse_blas/source/sparse_gemv_usm.cpp