.. _onemkl_blas_rotm:

rotm
====

Performs modified Givens rotation of points in the plane.

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

Given two vectors ``x`` and ``y``, each vector element of these
vectors is replaced as follows:

.. math::

      \left[
         \begin{array}{ccc}
         x_i \\ y_i
         \end{array}
      \right] =
      H
      \left[
         \begin{array}{ccc}
         x_i \\ y_i
         \end{array}
      \right]

for ``i`` from 1 to ``n``, where ``H`` is a modified Givens transformation matrix.

``rotm`` supports the following precisions:

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

   * -  T
   * -  ``float``
   * -  ``double``


rotm (Buffer Version)
*********************

Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::blas::column_major {
       void rotm(sycl::queue &queue,
                 std::int64_t n,
                 sycl::buffer<T,1> &x,
                 std::int64_t incx,
                 sycl::buffer<T,1> &y,
                 std::int64_t incy,
                 sycl::buffer<T,1> &param)
   }

.. code-block:: cpp

   namespace oneapi::mkl::blas::row_major {
       void rotm(sycl::queue &queue,
                 std::int64_t n,
                 sycl::buffer<T,1> &x,
                 std::int64_t incx,
                 sycl::buffer<T,1> &y,
                 std::int64_t incy,
                 sycl::buffer<T,1> &param)
   }

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

queue
   The queue where the routine should be executed.

n
   Number of elements in vector ``x``.

x
   Buffer holding input vector ``x``. Size of the buffer must be at
   least (1 + (``n`` - 1)*abs(``incx``)). See :ref:`matrix-storage` for
   more details.

incx
   Stride of vector ``x``.

y
   Buffer holding input vector ``y``. Size of the buffer must be at
   least (1 + (``n`` - 1)*abs(``incy``)). See `:ref:`matrix-storage` for
   more details.

incy
   Stride of vector ``y``.

param
   Buffer holding an array of size 5. The elements of the ``param``
   array are:

   ``param[0]`` contains a switch, ``flag``. The other array elements 
   ``param[1-4]`` contain the components of the modified Givens transformation matrix 
   ``H``: h\ :sub:`11`, h\ :sub:`21`, h\ :sub:`12`, and h\ :sub:`22`, respectively.

   Depending on the values of ``flag``, the components of ``H`` are
   set as follows:

   ``flag = -1.0``:

   .. math::

         H = \left[
         \begin{array}{ccc}
         h_{11} & h_{12} \\
         h_{21} & h_{22}
         \end{array}
         \right]

   ``flag = 0.0``:

   .. math::

         H = \left[
         \begin{array}{ccc}
         1.0 & h_{12} \\
         h_{21} & 1.0
         \end{array}
         \right]

   ``flag = 1.0``:

   .. math::

         H = \left[
         \begin{array}{ccc}
         h_{11} & 1.0 \\
         -1.0 & h_{22}
         \end{array}
         \right]

   ``flag = -2.0``:

   .. math::

         H = \left[
         \begin{array}{ccc}
         1.0 & 0.0 \\
         0.0 & 1.0
         \end{array}
         \right]

   In the last three cases, the matrix entries of 1.0, -1.0, 0.0 are
   assumed based on the value of ``flag`` and are not required to be
   set in the ``param`` vector.

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

x
   Buffer holding updated buffer ``x``.

y
   Buffer holding updated buffer ``y``.


rotm (USM Version)
*********************

Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::blas::column_major {
       sycl::event rotm(sycl::queue &queue,
                        std::int64_t n,
                        T *x,
                        std::int64_t incx,
                        T *y,
                        std::int64_t incy,
                        T *param,
                        const std::vector<sycl::event> &dependencies = {})
   }

.. code-block:: cpp

   namespace oneapi::mkl::blas::row_major {
       sycl::event rotm(sycl::queue &queue,
                        std::int64_t n,
                        T *x,
                        std::int64_t incx,
                        T *y,
                        std::int64_t incy,
                        T *param,
                        const std::vector<sycl::event> &dependencies = {})
   }

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

queue
   The queue where the routine should be executed.

n
   Number of elements in vector ``x``.

x
   Pointer to the input vector ``x``. Size of the array holding vector
   ``x`` must be at least (1 + (``n`` - 1)*abs(``incx``)).
   See :ref:`matrix-storage` for more details.

incx
   Stride of vector ``x``.

yparam
   Pointer to the input vector ``y``. Size of the array holding vector
   ``y`` must be at least (1 + (``n`` - 1)*abs(``incy``)).
   See :ref:`matrix-storage` for more details.

incy
   Stride of vector ``y``.

param
   Pointer to an array of size 5. The elements of the ``param`` array
   are:

   ``param[0]`` contains a switch, ``flag``. The other array elements 
   ``param[1-4]`` contain the components of the modified Givens transformation matrix 
   ``H``: h\ :sub:`11`, h\ :sub:`21`, h\ :sub:`12`, and h\ :sub:`22`, respectively.

   Depending on the values of ``flag``, the components of ``H`` are
   set as follows:

   ``flag = -1.0``:

   .. math::

         H = \left[
            \begin{array}{ccc}
            h_{11} & h_{12} \\
            h_{21} & h_{22}
            \end{array}
         \right]

   ``flag = 0.0``:

   .. math::

         H = \left[
         \begin{array}{ccc}
         1.0 & h_{12} \\
         h_{21} & 1.0
         \end{array}
         \right]

   ``flag = 1.0``:

   .. math::

         H = \left[
         \begin{array}{ccc}
         h_{11} & 1.0 \\
         -1.0 & h_{22}
         \end{array}
         \right]

   ``flag = -2.0``:

   .. math::

         H = \left[
         \begin{array}{ccc}
         1.0 & 0.0 \\
         0.0 & 1.0
         \end{array}
         \right]

   In the last three cases, the matrix entries of 1.0, -1.0, 0.0 are
   assumed based on the value of ``flag`` and are not required to be
   set in the ``param`` vector.

dependencies
   List of events to wait for before starting computation, if any. If
   omitted, defaults to no dependencies.

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

x
   Pointer to updated array ``x``.

y
   Pointer to updated array ``y``.

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

Output event to wait on to ensure computation is complete.