.. _sytrd:

sytrd
=====


Reduces a real symmetric matrix to tridiagonal form. This routine
belongs to the ``oneapi::mkl::lapack`` namespace.


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

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

The routine reduces a real symmetric matrix ``A`` to symmetric
tridiagonal form ``T`` by an orthogonal similarity transformation:
``A = Q*T*QT``. The orthogonal matrix ``Q`` is not formed explicitly
but is represented as a product of ``n``-1 elementary reflectors.
Routines are provided for working with ``Q`` in this representation .


API
***


Syntax
------

.. code-block:: cpp

      namespace oneapi::mkl::lapack {
        void sytrd(cl::sycl::queue &queue,
        mkl::uplo uplo,
        std::int64_t n,
        cl::sycl::buffer<T> &a,
        std::int64_t lda,
        cl::sycl::buffer<T> &d,
        cl::sycl::buffer<T> &e,
        cl::sycl::buffer<T> &tau,
        cl::sycl::buffer<T> &scratchpad,
        std::int64_t scratchpad_size)
      }

``sytrd`` supports the following precisions and devices:


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

   * -  T
     -  Devices supported
   * -  ``float``
     -  Host, CPU, and GPU
   * -  ``double``
     -  Host, CPU, and GPU


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

queue
   Device queue where calculations will be performed.


uplo
   Must be ``uplo::upper`` or ``uplo::lower``.


   If ``uplo = uplo::upper``, ``a`` stores the upper triangular part
   of ``A``.


   If ``uplo = uplo::lower``, ``a`` stores the lower triangular part
   of ``A``.


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


a
   Buffer holding matrix ``A``, size ``(lda,*)``. Contains the upper
   or lower triangle as specified by uplo.


lda
   The leading dimension of a; at least ``max(1,n)``.


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:`sytrd_scratchpad_size`
   function.


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

a
   On exit,


   if ``uplo = uplo::upper``, the diagonal and first superdiagonal of
   ``A`` are overwritten by the corresponding elements of the
   tridiagonal matrix ``T``, and the elements above the first
   superdiagonal, with the buffer tau, represent the orthogonal
   matrix ``Q`` as a product of elementary reflectors;


   if ``uplo = uplo::lower``, the diagonal and first subdiagonal of
   ``A`` are overwritten by the corresponding elements of the
   tridiagonal matrix ``T``, and the elements below the first
   subdiagonal, with the buffer tau, represent the orthogonal matrix
   ``Q`` as a product of elementary reflectors.


d
   Buffer holding the diagonal elements of the matrix ``T``. The
   dimension of d must be at least ``max(1, n)``.


e
   Buffer holding the off diagonal elements of the matrix ``T``. The
   dimension of e must be at least ``max(1, n-1)``.


tau
   Buffer holding array of size at least ``max(1, n)``. Stores
   ``(n-1)`` scalars that define elementary reflectors in
   decomposition of the unitary matrix ``Q`` in a product of ``n-1``
   elementary reflectors. tau ``(n)`` is used as workspace.


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