.. _onemkl_blas_rotg:

rotg
====

Computes the parameters for a Givens rotation.

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

Given the Cartesian coordinates ``(a, b)`` of a point, the ``rotg``
routines return the parameters ``c``, ``s``, ``r``, and ``z``
associated with the Givens rotation. The parameters ``c`` and ``s``
define a unitary matrix such that:

.. math::

      \left[
         \begin{array}{ccc}
         c & s \\
         -s & c
         \end{array}
      \right]
      \cdot
      \left[
         \begin{array}{ccc}
         a \\ b
         \end{array}
      \right] =
      \left[
         \begin{array}{ccc}
         r \\ 0
         \end{array}
      \right]


The parameter ``z`` is defined such that if \|\ ``a``\ \| >
\|\ ``b``\ \|, ``z`` is ``s``; otherwise if ``c`` is not 0 ``z`` is
1/``c``; otherwise ``z`` is 1.

``rotg`` supports the following precisions:

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

   * -  T
     -  T_real
   * -  ``float``
     -  ``float``
   * -  ``double``
     -  ``double``
   * -  ``std::complex<float>``
     -  ``float``
   * -  ``std::complex<double>``
     -  ``double``


rotg (Buffer Version)
*********************

Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::blas::column_major {
       void rotg(sycl::queue &queue,
                 sycl::buffer<T,1> &a,
                 sycl::buffer<T,1> &b,
                 sycl::buffer<T_real,1> &c,
                 sycl::buffer<T,1> &s)
   }

.. code-block:: cpp

   namespace oneapi::mkl::blas::row_major {
       void rotg(sycl::queue &queue,
                 sycl::buffer<T,1> &a,
                 sycl::buffer<T,1> &b,
                 sycl::buffer<T_real,1> &c,
                 sycl::buffer<T,1> &s)
   }

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

queue
   The queue where the routine should be executed

a
   Buffer holding ``x``-coordinate of the point.

b
   Buffer holding ``y``-coordinate of the point.

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

a
   Buffer holding parameter ``r`` associated with the Givens rotation.

b
   Buffer holding parameter ``z`` associated with the Givens rotation.

c
   Buffer holding parameter ``c`` associated with the Givens rotation.

s
   Buffer holding parameter ``s`` associated with the Givens rotation.


rotg (USM Version)
*********************

Syntax
------

.. code-block:: cpp

   namespace oneapi::mkl::blas::column_major {
       sycl::event rotg(sycl::queue &queue,
                        T *a,
                        T *b,
                        T_real *c,
                        T *s,
                        const std::vector<sycl::event> &dependencies = {})
   }

.. code-block:: cpp

   namespace oneapi::mkl::blas::row_major {
       sycl::event rotg(sycl::queue &queue,
                        T *a,
                        T *b,
                        T_real *c,
                        T *s,
                        const std::vector<sycl::event> &dependencies = {})
   }

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

queue
   The queue where the routine should be executed

a
   Pointer to ``x``-coordinate of the point.

b
   Pointer to ``y``-coordinate of the point.

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

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

a
   Pointer to parameter ``r`` associated with the Givens rotation.

b
   Pointer to parameter ``z`` associated with the Givens rotation.

c
   Pointer to parameter ``c`` associated with the Givens rotation.

s
   Pointer to parameter ``s`` associated with the Givens rotation.

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

Output event to wait on to ensure computation is complete.