.. _gebrd:

gebrd
=====


Reduces a general matrix to bidiagonal form. This routine belongs to the
``oneapi::mkl::lapack`` namespace.


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

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

The routine reduces a general ``m``-by-``n`` matrix ``A`` to a
bidiagonal matrix ``B`` by an orthogonal (unitary) transformation.


If ``m≥n``, the reduction is given by

.. math::

   A =
   QBP^H =
   \left(
      \begin{array}{ccc}
      B_1 \\ 0
      \end{array}
   \right) P^H =
   Q_1 B_1 P_H

where ``B``\ :sub:`1` is an ``n``-by-``n`` upper diagonal matrix,
``Q`` and ``P`` are orthogonal or, for a complex ``A``, unitary
matrices; ``Q``\ :sub:`1` consists of the first ``n`` columns of
``Q``.


If ``m < n``, the reduction is given by


``A = Q*B*PH = Q*(B10)*PH = Q1*B1*P1H``,


where ``B``\ :sub:`1` is an ``m``-by-``m`` lower diagonal matrix,
``Q`` and ``P`` are orthogonal or, for a complex ``A``, unitary
matrices; ``P``\ :sub:`1` consists of the first ``m`` columns of
``P``.


The routine does not form the matrices ``Q`` and ``P`` explicitly,
but represents them as products of elementary reflectors. Routines
are provided to work with the matrices ``Q`` and ``P`` in this
representation:


If the matrix ``A`` is real,


-  to compute ``Q`` and ``P`` explicitly, call
   :ref:`orgbr`.


If the matrix ``A`` is complex,


-  to compute ``Q`` and ``P`` explicitly, call
   :ref:`ungbr`.


API
***


Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::lapack {
     void gebrd(cl::sycl::queue &queue,
     std::int64_t m, std::int64_t n,
     cl::sycl::buffer<T,1> &a, std::int64_t lda,
     cl::sycl::buffer<realT,1> &d, cl::sycl::buffer<realT,1> &e, cl::sycl::buffer<T,1> &tauq, cl::sycl::buffer<T,1> &taup, cl::sycl::buffer<T,1> &scratchpad, std::int64_t scratchpad_size)
   }

``gebrd`` supports the following precision and devices.

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

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


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
   The buffer holding matrix ``A``. The second dimension of ``a``
   must be at least ``max(1, m)``.


lda
   The leading dimension of ``a``.


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


scratchpad_size
   Size of scratchpad memory as a number offloating point elements of
   typeT.


   Size should not be less then the valuereturned by the
   :ref:`gebrd_scratchpad_size`\ function.


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

a
   If ``m≥n``, the diagonal and first super-diagonal of a are
   overwritten by the upper bidiagonal matrix ``B``. The elements
   below the diagonal, with the buffer tauq, represent the orthogonal
   matrix ``Q`` as a product of elementary reflectors, and the
   elements above the first superdiagonal, with the buffer taup,
   represent the orthogonal matrix ``P`` as a product of elementary
   reflectors.


   If ``m<n``, the diagonal and first sub-diagonal of a are
   overwritten by the lower bidiagonal matrix ``B``. The elements
   below the first subdiagonal, with the buffer tauq, represent the
   orthogonal matrix ``Q`` as a product of elementary reflectors, and
   the elements above the diagonal, with the buffer taup, represent
   the orthogonal matrix ``P`` as a product of elementary reflectors.


d
   Buffer holding array of size at least ``max(1, min(m,n))``.
   Contains the diagonal elements of ``B``.


e
   Buffer holding array of size at least ``max(1, min(m,n) - 1)``.
   Contains the off-diagonal elements of ``B``.


tauq
   Buffer holding array of size at least ``max(1, min(m, n))``. The
   scalar factors of the elementary reflectors which represent the
   orthogonal or unitary matrix ``Q``.


taup
   Buffer holding array of size at least ``max(1, min(m, n))``. The
   scalar factors of the elementary reflectors which represent the
   orthogonal or unitary matrix ``P``.


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