.. _ungtr-usm-version:

ungtr (USM Version)
===================


Generates the complex unitary matrix Q determined by the ``hetrd`` (USM
Version) function. This routine belongs to the ``oneapi::mkl::lapack`` namespace.


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

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

The routine explicitly generates the ``n``-by-``n`` unitary matrix
``Q`` formed by the :ref:`hetrd-usm-version` when
reducing a complex Hermitian matrix ``A`` to tridiagonal form:
``A = Q*T*QT``. Use this routine after a call to :ref:`hetrd-usm-version`
function.


API
***


Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::lapack {
     cl::sycl::event ungtr(cl::sycl::queue &queue,
     mkl::uplo uplo,
     std::int64_t n,
     T *a,
     std::int64_t lda,
     T *tau,
     T *tau,
     T *scratchpad,
     std::int64_t scratchpad_size,
     const std::vector<cl::sycl::event> &events = {})
   }

``ungtr`` (USM version) supports the following precision and devices.

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

   * -  T
     -  Devices Supported
   * -  ``float``
     -  Host and CPU
   * -  ``double``
     -  Host and CPU


Input Parameters
----------------

queue
   Device queue where calculations will be performed.

uplo
   Must be uplo::upper or uplo::lower. Uses the same uplo as supplied
   to the :ref:`hetrd-usm-version`
   function.


n
   The order of matrix ``Q`` (``0≤n``).


a
   The pointer ``a`` returned by the :ref:`hetrd-usm-version`
   function. The second dimension of ``a`` must be at least
   ``max(1, n)``.


lda
   The leading dimension of ``a`` (``n≤lda``).


tau
   The pointer tau returned by the :ref:`hetrd-usm-version`
   function. The dimension of tau must be at least ``max(1,n-1)``.


scratchpad
   Pointer to scratchpad memory to be used by the routine for storing
   intermediate results.


scratchpad_size
   Size of scratchpad memory as a number of floating point elements
   of type ``T``. Size should not be less than the value returned by
   the
   :ref:`ungtr_scratchpad_size`
   function.


events
   List of events to wait for before starting computation. Defaults
   to empty list.


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

a
   Overwritten by the unitary matrix ``Q``.


Exceptions
----------

.. tabularcolumns:: |\Y{0.3}|\Y{0.7}|

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

   * - Exception
     - Description

   * -     ``mkl::lapack::exception``
     -     This exception is thrown when problems occur during    calculations. You can obtain the info code of the problem using the   info() method of the exception object:

           If   ``info = -i``, the ``i``-th parameter had an illegal   value.

           If ``info`` is equal to the value passed as   scratchpad size, and detail() returns non-zero, then the passed   scratchpad has an insufficient size, and the required size should not   be less than the value returned by the detail() method of the   exception object.


Return Values
-------------

Output event to wait on to ensure computation is complete.