.. _ormtr-usm-version:

ormtr (USM Version)
===================

Multiplies a real matrix by the real orthogonal matrix ``Q`` determined
by the ``sytrd`` (USM Version) function. This routine belongs to the ``oneapi::mkl::lapack`` namespace.


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

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

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

Depending on the parameters side 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``).


API
***


Syntax
------

.. code-block:: cpp

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

``ormtr`` (USM version) 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: 0

   * -  ``r = m``
     -  if ``side = side::left``
   * -  ``r = n``
     -  if ``side = 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-usm-version`.


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
   The pointer to memory returned by :ref:`sytrd-usm-version`.


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


tau
   The pointer to tau returned by :ref:`sytrd-usm-version`. The
   dimension of tau must be at least ``max(1, r-1)``.


c
   The pointer to memory containing 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
   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:`ormtr_scratchpad_size`
   function.


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


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

c
   Overwritten by ``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.


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

Output event to wait on to ensure computation is complete.