.. _oneapi-mkl-sparse-trsv:

oneapi::mkl::sparse::trsv
=========================

Solves a system of linear equations for a triangular sparse 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::trsv`` routine solves the sparse triangular system 

.. math::

      \text{op}(A)\cdot y =  x

where :math:`A` is a sparse triangular matrix of size :math:`m` rows by :math:`m` 
columns and :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}

The dense vectors :math:`x` and :math:`y` should be of length at least :math:`m`. The vector
:math:`x` is input right hand side data and math:`y` is the resulting output vector.

For a given matrix decomposition into lower, diagonal and upper parts :math:`A = L + D + U`,
the triangular solve with one of ``oneapi::mkl::uplo::lower`` or ``oneapi::mkl::uplo::upper`` 
selected will perform the appropriate forward or backward substitution 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 forward or backward substitution 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 trsv (
            cl::sycl::queue &queue,
            oneapi::mkl::uplo uplo_flag,
            oneapi::mkl::transpose transpose_flag,
            oneapi::mkl::diag diag_flag,
            oneapi::mkl::sparse::matrix_handle_t handle,
            cl::sycl::buffer<fp, 1> &x,
            cl::sycl::buffer<fp, 1> &y)
    }

**Using USM pointers:**


.. code-block:: cpp

    namespace oneapi::mkl::sparse {
        cl::sycl::event trsv(
            cl::sycl::queue &queue,
            oneapi::mkl::uplo uplo_flag,
            oneapi::mkl::transpose transpose_flag,
            oneapi::mkl::diag diag_flag,
            oneapi::mkl::sparse::matrix_handle_t handle,
            fp *x,
            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 based on provided matrix data.

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

      * -  ``oneapi::mkl::diag::nonunit``
        -  Diagonal elements are used as provided in the sparse matrix.
      * -  ``oneapi::mkl::diag::unit``
        -  The value of one is substituted for the diagonal elements in the triangular solve algorithm.

   .. note::
        If ``oneapi::mkl::diag::nonunit`` is selected, all diagonal values must be present in the 
        sparse matrix.  This is not necessary for the ``oneapi::mkl::diag::unit`` case.


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. It is the input vector ``x``


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



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

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.  The solution of the triangular
   solve is filled into this array.



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

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



Examples
********

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

.. code-block::

   examples/dpcpp/sparse_blas/source/sparse_trsv.cpp

.. code-block::

   examples/dpcpp/sparse_blas/source/sparse_trsv_usm.cpp