.. _hetrf:

hetrf
=====

Computes the Bunch-Kaufman factorization of a complex Hermitian matrix.
This routine belongs to the ``oneapi::mkl::lapack`` namespace.


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

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

The routine computes the factorization of a complex Hermitian matrix
``A``\ using the Bunch-Kaufman diagonal pivoting method:

-  if ``uplo='U'``, ``A = U*D*UH``

-  if ``uplo='L'``, ``A = L*D*LH,``

where ``A`` is the input matrix, ``U`` and ``L`` are products of
permutation and triangular matrices with unit diagonal (upper
triangular for ``U`` and lower triangular for ``L``), and ``D`` is a
Hermitian block-diagonal matrix with 1-by-1 and 2-by-2 diagonal
blocks. ``U`` and ``L`` have 2-by-2 unit diagonal blocks
corresponding to the 2-by-2 blocks of ``D``.


.. note::
   This routine supports the Progress Routine feature.


API
***


Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::lapack {
     void hetrf(cl::sycl::queue &queue,
     mkl::uplo uplo,
     std::int64_t n,
     cl::sycl::buffer<T> &a,
     std::int64_t lda,
     std::int64_t *ipiv,
     cl::sycl::buffer<T> &scratchpad, std::int64_t scratchpad_size)
   }

``hetrf`` 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
   The device queue where calculations will be performed.

uplo
   Indicates whether the upper or lower triangular part of ``A`` is
   stored and how ``A`` is factored:.


   If ``uplo = uplo::upper``, the arraya stores the upper triangular
   part of ``A`` and ``A`` is factored as
   ``U``\ \*\ ``D``\ \*\ ``U``\ :sup:`H`.


   If ``uplo = uplo::lower``, the arraya stores the lower triangular
   part of ``A`` and ``A`` is factored as
   ``L``\ \*\ ``D``\ \*\ ``L``\ :sup:`H`.


n
   The order of the matrix ``A``\ ``(0≤n)``.


a
   Buffer holding coefficients of matrix ``A``, size
   ``max(1,lda*n)``, containing either the upper or the lower
   triangular part of the matrix ``A`` (see uplo). The second
   dimension of a must be at least ``max(1,n)``.


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 of floating point elements
   of type ``T``. Size should not be less than the value returned by
   the
   :ref:`hetrf_scratchpad_size`
   function.


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

a
   The upper or lower triangular part of ``a`` is overwritten by
   details of the block-diagonal matrix ``D`` and the multipliers
   used to obtain the factor ``U`` (or ``L``).


ipiv
   Buffer holding array of size at least ``max(1, n)``. Contains
   details of the interchanges and the block structure of ``D``. If
   ``ipiv(i) = k >0``, then ``dii`` is a 1-by-1 block, and the
   ``i``-th row and column of ``A`` was interchanged with the
   ``k``-th row and column.


   If ``uplo`` = mkl::uplo::upper and ``ipiv``\ (``i``)
   =\ ``ipiv``\ (``i``-1) = -``m`` < 0, then ``D`` has a 2-by-2 block
   in rows/columns ``i`` and ``i-1``, and (``i-1``)-th row and column
   of ``A`` was interchanged with the ``m``-th row and column.


   If ``uplo`` = mkl::uplo::lower and ``ipiv``\ (``i``)
   =\ ``ipiv``\ (``i``\ +1) = -``m`` < 0, then ``D`` has a 2-by-2
   block in rows/columns ``i`` and ``i+1``, and (``i+1``)-th row and
   column of ``A`` was interchanged with the ``m``-th row and column.


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 = i``, ``d``\ :sub:```i``\ ``i``` is   0. The factorization has been completed, but ``D`` is exactly   singular. Division by 0 will occur if you use ``D`` for solving a   system of linear equations.

           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.