.. _oneapi-mkl-sparse-optimize_gemv:

oneapi::mkl::sparse::optimize_gemv
==================================

Performs internal optimizations for oneapi::mkl::sparse::gemv by
analyzing the matrix structure.


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

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

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

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


API
***

Syntax
------

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


**Using SYCL buffers:**

.. code-block:: cpp

    namespace oneapi::mkl::sparse {    
        void optimize_gemv (
            cl::sycl::queue &queue,
            oneapi::mkl::transpose transpose_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_gemv (
            cl::sycl::queue &queue,
            oneapi::mkl::transpose transpose_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.


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

   .. list-table::
      :header-rows: 1

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

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