aoclsparse_?gthrz() - 5.2 English - 68552

AOCL API Guide (68552)
Document ID
68552
Release Date
2025-12-29
Version
5.2 English
aoclsparse_status aoclsparse_sgthrz(aoclsparse_int nnz, float *y, float *x, const aoclsparse_int *indx)#
aoclsparse_status aoclsparse_dgthrz(aoclsparse_int nnz, double *y, double *x, const aoclsparse_int *indx)#
aoclsparse_status aoclsparse_cgthrz(aoclsparse_int nnz, void *y, void *x, const aoclsparse_int *indx)#
aoclsparse_status aoclsparse_zgthrz(aoclsparse_int nnz, void *y, void *x, const aoclsparse_int *indx)#

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

The aoclsparse_?gthrz is a group of functions that gather the elements

indexed in indx from the dense vector y into the sparse vector x. The gathered elements in \(y\) are replaced by zero.

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}}\}, \text{ and after the assignment, } y_{I_{x_i}}=0, i\in\{1,\ldots,{\bf\mathsf{nnz}}\}. \]

For double precision complex vectors use aoclsparse_zgthrz() and for single precision complex vectors use aoclsparse_cgthrz().

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_size – nnz 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