.. _oneapi-mkl-sparse-optimize_trsv:

oneapi::mkl::sparse::optimize_trsv
==================================


Performs internal optimizations for ``oneapi::mkl::sparse::trsv`` by
analyzing the provided matrix structure and operation parameters.


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

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

The ``oneapi::mkl::sparse::optimize_trsv`` routine analyzes matrix structure and performs optimizations. Optimized data is then stored in the matrix handle.

.. note::
   Refer to :ref:`Exceptions <exceptions>` for a detailed description of the exceptions thrown. 



API
***

Syntax
------

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


**Using SYCL buffers:**

.. code-block:: cpp

    namespace oneapi::mkl::sparse {
        void optimize_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)
    }

**Using USM pointers:**

.. note::
   Currently, the USM API might be a blocking call.


.. code-block:: cpp

    namespace oneapi::mkl::sparse {
        cl::sycl::event optimize_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,
            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, ``op(A)`` = ``A``.
      * -  ``oneapi::mkl::transpose::trans``
        -  Transpose, ``op(A)`` = ``A``\ :sup:`T`.
      * -  ``oneapi::mkl::transpose::conjtrans``
        -  Conjugate transpose, ``op(A)`` = ``A``\ :sup:`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.


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.

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


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

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