.. _sytrf-usm-version:

sytrf (USM Version)
===================

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 {
     cl::sycl::event sytrf(queue &queue,
     mkl::uplo uplo,
     std::int64_t n,
     T *a,
     std::int64_t lda,
     std::int64_t *ipiv,
     T *scratchpad,
     std::int64_t scratchpad_size,
     const std::vector<cl::sycl::event> &events = {})
   }

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


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


   If ``uplo = uplo::upper``, the array ``a`` stores the upper
   triangular part of the matrix ``A``, and ``A`` is factored as
   ``U*D*U``\ :sup:`T`.


   If ``uplo = uplo::lower``, the array ``a`` stores the lower
   triangular part of the matrix ``A``, and ``A`` is factored as
   ``L*D*L``\ :sup:`T`.


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


a
   Pointer to 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
   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:`sytrf_scratchpad_size`
   function.


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



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
   Pointer to memory 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``, ``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.


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

Output event to wait on to ensure computation is complete.