.. _sytrf:

sytrf
=====


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


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

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

The routine computes the factorization of a real/complex symmetric
matrix ``A`` using the Bunch-Kaufman diagonal pivoting method. The
form of the factorization is:

-  if ``uplo=uplo::upper``, ``A`` = ``U*D*U``\ :sup:`T`

-  if ``uplo=uplo::lower``, ``A`` = ``L*D*L``\ :sup:`T`

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
symmetric 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``.


API
***


Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::lapack {
     void sytrf(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)
   }

``sytrf`` 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
----------------

.. list-table::
   :header-rows: 0

   * -     queue
     -      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 buffer a stores the upper triangular part   of the matrix ``A``, and ``A`` is factored as ``U*D*UT``.         If ``uplo=uplo::lower``, the buffer a stores the   lower triangular part of the matrix ``A``, and ``A`` is factored as   ``L*D*LT``.
   * -     n
     -     The order of matrix ``A`` (``0≤n``).
   * -     a
     -     Buffer holding the coefficients of matrix ``A``, size    ``max(1,lda*n)`` containing either the upper or 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:`sytrf_scratchpad_size`   function.


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

.. list-table::
   :header-rows: 0

   * -     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 ``d``\ :sub:`ii` 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``, ``dii`` 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.