.. _onemkl_blas_rotmg:

rotmg
=====

Computes the parameters for a modified Givens rotation.

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

Given Cartesian coordinates (``x1``, ``y1``) of an
input vector, the ``rotmg`` routines compute the components of a modified
Givens transformation matrix ``H`` that zeros the ``y``-component of
the resulting vector:

.. math::

      \left[
         \begin{array}{ccc}
         x1 \\ 0
         \end{array}
      \right] = H
      \left[
         \begin{array}{ccc}
         x1 & \sqrt{d1} \\
         y1 & \sqrt{d2}
         \end{array}
      \right]

``rotmg`` supports the following precisions:

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

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

rotmg (Buffer Version)
**********************

Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::blas::column_major {
       void rotmg(sycl::queue &queue,
                  sycl::buffer<T,1> &d1,
                  sycl::buffer<T,1> &d2,
                  sycl::buffer<T,1> &x1,
                  sycl::buffer<T,1> &y1,
                  sycl::buffer<T,1> &param)
   }

.. code-block:: cpp

   namespace oneapi::mkl::blas::row_major {
       void rotmg(sycl::queue &queue,
                  sycl::buffer<T,1> &d1,
                  sycl::buffer<T,1> &d2,
                  sycl::buffer<T,1> &x1,
                  sycl::buffer<T,1> &y1,
                  sycl::buffer<T,1> &param)
   }

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

queue
   The queue where the routine should be executed.

d1
   Buffer holding the scaling factor for ``x``-coordinate of the
   input vector.

d2
   Buffer holding the scaling factor for ``y``-coordinate of the
   input vector.

x1
   Buffer holding ``x``-coordinate of the input vector.

y1
   Scalar specifying ``y``-coordinate of the input vector.

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

d1
   Buffer holding the first diagonal element of the updated matrix.

d2
   Buffer holding the second diagonal element of the updated matrix.

x1
   Buffer holding ``x``-coordinate of the rotated vector before
   scaling

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 array ``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.9 & 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, and 0.0
   are assumed based on the value of ``flag`` and are not required to
   be set in the ``param`` vector.


rotmg (USM Version)
**********************

Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::blas::column_major {
       sycl::event rotmg(sycl::queue &queue,
                         T *d1,
                         T *d2,
                         T *x1,
                         T *y1,
                         T *param,
                         const std::vector<sycl::event> &dependencies = {})
   }

.. code-block:: cpp

   namespace oneapi::mkl::blas::row_major {
       sycl::event rotmg(sycl::queue &queue,
                         T *d1,
                         T *d2,
                         T *x1,
                         T *y1,
                         T *param,
                         const std::vector<sycl::event> &dependencies = {})
   }

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

queue
   The queue where the routine should be executed.

d1
   Pointer to the scaling factor for ``x``-coordinate of the
   input vector.

d2
   Pointer to the scaling factor for ``y``-coordinate of the
   input vector.

x1
   Pointer to ``x``-coordinate of the input vector.

y1
   Scalar specifying ``y``-coordinate of the input vector.

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

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

d1
   Pointer to the first diagonal element of the updated matrix.

d2
   Pointer to the second diagonal element of the updated matrix.

x1
   Pointer to ``x``-coordinate of the rotated vector before scaling

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 array ``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, and 0.0
   are assumed based on the value of ``flag`` and are not required to
   be set in the ``param`` vector.

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

Output event to wait on to ensure computation is complete.