aoclsparse_?gthr() - 5.2 English - 68552

AOCL API Guide (68552)

Document ID
68552
Release Date
2025-12-29
Version
5.2 English
aoclsparse_status aoclsparse_sgthr(aoclsparse_int nnz, const float *y, float *x, const aoclsparse_int *indx)#
aoclsparse_status aoclsparse_dgthr(aoclsparse_int nnz, const double *y, double *x, const aoclsparse_int *indx)#
aoclsparse_status aoclsparse_cgthr(aoclsparse_int nnz, const void *y, void *x, const aoclsparse_int *indx)#
aoclsparse_status aoclsparse_zgthr(aoclsparse_int nnz, const void *y, void *x, const aoclsparse_int *indx)#

Gather elements from a dense vector and store them into a sparse vector.

The aoclsparse_?gthr is a group of functions that gather the elements indexed in indx from the dense vector y into the sparse vector x.

Let \(y\in R^m\) (or \(C^m\)) be a dense vector, \(x\) be a sparse vector from the same space and \(I_x\) be a set of indices of size \(0<\) nnz \(\le m\) described by indx, then

\[ x_i = y_{I_{x_i}}, i\in\{1,\ldots,{\bf\mathsf{nnz}}\}. \]

For double precision complex vectors use aoclsparse_zgthr() and for single precision complex vectors use aoclsparse_cgthr().

  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 <complex>
 29#include <iomanip>
 30#include <iostream>
 31#include <vector>
 32
 33int main()
 34{
 35    std::cout << "-------------------------------" << std::endl
 36              << "---- Gather sample program ----" << std::endl
 37              << "-------------------------------" << std::endl
 38              << std::endl;
 39
 40    // Input data
 41
 42    // Number of non-zeros of the sparse vector
 43    const aoclsparse_int nnz = 3;
 44
 45    // Sparse index vector (does not need to be ordered)
 46    std::vector<aoclsparse_int> indx = {0, 5, 3};
 47
 48    // Sparse value vector
 49    std::vector<std::complex<double>> x(3);
 50
 51    // Dense vector
 52    std::vector<std::complex<double>> y{
 53        {1, 1}, {1, 2}, {2, 3}, {1, 0}, {4, 1}, {1.2, -1}, {7, -1}, {0, 2}, {-2, 3}};
 54
 55    // Expected sparse value vector
 56    std::vector<std::complex<double>> x_exp{{1, 1}, {1.2, -1}, {1, 0}};
 57
 58    // Expected dense vector
 59    std::vector<std::complex<double>> y_exp{
 60        {0, 0}, {1, 2}, {2, 3}, {0, 0}, {4, 1}, {0, 0}, {7, -1}, {0, 2}, {-2, 3}};
 61
 62    aoclsparse_int ny = y.size();
 63
 64    aoclsparse_status status;
 65
 66    // Call the gather function
 67    status = aoclsparse_zgthr(nnz, y.data(), x.data(), indx.data());
 68    if(status != aoclsparse_status_success)
 69    {
 70        std::cerr << "Error returned from aoclsparse_zgthr, status = " << status << "."
 71                  << std::endl;
 72        return 1;
 73    }
 74
 75    // Check and print the result
 76    std::cout << "Gather from vector y: " << std::endl
 77              << std::setw(11) << "x"
 78              << "   " << std::setw(11) << "expected" << std::endl;
 79    std::cout << std::fixed;
 80    std::cout.precision(1);
 81    bool oki, ok = true;
 82    for(aoclsparse_int i = 0; i < nnz; i++)
 83    {
 84        oki = x[i] == x_exp[i];
 85        ok &= oki;
 86        std::cout << std::setw(11) << x[i] << std::setw(3) << "" << std::setw(11) << x_exp[i]
 87                  << std::setw(2) << (oki ? "" : " !") << std::endl;
 88    }
 89
 90    // Call the gather with zero function
 91    status = aoclsparse_zgthrz(nnz, y.data(), x.data(), indx.data());
 92    if(status != aoclsparse_status_success)
 93    {
 94        std::cerr << "Error returned from aoclsparse_zgthr, status = " << status << "."
 95                  << std::endl;
 96        return 3;
 97    }
 98
 99    // Check and print the result
100    std::cout << std::endl
101              << "Gather from vector y: " << std::endl
102              << std::setw(11) << "y" << std::setw(3) << "" << std::setw(11) << "expected"
103              << std::setw(3) << "" << std::setw(11) << "x" << std::setw(3) << "" << std::setw(11)
104              << "expected" << std::endl;
105    std::cout << std::fixed;
106    std::cout.precision(1);
107    bool oky;
108    for(aoclsparse_int i = 0; i < ny; i++)
109    {
110        oky = y[i] == y_exp[i];
111        ok &= oky;
112        std::cout << std::setw(11) << y[i] << std::setw(3) << "" << std::setw(11) << y_exp[i]
113                  << std::setw(2) << (oky ? "" : " !");
114        if(i < nnz)
115        {
116            oki = x[i] == x_exp[i];
117            ok &= oki;
118            std::cout << " " << std::setw(11) << x[i] << std::setw(3) << "" << std::setw(11)
119                      << x_exp[i] << std::setw(2) << (oki ? "" : " !");
120        }
121        std::cout << std::endl;
122    }
123
124    return (ok ? 0 : 6);
125}

Note

These functions assume that the indices stored in indx are less than \(m\) without duplicate elements, and that x and indx are pointers to vectors of size at least nnz.

Parameters:
  • nnz[in] number of non-zero entries of \(x\). If nnz is zero, then none of the entries of vectors x, y, and indx are touched.

  • y[in] pointer to dense vector \(y\) of size at least \(m\).

  • x[out] pointer to sparse vector \(x\) with at least nnz non-zero elements.

  • indx[in] index vector of size nnz, containing the indices of the non-zero values of \(x\). Indices should range from 0 to \(m-1\), need not be ordered. The elements in this vector are only checked for non-negativity. The user should make sure that no index is out-of-bound and that it does not contains any duplicates.

Return values:
  • aoclsparse_status_success – the operation completed successfully

  • aoclsparse_status_invalid_sizennz parameter value is negative

  • aoclsparse_status_invalid_pointer – at least one of the pointers y, x or indx is invalid

  • aoclsparse_status_invalid_index_value – at least one of the indices in indx is negative