.. _geqrf_batch-group-version:

geqrf_batch (Group Version)
===========================

Computes the batch of QR factorizations of a general m-by-n matrices.
This routine belongs to the ``oneapi::mkl::lapack`` namespace.


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

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

The routine forms the ``Q``\ :sub:`i`\ ``R``\ :sub:`i` factorizations
of a general ``m``-by-``n`` matrix ``A``\ :sub:`i`,
``iϵ{1...batch_size}``, where ``batch_size`` is a sum of all
parameter group sizes as provided with the ``group_sizes`` array. No
pivoting is performed during factorization.


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


Total number of problems to solve, ``batch_size``, is a sum of sizes
of all of the groups of parameters as provided by
``group_sizes``\ array.


API
***


Syntax
------


.. code-block:: cpp

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

Function supports the following precisions and devices.

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

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


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

queue
   Device queue where calculations will be performed.


m
   Array of ``group_count`` parameters m\ :sub:`g` parameters.


   Each of m\ :sub:`g` specifies the number of rows in the matrices
   ``A``\ :sub:`i` from array ``a``, belonging to group ``g``.


n
   Array of ``group_count`` parameters n\ :sub:`g` parameters.


   Each of n\ :sub:`g` specifies the number of columns in the
   matrices ``A``\ :sub:`i` from array ``a``, belonging to group
   ``g``.


a
   Array of ``batch_size`` pointers to input matrices
   ``A``\ :sub:`i`, each being of size
   ``lda``\ :sub:`g`\ \*\ ``n``\ :sub:`g` (``g`` is an index of group
   to which ``A``\ :sub:`i` belongs).


lda
   Array of ``group_count``\ ``lda``\ :sub:`g` parameters, each
   representing the leading dimensions of input matrices
   ``A``\ :sub:`i`, from array ``a``, belonging to group ``g``.


group_count
   Specifies the number of groups of parameters. Must be at least 0.


group_sizes
   Array of group_count integers. Array element with index ``g``
   specifies the number of problems to solve for each of the groups
   of parameters ``g``. So the total number of problems to solve,
   ``batch_size``, is a sum of all parameter group sizes.


scratchpad
   Scratchpad memory to be used by 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 then the value returned by
   :ref:`geqrf_batch_scratchpad_size-group-version`.


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


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

a
   Matrices pointed to by array ``a`` are overwritten by the
   factorization data as follows:


   The elements on and above the diagonal of ``A``\ :sub:`i` contain
   the ``min(mg,mng)``-by-``n``\ :sub:`g` upper trapezoidal matrices
   ``R``\ :sub:`i` (``R``\ :sub:`i` is upper triangular if
   ``mg≥ng``); the elements below the diagonal, with the array
   ``tau``\ :sub:`i`, present the orthogonal matrix ``Q``\ :sub:`i`
   as a rpoduct of ``min(mg,ng)`` elementary reflectors.


   Here, ``g`` is an index of parameters group corresponding to
   ``i``-th decomposition.


tau
   Array of pointers to store ``tau``\ :sub:`i`, each of size
   ``m``\ :sub:`g`,\ ``n``\ :sub:`g`, containing scalars that define
   elementary reflectors for the matrices ``Q``\ :sub:`i` in its
   decomposition in a product of elementary reflectors.


   Here, ``g`` is an index of parameters group corresponding to
   ``i``-th decomposition.


Exceptions
----------

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

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

   * - Exception
     - Description

   * -     ``mkl::lapack::batch_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 = -n``, the ``n``-th parameter had an illegal   value.

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




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

Output event to wait on to ensure computation is complete.