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:

\[\begin{split}\begin{bmatrix}x1 \\ 0\end{bmatrix}= H \begin{bmatrix}x1\sqrt{d1} \\ y1\sqrt{d2}\end{bmatrix}\end{split}\]

rotmg supports the following precisions.

T
float
double

rotmg (Buffer Version)

Syntax

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)
}

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 the x-coordinate of the input vector.

d2

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

x1

Buffer holding the x-coordinate of the input vector.

y1

Scalar specifying the 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 the 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 modified Givens transformation matrix H: h₁₁, h₂₁, h₁₂, and h₂₂, respectively.

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

flag = -1.0:

\[\begin{split}H=\begin{bmatrix}h_{11} & h_{12} \\ h_{21} & h_{22}\end{bmatrix}\end{split}\]

flag = 0.0:

\[\begin{split}H=\begin{bmatrix}1.0 & h_{12} \\ h_{21} & 1.0\end{bmatrix}\end{split}\]

flag = 1.0:

\[\begin{split}H=\begin{bmatrix}h_{11} & 1.0 \\ -1.0 & h_{22}\end{bmatrix}\end{split}\]

flag = -2.0:

\[\begin{split}H=\begin{bmatrix}1.0 & 0.0 \\ 0.0 & 1.0\end{bmatrix}\end{split}\]

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.

Throws

This routine shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here.

oneapi::mkl::invalid_argument

oneapi::mkl::unsupported_device

oneapi::mkl::host_bad_alloc

oneapi::mkl::device_bad_alloc

oneapi::mkl::unimplemented

rotmg (USM Version)

Syntax

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

namespace oneapi::mkl::blas::row_major {
    sycl::event rotmg(sycl::queue &queue,
                      T *d1,
                      T *d2,
                      T *x1,
                      value_or_pointer<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 the x-coordinate of the input vector.

d2

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

x1

Pointer to the x-coordinate of the input vector.

y1

Scalar specifying the y-coordinate of the input vector. See Scalar Arguments in BLAS for more details.

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 the 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 modified Givens transformation matrix H: h₁₁, h₂₁, h₁₂, and h₂₂, respectively.

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

flag = -1.0:

\[\begin{split}H=\begin{bmatrix}h_{11} & h_{12} \\ h_{21} & h_{22}\end{bmatrix}\end{split}\]

flag = 0.0:

\[\begin{split}H=\begin{bmatrix}1.0 & h_{12} \\ h_{21} & 1.0\end{bmatrix}\end{split}\]

flag = 1.0:

\[\begin{split}H=\begin{bmatrix}h_{11} & 1.0 \\ -1.0 & h_{22}\end{bmatrix}\end{split}\]

flag = -2.0:

\[\begin{split}H=\begin{bmatrix}1.0 & 0.0 \\ 0.0 & 1.0\end{bmatrix}\end{split}\]

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.

Throws

This routine shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here.

oneapi::mkl::invalid_argument

oneapi::mkl::unsupported_device

oneapi::mkl::host_bad_alloc

oneapi::mkl::device_bad_alloc

oneapi::mkl::unimplemented

Parent topic: BLAS Level 1 Routines