.. _oneapi-mkl-sparse-trmv:

oneapi::mkl::sparse::trmv
=========================


Computes a sparse matrix-dense vector product over upper or lower
triangular parts of the 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::trmv`` routine computes a sparse matrix-dense vector product 
over a triangular part 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 sparse triangular matrix of 
size ``m`` rows by ``m`` columns and :math:`x` and :math:`y` are dense vectors of size ``m``.  
The operation :math:`\text{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}

For a given matrix decomposition into lower, diagonal and upper parts :math:`A = L + D + U`,
the triangular matrix vector product with one of ``oneapi::mkl::uplo::lower`` or 
``oneapi::mkl::uplo::upper`` selected will perform the appropriate matrix product using 
respectively :math:`\text{op}(L+D)` or :math:`\text{op}(D+U)` for ``oneapi::mkl::diag::nonunit`` 
or if using ``oneapi::mkl::diag::unit``, will perform the appropriate matrix product for
:math:`\text{op}(L+I)` or :math:`\text{op}(I+U)` where :math:`I` is the identity matrix. 


API
***

Syntax
------

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


**Using SYCL buffers:**

.. code-block:: cpp

    namespace oneapi::mkl::sparse {
        void trmv (
            cl::sycl::queue &queue,
            oneapi::mkl::uplo uplo_flag,
            oneapi::mkl::transpose transpose_flag,
            oneapi::mkl::diag diag_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 trmv(
            cl::sycl::queue &queue,
            oneapi::mkl::uplo uplo_flag,
            oneapi::mkl::transpose transpose_flag,
            oneapi::mkl::diag
            diag_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 of the matrix is to be processed.

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

      * -  ``oneapi::mkl::uplo::lower``
        -  The lower triangular matrix part is processed.
      * -  ``oneapi::mkl::uplo::upper``
        -  The upper triangular matrix part is processed.

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``.


diag_flag
   Specifies if the diagonal used for computations is unit or not.

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

      * -  ``oneapi::mkl::diag::nonunit``
        -  Diagonal elements might not be equal to one.
      * -  ``oneapi::mkl::diag::unit``
        -  Diagonal elements are equal to one.

   .. note::
        Currently, the only supported case for ``diag_flag`` is ``oneapi::mkl::diag::nonunit``.

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 ``transpose_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::trmv`` 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 ``trmv`` routine.



Examples
********

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

.. code-block::

   examples/dpcpp/sparse_blas/source/sparse_trmv.cpp