.. _oneapi-mkl-sparse-symv:

oneapi::mkl::sparse::symv
=========================


Computes a sparse matrix-dense vector product for a symmetric matrix
built from the lower or upper triangular of the input matrix.


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

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

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


The ``oneapi::mkl::sparse::symv`` routine computes a sparse symmetric
matrix-dense vector product for a real symmetric matrix built from the
lower or upper triangular portion of the input matrix :math:`A` defined as

.. math::

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

where :math:`\alpha` and :math:`\beta` are scalars, :math:`A` is a real-valued square sparse matrix 
of dimension :math:`m` rows and columns, :math:`\text{sym}()` is a matrix modifier which symmetrizes 
the matrix according to the ``oneapi::mkl::uplo`` value  and :math:`x` and :math:`y` are dense vectors.

For a given matrix decomposition into lower, diagonal and upper parts :math:`A = L+D+U`,
the ``symv`` routine with ``oneapi::mkl::uplo::lower`` selected will perform the  
matrix product with :math:`\text{sym}(A) = L+D+L^T`  and for ``oneapi::mkl::uplo::upper`` will 
perform the matrix product using :math:`\text{sym}(A) = U^T+D+U`.


API
***

Syntax
------

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


**Using SYCL buffers:**

.. code-block:: cpp

    namespace oneapi::mkl::sparse {
        void symv (
            cl::sycl::queue &queue,
            oneapi::mkl::uplo uplo_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 symv (
            cl::sycl::queue &queue,
            oneapi::mkl::uplo uplo_flag,
            const fp alpha,
            oneapi::mkl::sparse::matrix_handle_t handle,
            fp *x,
            const 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.


uplo_flag
   Specifies which part is to be processed.

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

      * -  ``oneapi::mkl::uplo::lower``
        -  The lower part is used for symmetric product.
      * -  ``oneapi::mkl::uplo::upper``
        -  The upper part is used for symmetric product.

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, :math:`m`, of input matrix.


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


y
   SYCL buffer or device-accessible USM pointer of size at least
   equal to the number of rows, :math:`m`, of the input matrix.


dependencies
   A vector of type ``std::vector<cl::sycl::event>``
   containing the list of events that the ``oneapi::mkl::sparse::symv`` 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 ``symv`` routine.


Examples
********

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

.. code-block:: console

   examples/dpcpp/sparse_blas/source/sparse_symv.cpp