.. _ungbr:

ungbr
=====

Generates the complex unitary matrix Q or P\ :sup:`t` determined by
:ref:`gebrd <gebrd>`. This routine belongs to the ``oneapi::mkl::lapack`` namespace.


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

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

The routine generates the whole or part of the unitary matrices ``Q``
and ``P``\ :sup:`H` formed by the routines
:ref:`gebrd`.
Use this routine after a call to ``cgebrd``/``zgebrd``. All valid
combinations of arguments are described in *Input Parameters*; in
most cases you need the following:


To compute the whole ``m``-by-``m`` matrix ``Q``, use:


.. code-block:: cpp

   ungbr(queue, generate::q, m, m, n, a, ...)

(note that the buffer\ ``a`` must have at least ``m`` columns).

To form the ``n`` leading columns of ``Q`` if ``m > n``, use:

.. code-block:: cpp

   ungbr(queue, generate::q, m, n, n, a, ...)

To compute the whole ``n``-by-``n`` matrix ``P``\ :sup:`T`, use:

.. code-block:: cpp

   ungbr(queue, generate::p, n, n, m, a, ...)

(note that the array ``a`` must have at least ``n`` rows).


To form the ``m`` leading rows of ``P``\ :sup:`T` if ``m < n``, use:

.. code-block:: cpp

   ungbr(queue, generate::p, m, n, m, a, ...)


API
***


Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::lapack {
     void ungbr(cl::sycl::queue &queue,
     mkl::generate gen,
     std::int64_t m,
     std::int64_t n,
     std::int64_t k,
     cl::sycl::buffer<T> &a,
     std::int64_t lda,
     cl::sycl::buffer<T> &tau,
     cl::sycl::buffer<T> &scratchpad,
     std::int64_t scratchpad_size)
   }

``ungbr`` supports the following precisions and devices:

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

   * -  T
     -  Devices supported
   * -  ``std::complex<float>``
     -  Host and CPU
   * -  ``std::complex<double>``
     -  Host and CPU


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

queue
   Device queue where calculations will be performed.


gen
   Must be ``generate::q`` or ``generate::p``.


   If gen\ ``= generate::q``, the routine generates the matrix ``Q``.


   If gen\ ``= generate::p``, the routine generates the matrix
   ``P``\ :sup:`T`.


m
   The number of rows in the matrix ``Q`` or ``P``\ :sup:`T` to be
   returned ``(0≤m)``.


   If gen\ ``= generate::q``, ``m ≥ n ≥ min(m, k)``.


   If gen\ ``= generate::p``, ``n ≥ m ≥ min(n, k)``.


n
   The number of rows in the matrix ``Q`` or ``P``\ :sup:`T` to be
   returned ``(0≤n)``. See m for constraints.


k
   If gen\ ``= generate::q``, the number of columns in the original
   ``m``-by-k matrix reduced by gebrd.


   If gen\ ``= generate::p``, the number of rows in the original
   ``k``-by-n matrix reduced by gebrd.


a
   Buffer holding memory returned by gebrd.


lda
   The leading dimension of a.


tau
   For gen\ ``= generate::q``, the array tauq is returned by the
   gebrd function.


   For gen\ ``= generate::p``, the array taup is returned by the
   gebrd function.


   The dimension of tau must be at least ``min(m,k)`` for
   ``gen = generate::q``, or ``min(n,k)`` for ``gen = generate::p``.


scratchpad
   Buffer holding 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:`ungbr_scratchpad_size`
   function.


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

a
   Overwritten by n leading columns of the m-by-m unitary matrix
   ``Q`` or ``P``\ :sup:`T`, (or the leading rows or columns thereof)
   as specified by gen, m, and n.


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.