aoclsparse_?roti() - 5.2 English - 68552

AOCL API Guide (68552)

Document ID
68552
Release Date
2025-12-29
Version
5.2 English
aoclsparse_status aoclsparse_sroti(const aoclsparse_int nnz, float *x, const aoclsparse_int *indx, float *y, const float c, const float s)#
aoclsparse_status aoclsparse_droti(const aoclsparse_int nnz, double *x, const aoclsparse_int *indx, double *y, const double c, const double s)#

Apply Givens rotation to single or double precision real vectors.

aoclsparse_sroti() and aoclsparse_droti() apply the Givens rotation on elements of two real vectors.

Let \(y\in R^m\) be a vector in full storage form, \(x\) be a vector in a compressed form and \(I_x\) its nonzero indices set of length at least nnz described by the array indx, then

\[ x_i = {\bf\mathsf{c}} * x_i + {\bf\mathsf{s}} * y_{I_{x_{i}}}, \]
\[ y_{I_{x_{i}}} = {\bf\mathsf{c}} * y_{I_{x_{i}}} - {\bf\mathsf{s}} * x_i, \]

for \(i\in 1, \ldots, {\bf\mathsf{nnz}}\). The elements c, s are scalars.

  1/* ************************************************************************
  2 * Copyright (c) 2023 Advanced Micro Devices, Inc.
  3 *
  4 * Permission is hereby granted, free of charge, to any person obtaining a copy
  5 * of this software and associated documentation files (the "Software"), to deal
  6 * in the Software without restriction, including without limitation the rights
  7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  8 * copies of the Software, and to permit persons to whom the Software is
  9 * furnished to do so, subject to the following conditions:
 10 *
 11 * The above copyright notice and this permission notice shall be included in
 12 * all copies or substantial portions of the Software.
 13 *
 14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 20 * THE SOFTWARE.
 21 *
 22 * ************************************************************************ */
 23
 24#include "aoclsparse.h"
 25
 26#include <cfloat>
 27#include <cmath>
 28#include <iomanip>
 29#include <iostream>
 30#include <limits>
 31#include <vector>
 32
 33// Sample program to illustrate the usage of Givens rotation on a compressed sparse vector and a full storage vector(double precision)
 34int main(void)
 35{
 36    std::cout << "-----------------------------" << std::endl
 37              << "---- roti sample program ----" << std::endl
 38              << "-----------------------------" << std::endl
 39              << std::endl;
 40
 41    // Input data
 42
 43    // Number of non-zeros of the sparse vector
 44    const aoclsparse_int nnz = 5;
 45
 46    // Sparse index vector (does not need to be ordered)
 47    std::vector<aoclsparse_int> indx{0, 3, 6, 7, 9};
 48
 49    // Sparse value vector in compressed form
 50    std::vector<double> x{-0.75, 4, -9.5, 46, 1.25};
 51
 52    // Output vector
 53    std::vector<double> y{-0.75, 0, 0, 4, 0, 0, -9.5, 46, 0, 1.25};
 54
 55    // Expected output vectors
 56    std::vector<double> y_exp{0, 0, 0, 0, 0, 0, 0, 0, 0, 0};
 57    std::vector<double> x_exp{-3, 16, -38, 184, 5};
 58
 59    const double c = 2;
 60    const double s = 2;
 61
 62    aoclsparse_int ny = y.size();
 63    aoclsparse_int nx = x.size();
 64
 65    aoclsparse_status status;
 66    std::cout << "Invoking aoclsparse_droti...\n";
 67    //Invoke aoclsparse_droti to apply Givens rotation
 68    status = aoclsparse_droti(nnz, x.data(), indx.data(), y.data(), c, s);
 69
 70    if(status != aoclsparse_status_success)
 71    {
 72        std::cerr << "Error returned from aoclsparse_droti, status = " << status << "."
 73                  << std::endl;
 74        return 3;
 75    }
 76
 77    // Check and print the result
 78    std::cout << "The vector y after Givens rotation: " << std::endl
 79              << std::setw(11) << "y"
 80              << "   " << std::setw(11) << "expected" << std::endl;
 81    std::cout << std::fixed;
 82
 83    std::cout.precision(2);
 84
 85    bool oki, ok_y = true, ok_x = true;
 86
 87    //Initializing precision tolerance range for double
 88    const double tol = std::sqrt(std::numeric_limits<double>::epsilon());
 89
 90    for(aoclsparse_int i = 0; i < ny; i++)
 91    {
 92        oki = std::abs(y[i] - y_exp[i]) <= tol;
 93        ok_y &= oki;
 94        std::cout << std::setw(11) << y[i] << std::setw(3) << "" << std::setw(11) << y_exp[i]
 95                  << std::setw(2) << (oki ? "" : " !") << std::endl;
 96    }
 97    std::cout << std::endl;
 98    std::cout << "The vector x after Givens rotation: " << std::endl
 99              << std::setw(11) << "x"
100              << "   " << std::setw(11) << "expected" << std::endl;
101    std::cout << std::fixed;
102    for(aoclsparse_int i = 0; i < nx; i++)
103    {
104        oki = std::abs(x[i] - x_exp[i]) <= tol;
105        ok_x &= oki;
106        std::cout << std::setw(11) << x[i] << std::setw(3) << "" << std::setw(11) << x_exp[i]
107                  << std::setw(2) << (oki ? "" : " !") << std::endl;
108    }
109    return ((ok_y && ok_x) ? 0 : 6);
110}

Note

The contents of the vectors are not checked for NaNs.

Parameters:
  • nnz[in] The number of elements to use from \(x\) and \({\bf\mathsf{indx}}\).

  • x[inout] Array \(x\) of at least \({\bf\mathsf{nnz}}\) elements in compressed form. The elements of the array are updated after applying the Givens rotation.

  • indx[in] Nonzero index set of \(x\), \(I_x\), with at least \({\bf\mathsf{nnz}}\) elements. The first \({\bf\mathsf{nnz}}\) elements are used to apply the Givens rotation. The elements in this vector are only checked for non-negativity. The caller should make sure that each entry is less than the size of y and are all distinct.

  • y[inout] Dense array of at least \(\max(I_{x_i}, \text{ for } i \in \{ 1,\ldots, {\bf\mathsf{nnz}}\})\) elements in full storage form. The elements of the array are updated after applying the Givens rotation.

  • c[in] A scalar.

  • s[in] A scalar.

Return values:
  • aoclsparse_status_success – The operation completed successfully.

  • aoclsparse_status_invalid_pointer – At least one of the pointers x, indx, y is invalid.

  • aoclsparse_status_invalid_size – Indicates that provided nnz is less than zero.

  • aoclsparse_status_invalid_index_value – At least one of the indices in indx is negative. With this error, the values of vectors x and y are undefined.