.. _gerqf-usm-version:

gerqf (USM Version)
===================


Computes the RQ factorization of a general m-by-n matrix . This routine
belongs to the ``oneapi::mkl::lapack`` namespace.


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

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

The routine forms the ``RQ`` factorization of a general
``m``-by-``n`` matrix ``A``. No pivoting is performed.


The routine does not form the matrix ``Q`` explicitly. Instead, ``Q``
is represented as a product of min(``m``, ``n``) elementary
reflectors. Routines are provided to work with ``Q`` in this
representation.


API
***


Syntax
------

.. code-block:: cpp

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

``gerqf`` (USM version) supports the following precisions and
devices:

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

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


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

queue
   Device queue where calculations will be performed.


m
   The number of rows in the matrix ``A`` (``0≤m``).


n
   The number of columns in the matrix ``A`` (``0≤n``).


a
   Pointer to the memory holding input matrix ``A``. The second
   dimension of ``a`` must be at least ``max(1, n)``.


lda
   The leading dimension of ``a``, at least ``max(1, m)``.


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:`gerqf_scratchpad_size` function.


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


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

a
   Overwritten by the factorization data as follows:


   if ``m ≤ n``, the upper triangle of the subarray
   ``a(1:m, n-m+1:n )`` contains the ``m``-by-``m`` upper triangular
   matrix ``R``; if ``m ≥ n``, the elements on and above the
   (``m``-``n``)-th subdiagonal contain the ``m``-by-``n`` upper
   trapezoidal matrix ``R``


   In both cases, the remaining elements, with the array\ ``tau``,
   represent the orthogonal/unitary matrix ``Q`` as a product of
   ``min(m,n)`` elementary reflectors.


tau
   Array, size at least ``min(m,n)``.


   Contains scalars that define elementary reflectors for the matrix
   ``Q`` in its decomposition in a product of elementary reflectors.


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   get_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 get_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 get_detail() method of the   exception object.


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

Output event to wait on to ensure computation is complete.