.. _ormtr:

ormtr
=====


Multiplies a real matrix by the real orthogonal matrix ``Q`` determined
by :ref:`sytrd <sytrd>`. This routine belongs to the ``oneapi::mkl::lapack`` namespace.


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

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

``Q``\ :sup:`T`, where ``Q`` is the orthogonal matrix ``Q`` formed by
:ref:`sytrd` when
reducing a real symmetric matrix ``A`` to tridiagonal form:
``A = Q*T*QT``. Use this routine after a call to
:ref:`sytrd`.

Depending on the parameters left_right and trans, the routine can
form one of the matrix products ``Q*C``, ``QT*C``, ``C*Q``, or
``C*QT`` (overwriting the result on ``C``).

The routine multiplies a real matrix ``C`` by ``Q`` or


API
***


Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::lapack {
     void ormtr(cl::sycl::queue &queue,
     mkl::side side,
     mkl::uplo uplo,
     mkl::transpose trans,
     std::int64_t m,
     std::int64_t n,
     cl::sycl::buffer<T> &a,
     std::int64_t lda,
     cl::sycl::buffer<T> &tau,
     cl::sycl::buffer<T> &c,
     std::int64_t ldc,
     cl::sycl::buffer<T> &scratchpad,
      std::int64_t scratchpad_size)
   }

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

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

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


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

In the descriptions below, ``r`` denotes the order of ``Q``:

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

   * -  ``r = m``
     -  if ``left_right = side::left``
   * -  ``r = n``
     -  if ``left_right = side::right``

queue
   Device queue where calculations will be performed.


side
   Must be either ``side::left`` or ``side::right``.


   If ``side = side::left``, ``Q`` or ``Q``\ :sup:`T` is applied to
   ``C`` from the left.


   If ``side = side::right``, ``Q`` or ``Q``\ :sup:`T` is applied to
   ``C`` from the right.


uplo
   Must be either ``uplo::upper`` or ``uplo::lower``. Uses the same
   ``uplo`` as supplied to
   :ref:`sytrd`.


trans
   Must be either ``transpose::nontrans`` or ``transpose::trans``.


   If ``trans = transpose::nontrans``, the routine multiplies ``C``
   by ``Q``.


   If ``trans = transpose::trans``, the routine multiplies ``C`` by
   ``Q``\ :sup:`T`.


m
   The number of rows in the matrix ``C``\ ``(m ≥ 0)``.


n
   The number of columns in the matrix ``C``\ ``(n ≥ 0)``.


a
   Buffer holding array returned by
   :ref:`sytrd`.


lda
   The leading dimension of a\ ``(max(1, r) ≤ lda)``.


tau
   Buffer holding tau returned by
   :ref:`sytrd`. The
   dimension of tau must be at least ``max(1, r-1)``.


c
   Buffer holding the matrix ``C``. The second dimension of c must be
   at least ``max(1, n)``.


ldc
   The leading dimension of c\ ``(max(1, n) ≤ ldc)``.


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


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

c
   Overwritten by the product ``Q*C``, ``QT*C``, ``C*Q``, or ``C*QT``
   (as specified by side and trans).


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.