Sparse level 1 functions

The sparse level 1 routines describe operations between a vector in sparse format and a vector in dense format. This section describes all hipSPARSE level 1 sparse linear algebra functions.

hipsparseXaxpyi()

hipsparseStatus_t hipsparseSaxpyi(hipsparseHandle_t handle, int nnz, const float *alpha, const float *xVal, const int *xInd, float *y, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseDaxpyi(hipsparseHandle_t handle, int nnz, const double *alpha, const double *xVal, const int *xInd, double *y, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseCaxpyi(hipsparseHandle_t handle, int nnz, const hipComplex *alpha, const hipComplex *xVal, const int *xInd, hipComplex *y, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseZaxpyi(hipsparseHandle_t handle, int nnz, const hipDoubleComplex *alpha, const hipDoubleComplex *xVal, const int *xInd, hipDoubleComplex *y, hipsparseIndexBase_t idxBase)

Scale a sparse vector and add it to a dense vector.

hipsparseXaxpyi multiplies the sparse vector \(x\) with scalar \(\alpha\) and adds the result to the dense vector \(y\), such that

\[ y := y + \alpha \cdot x \]

for(i = 0; i < nnz; ++i)
{
    y[xInd[i]] = y[xInd[i]] + alpha * xVal[i];
}

Deprecated:

This function is deprecated when using the CUDA backend (CUDA 11.0+) and will be removed in CUDA 12.0. This deprecation does not apply to the ROCm backend.

Note

This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

Note

If nnz is zero, the function returns successfully without modifying y. Duplicate indices in xInd will result in the corresponding values being added multiple times to the same location in y.

Parameters:

• handle – [in] handle to the hipsparse library context queue.

• nnz – [in] number of non-zero entries of vector \(x\). Must be non-negative.

• alpha – [in] scalar \(\alpha\).

• xVal – [in] array of nnz elements containing the values of \(x\).

• xInd – [in] array of nnz elements containing the indices of the non-zero values of \(x\).

• y – [inout] array of values in dense format. Must be pre-allocated with sufficient size to accommodate all indices specified in xInd.

• idxBase – [in] index base. HIPSPARSE_INDEX_BASE_ZERO for zero-based indexing or HIPSPARSE_INDEX_BASE_ONE for one-based indexing.

Return values:

• HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

• HIPSPARSE_STATUS_NOT_INITIALIZED – handle is not initialized.

• HIPSPARSE_STATUS_INVALID_VALUE – handle is nullptr, nnz is negative, alpha, xVal, xInd or y is nullptr when nnz is greater than zero, or idxBase is neither HIPSPARSE_INDEX_BASE_ZERO nor HIPSPARSE_INDEX_BASE_ONE.

C++CFortran

int main(int argc, char* argv[])
{
    // Number of non-zeros of the sparse vector
    const int nnz = 3;

    // Number of entries in the dense vector
    const int size = 9;

    // Sparse index vector
    std::vector<int> hxInd = {0, 3, 5};

    // Sparse value vector
    std::vector<double> hxVal = {1.0, 2.0, 3.0};

    // Dense vector
    std::vector<double> hy = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0};

    // Scalar alpha
    double alpha = 3.7;

    // Index base
    hipsparseIndexBase_t idxBase = HIPSPARSE_INDEX_BASE_ZERO;

    // Offload data to device
    int*    dxInd;
    double* dxVal;
    double* dy;

    HIP_CHECK(hipMalloc((void**)&dxInd, sizeof(int) * nnz));
    HIP_CHECK(hipMalloc((void**)&dxVal, sizeof(double) * nnz));
    HIP_CHECK(hipMalloc((void**)&dy, sizeof(double) * size));

    HIP_CHECK(hipMemcpy(dxInd, hxInd.data(), sizeof(int) * nnz, hipMemcpyHostToDevice));
    HIP_CHECK(hipMemcpy(dxVal, hxVal.data(), sizeof(double) * nnz, hipMemcpyHostToDevice));
    HIP_CHECK(hipMemcpy(dy, hy.data(), sizeof(double) * size, hipMemcpyHostToDevice));

    // hipSPARSE handle
    hipsparseHandle_t handle;
    HIPSPARSE_CHECK(hipsparseCreate(&handle));

    // Call daxpyi to perform y = y + alpha * x
    HIPSPARSE_CHECK(hipsparseDaxpyi(handle, nnz, &alpha, dxVal, dxInd, dy, idxBase));

    // Copy result back to host
    HIP_CHECK(hipMemcpy(hy.data(), dy, sizeof(double) * size, hipMemcpyDeviceToHost));

    std::cout << "hy" << std::endl;
    for(int i = 0; i < size; i++)
    {
        std::cout << hy[i] << " ";
    }
    std::cout << std::endl;

    // Clear hipSPARSE
    HIPSPARSE_CHECK(hipsparseDestroy(handle));

    // Clear device memory
    HIP_CHECK(hipFree(dxInd));
    HIP_CHECK(hipFree(dxVal));
    HIP_CHECK(hipFree(dy));
    return 0;
}

hipsparseXdoti()

hipsparseStatus_t hipsparseSdoti(hipsparseHandle_t handle, int nnz, const float *xVal, const int *xInd, const float *y, float *result, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseDdoti(hipsparseHandle_t handle, int nnz, const double *xVal, const int *xInd, const double *y, double *result, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseCdoti(hipsparseHandle_t handle, int nnz, const hipComplex *xVal, const int *xInd, const hipComplex *y, hipComplex *result, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseZdoti(hipsparseHandle_t handle, int nnz, const hipDoubleComplex *xVal, const int *xInd, const hipDoubleComplex *y, hipDoubleComplex *result, hipsparseIndexBase_t idxBase)

Compute the dot product of a sparse vector with a dense vector.

hipsparseXdoti computes the dot product of the sparse vector \(x\) with the dense vector \(y\), such that

\[ result := y^T x \]

result = 0
for(i = 0; i < nnz; ++i)
{
    result += xVal[i] * y[xInd[i]];
}

Deprecated:

This function is deprecated when using the CUDA backend (CUDA 10.0+) and will be removed in CUDA 11.0. This deprecation does not apply to the ROCm backend.

Note

This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

Note

If nnz is zero, the function returns successfully with result set to zero.

Parameters:

• handle – [in] handle to the hipsparse library context queue.

• nnz – [in] number of non-zero entries of vector \(x\). Must be non-negative.

• xVal – [in] array of nnz values containing the elements of \(x\).

• xInd – [in] array of nnz elements containing the indices of the non-zero values of \(x\).

• y – [in] array of values in dense format. Must be pre-allocated with sufficient size to accommodate all indices specified in xInd.

• result – [out] pointer to the result, can be host or device memory.

• idxBase – [in] index base. HIPSPARSE_INDEX_BASE_ZERO for zero-based indexing or HIPSPARSE_INDEX_BASE_ONE for one-based indexing.

Return values:

• HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

• HIPSPARSE_STATUS_NOT_INITIALIZED – handle is not initialized.

• HIPSPARSE_STATUS_INVALID_VALUE – handle or result is nullptr, nnz is negative, xVal, xInd or y is nullptr when nnz is greater than zero, or idxBase is neither HIPSPARSE_INDEX_BASE_ZERO nor HIPSPARSE_INDEX_BASE_ONE.

• HIPSPARSE_STATUS_ALLOC_FAILED – the buffer for the dot product reduction could not be allocated.

• HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

C++CFortran

int main(int argc, char* argv[])
{
    // Number of non-zeros of the sparse vector
    const int nnz = 3;

    // Number of entries in the dense vector
    const int size = 9;

    // Sparse index vector
    std::vector<int> hxInd = {0, 3, 5};

    // Sparse value vector
    std::vector<float> hxVal = {1.0f, 2.0f, 3.0f};

    // Dense vector
    std::vector<float> hy = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f, 9.0f};

    // Index base
    hipsparseIndexBase_t idxBase = HIPSPARSE_INDEX_BASE_ZERO;

    // Offload data to device
    int*   dxInd;
    float* dxVal;
    float* dy;

    HIP_CHECK(hipMalloc((void**)&dxInd, sizeof(int) * nnz));
    HIP_CHECK(hipMalloc((void**)&dxVal, sizeof(float) * nnz));
    HIP_CHECK(hipMalloc((void**)&dy, sizeof(float) * size));

    HIP_CHECK(hipMemcpy(dxInd, hxInd.data(), sizeof(int) * nnz, hipMemcpyHostToDevice));
    HIP_CHECK(hipMemcpy(dxVal, hxVal.data(), sizeof(float) * nnz, hipMemcpyHostToDevice));
    HIP_CHECK(hipMemcpy(dy, hy.data(), sizeof(float) * size, hipMemcpyHostToDevice));

    // hipSPARSE handle
    hipsparseHandle_t handle;
    HIPSPARSE_CHECK(hipsparseCreate(&handle));

    // Call sdoti to compute the dot product
    float dot;
    HIPSPARSE_CHECK(hipsparseSdoti(handle, nnz, dxVal, dxInd, dy, &dot, idxBase));

    std::cout << "dot: " << dot << std::endl;

    // Clear hipSPARSE
    HIPSPARSE_CHECK(hipsparseDestroy(handle));

    // Clear device memory
    HIP_CHECK(hipFree(dxInd));
    HIP_CHECK(hipFree(dxVal));
    HIP_CHECK(hipFree(dy));

    return 0;
}

hipsparseXdotci()

hipsparseStatus_t hipsparseCdotci(hipsparseHandle_t handle, int nnz, const hipComplex *xVal, const int *xInd, const hipComplex *y, hipComplex *result, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseZdotci(hipsparseHandle_t handle, int nnz, const hipDoubleComplex *xVal, const int *xInd, const hipDoubleComplex *y, hipDoubleComplex *result, hipsparseIndexBase_t idxBase)

Compute the dot product of a complex conjugate sparse vector with a dense vector.

hipsparseXdotci computes the dot product of the complex conjugate sparse vector \(x\) with the dense vector \(y\), such that

\[ result := \bar{x}^H y \]

result = 0
for(i = 0; i < nnz; ++i)
{
    result += conj(xVal[i]) * y[xInd[i]];
}

Deprecated:

This function is deprecated when using the CUDA backend (CUDA 10.0+) and will be removed in CUDA 11.0. This deprecation does not apply to the ROCm backend.

Note

This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

Note

If nnz is zero, the function returns successfully with result set to zero.

Parameters:

• handle – [in] handle to the hipsparse library context queue.

• nnz – [in] number of non-zero entries of vector \(x\). Must be non-negative.

• xVal – [in] array of nnz values containing the elements of \(x\).

• xInd – [in] array of nnz elements containing the indices of the non-zero values of \(x\).

• y – [in] array of values in dense format. Must be pre-allocated with sufficient size to accommodate all indices specified in xInd.

• result – [out] pointer to the result, can be host or device memory.

• idxBase – [in] index base. HIPSPARSE_INDEX_BASE_ZERO for zero-based indexing or HIPSPARSE_INDEX_BASE_ONE for one-based indexing.

Return values:

• HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

• HIPSPARSE_STATUS_NOT_INITIALIZED – handle is not initialized.

• HIPSPARSE_STATUS_INVALID_VALUE – handle or result is nullptr, nnz is negative, xVal, xInd or y is nullptr when nnz is greater than zero, or idxBase is neither HIPSPARSE_INDEX_BASE_ZERO nor HIPSPARSE_INDEX_BASE_ONE.

• HIPSPARSE_STATUS_ALLOC_FAILED – the buffer for the dot product reduction could not be allocated.

• HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

hipsparseXgthr()

hipsparseStatus_t hipsparseSgthr(hipsparseHandle_t handle, int nnz, const float *y, float *xVal, const int *xInd, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseDgthr(hipsparseHandle_t handle, int nnz, const double *y, double *xVal, const int *xInd, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseCgthr(hipsparseHandle_t handle, int nnz, const hipComplex *y, hipComplex *xVal, const int *xInd, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseZgthr(hipsparseHandle_t handle, int nnz, const hipDoubleComplex *y, hipDoubleComplex *xVal, const int *xInd, hipsparseIndexBase_t idxBase)

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

hipsparseXgthr gathers the elements that are listed in xInd from the dense vector \(y\) and stores them in the sparse vector \(x\).

for(i = 0; i < nnz; ++i)
{
    xVal[i] = y[xInd[i]];
}

Deprecated:

This function is deprecated when using the CUDA backend (CUDA 11.0+) and will be removed in CUDA 12.0. This deprecation does not apply to the ROCm backend.

Note

This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

Note

If nnz is zero, the function returns successfully without modifying xVal.

Parameters:

• handle – [in] handle to the hipsparse library context queue.

• nnz – [in] number of non-zero entries of \(x\). Must be non-negative.

• y – [in] array of values in dense format. Must be pre-allocated with sufficient size to accommodate all indices specified in xInd.

• xVal – [out] array of nnz elements that will contain the gathered values of \(x\).

• xInd – [in] array of nnz elements containing the indices of the non-zero values of \(x\).

• idxBase – [in] index base. HIPSPARSE_INDEX_BASE_ZERO for zero-based indexing or HIPSPARSE_INDEX_BASE_ONE for one-based indexing.

Return values:

• HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

• HIPSPARSE_STATUS_NOT_INITIALIZED – handle is not initialized.

• HIPSPARSE_STATUS_INVALID_VALUE – handle is nullptr, nnz is negative, y, xVal or xInd is nullptr when nnz is greater than zero, or idxBase is neither HIPSPARSE_INDEX_BASE_ZERO nor HIPSPARSE_INDEX_BASE_ONE.

C++CFortran

int main(int argc, char* argv[])
{
    // Number of non-zeros of the sparse vector
    const int nnz = 3;

    // Number of entries in the dense vector
    const int size = 9;

    // Sparse index vector
    std::vector<int> hxInd = {0, 3, 5};

    // Sparse value vector
    std::vector<float> hxVal(nnz);

    // Dense vector
    std::vector<float> hy = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f, 9.0f};

    // Index base
    hipsparseIndexBase_t idxBase = HIPSPARSE_INDEX_BASE_ZERO;

    // Offload data to device
    int*   dxInd;
    float* dxVal;
    float* dy;

    HIP_CHECK(hipMalloc((void**)&dxInd, sizeof(int) * nnz));
    HIP_CHECK(hipMalloc((void**)&dxVal, sizeof(float) * nnz));
    HIP_CHECK(hipMalloc((void**)&dy, sizeof(float) * size));

    HIP_CHECK(hipMemcpy(dxInd, hxInd.data(), sizeof(int) * nnz, hipMemcpyHostToDevice));
    HIP_CHECK(hipMemcpy(dy, hy.data(), sizeof(float) * size, hipMemcpyHostToDevice));

    // hipSPARSE handle
    hipsparseHandle_t handle;
    HIPSPARSE_CHECK(hipsparseCreate(&handle));

    // Call sgthr
    HIPSPARSE_CHECK(hipsparseSgthr(handle, nnz, dy, dxVal, dxInd, idxBase));

    // Copy result back to host
    HIP_CHECK(hipMemcpy(hxVal.data(), dxVal, sizeof(float) * nnz, hipMemcpyDeviceToHost));

    std::cout << "hxVal" << std::endl;
    for(int i = 0; i < nnz; i++)
    {
        std::cout << hxVal[i] << " ";
    }
    std::cout << std::endl;

    // Clear hipSPARSE
    HIPSPARSE_CHECK(hipsparseDestroy(handle));

    // Clear device memory
    HIP_CHECK(hipFree(dxInd));
    HIP_CHECK(hipFree(dxVal));
    HIP_CHECK(hipFree(dy));

    return 0;
}

hipsparseXgthrz()

hipsparseStatus_t hipsparseSgthrz(hipsparseHandle_t handle, int nnz, float *y, float *xVal, const int *xInd, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseDgthrz(hipsparseHandle_t handle, int nnz, double *y, double *xVal, const int *xInd, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseCgthrz(hipsparseHandle_t handle, int nnz, hipComplex *y, hipComplex *xVal, const int *xInd, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseZgthrz(hipsparseHandle_t handle, int nnz, hipDoubleComplex *y, hipDoubleComplex *xVal, const int *xInd, hipsparseIndexBase_t idxBase)

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

hipsparseXgthrz gathers the elements that are listed in xInd from the dense vector \(y\) and stores them in the sparse vector \(x\). The gathered elements in \(y\) are replaced by zero.

for(i = 0; i < nnz; ++i)
{
    xVal[i]    = y[xInd[i]];
    y[xInd[i]] = 0;
}

Deprecated:

This function is deprecated when using the CUDA backend (CUDA 11.0+) and will be removed in CUDA 12.0. This deprecation does not apply to the ROCm backend.

Note

This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

Note

If nnz is zero, the function returns successfully without modifying xVal or y.

Parameters:

• handle – [in] handle to the hipsparse library context queue.

• nnz – [in] number of non-zero entries of \(x\). Must be non-negative.

• y – [inout] array of values in dense format. Must be pre-allocated with sufficient size to accommodate all indices specified in xInd. Gathered elements are set to zero.

• xVal – [out] array of nnz elements that will contain the gathered values of \(x\).

• xInd – [in] array of nnz elements containing the indices of the non-zero values of \(x\).

• idxBase – [in] index base. HIPSPARSE_INDEX_BASE_ZERO for zero-based indexing or HIPSPARSE_INDEX_BASE_ONE for one-based indexing.

Return values:

• HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

• HIPSPARSE_STATUS_NOT_INITIALIZED – handle is not initialized.

• HIPSPARSE_STATUS_INVALID_VALUE – handle is nullptr, nnz is negative, y, xVal or xInd is nullptr when nnz is greater than zero, or idxBase is neither HIPSPARSE_INDEX_BASE_ZERO nor HIPSPARSE_INDEX_BASE_ONE.

hipsparseXroti()

hipsparseStatus_t hipsparseSroti(hipsparseHandle_t handle, int nnz, float *xVal, const int *xInd, float *y, const float *c, const float *s, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseDroti(hipsparseHandle_t handle, int nnz, double *xVal, const int *xInd, double *y, const double *c, const double *s, hipsparseIndexBase_t idxBase)

Apply Givens rotation to a dense and a sparse vector.

hipsparseXroti applies the Givens rotation matrix \(G\) to the sparse vector \(x\) and the dense vector \(y\), where

\[\begin{split} G = \begin{pmatrix} c & s \\ -s & c \end{pmatrix} \end{split}\]

for(i = 0; i < nnz; ++i)
{
    x_tmp = xVal[i];
    y_tmp = y[xInd[i]];

    xVal[i]    = c * x_tmp + s * y_tmp;
    y[xInd[i]] = c * y_tmp - s * x_tmp;
}

Deprecated:

This function is deprecated when using the CUDA backend (CUDA 11.0+) and will be removed in CUDA 12.0. This deprecation does not apply to the ROCm backend.

Note

This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

Note

If nnz is zero, the function returns successfully without modifying xVal or y.

Parameters:

• handle – [in] handle to the hipsparse library context queue.

• nnz – [in] number of non-zero entries of \(x\). Must be non-negative.

• xVal – [inout] array of nnz elements containing the non-zero values of \(x\).

• xInd – [in] array of nnz elements containing the indices of the non-zero values of \(x\).

• y – [inout] array of values in dense format. Must be pre-allocated with sufficient size to accommodate all indices specified in xInd.

• c – [in] pointer to the cosine element of \(G\), can be on host or device.

• s – [in] pointer to the sine element of \(G\), can be on host or device.

• idxBase – [in] index base. HIPSPARSE_INDEX_BASE_ZERO for zero-based indexing or HIPSPARSE_INDEX_BASE_ONE for one-based indexing.

Return values:

• HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

• HIPSPARSE_STATUS_NOT_INITIALIZED – handle is not initialized.

• HIPSPARSE_STATUS_INVALID_VALUE – handle, c or s is nullptr, nnz is negative, xVal, xInd or y is nullptr when nnz is greater than zero, or idxBase is neither HIPSPARSE_INDEX_BASE_ZERO nor HIPSPARSE_INDEX_BASE_ONE.

C++CFortran

int main(int argc, char* argv[])
{
    // Number of non-zeros of the sparse vector
    const int nnz = 3;

    // Number of entries in the dense vector
    const int size = 9;

    // Sparse index vector
    std::vector<int> hxInd = {0, 3, 5};

    // Sparse value vector
    std::vector<float> hxVal = {1.0f, 2.0f, 3.0f};

    // Dense vector
    std::vector<float> hy = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f, 9.0f};

    // c and s
    float c = 3.7;
    float s = 1.3;

    // Index base
    hipsparseIndexBase_t idxBase = HIPSPARSE_INDEX_BASE_ZERO;

    // Offload data to device
    int*   dxInd;
    float* dxVal;
    float* dy;

    HIP_CHECK(hipMalloc((void**)&dxInd, sizeof(int) * nnz));
    HIP_CHECK(hipMalloc((void**)&dxVal, sizeof(float) * nnz));
    HIP_CHECK(hipMalloc((void**)&dy, sizeof(float) * size));

    HIP_CHECK(hipMemcpy(dxInd, hxInd.data(), sizeof(int) * nnz, hipMemcpyHostToDevice));
    HIP_CHECK(hipMemcpy(dxVal, hxVal.data(), sizeof(float) * nnz, hipMemcpyHostToDevice));
    HIP_CHECK(hipMemcpy(dy, hy.data(), sizeof(float) * size, hipMemcpyHostToDevice));

    // hipSPARSE handle
    hipsparseHandle_t handle;
    HIPSPARSE_CHECK(hipsparseCreate(&handle));

    // Call sroti
    HIPSPARSE_CHECK(hipsparseSroti(handle, nnz, dxVal, dxInd, dy, &c, &s, idxBase));

    // Copy result back to host
    HIP_CHECK(hipMemcpy(hxVal.data(), dxVal, sizeof(float) * nnz, hipMemcpyDeviceToHost));
    HIP_CHECK(hipMemcpy(hy.data(), dy, sizeof(float) * size, hipMemcpyDeviceToHost));

    std::cout << "hxVal" << std::endl;
    for(int i = 0; i < nnz; i++)
    {
        std::cout << hxVal[i] << " ";
    }
    std::cout << std::endl;

    std::cout << "hy" << std::endl;
    for(int i = 0; i < size; i++)
    {
        std::cout << hy[i] << " ";
    }
    std::cout << std::endl;

    // Clear hipSPARSE
    HIPSPARSE_CHECK(hipsparseDestroy(handle));

    // Clear device memory
    HIP_CHECK(hipFree(dxInd));
    HIP_CHECK(hipFree(dxVal));
    HIP_CHECK(hipFree(dy));

    return 0;
}

hipsparseXsctr()

hipsparseStatus_t hipsparseSsctr(hipsparseHandle_t handle, int nnz, const float *xVal, const int *xInd, float *y, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseDsctr(hipsparseHandle_t handle, int nnz, const double *xVal, const int *xInd, double *y, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseCsctr(hipsparseHandle_t handle, int nnz, const hipComplex *xVal, const int *xInd, hipComplex *y, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseZsctr(hipsparseHandle_t handle, int nnz, const hipDoubleComplex *xVal, const int *xInd, hipDoubleComplex *y, hipsparseIndexBase_t idxBase)

Scatter elements from a dense vector across a sparse vector.

hipsparseXsctr scatters the elements that are listed in xInd from the sparse vector \(x\) into the dense vector \(y\). Indices of \(y\) that are not listed in xInd remain unchanged.

for(i = 0; i < nnz; ++i)
{
    y[xInd[i]] = xVal[i];
}

Deprecated:

This function is deprecated when using the CUDA backend (CUDA 11.0+) and will be removed in CUDA 12.0. This deprecation does not apply to the ROCm backend.

Note

This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

Note

If nnz is zero, the function returns successfully without modifying y. Duplicate indices in xInd will result in the last value being written to y.

Parameters:

• handle – [in] handle to the hipsparse library context queue.

• nnz – [in] number of non-zero entries of \(x\). Must be non-negative.

• xVal – [in] array of nnz elements containing the non-zero values of \(x\).

• xInd – [in] array of nnz elements containing the indices of the non-zero values of \(x\).

• y – [inout] array of values in dense format. Must be pre-allocated with sufficient size to accommodate all indices specified in xInd.

• idxBase – [in] index base. HIPSPARSE_INDEX_BASE_ZERO for zero-based indexing or HIPSPARSE_INDEX_BASE_ONE for one-based indexing.

Return values:

• HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

• HIPSPARSE_STATUS_NOT_INITIALIZED – handle is not initialized.

• HIPSPARSE_STATUS_INVALID_VALUE – handle is nullptr, nnz is negative, xVal, xInd or y is nullptr when nnz is greater than zero, or idxBase is neither HIPSPARSE_INDEX_BASE_ZERO nor HIPSPARSE_INDEX_BASE_ONE.

C++CFortran

int main(int argc, char* argv[])
{
    // Number of non-zeros of the sparse vector
    const int nnz = 3;

    // Number of entries in the dense vector
    const int size = 9;

    // Sparse index vector
    std::vector<int> hxInd = {0, 3, 5};

    // Sparse value vector
    std::vector<float> hxVal = {9.0, 2.0, 3.0};

    // Dense vector
    std::vector<float> hy = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0};

    // Index base
    hipsparseIndexBase_t idxBase = HIPSPARSE_INDEX_BASE_ZERO;

    // Offload data to device
    int*   dxInd;
    float* dxVal;
    float* dy;

    HIP_CHECK(hipMalloc((void**)&dxInd, sizeof(int) * nnz));
    HIP_CHECK(hipMalloc((void**)&dxVal, sizeof(float) * nnz));
    HIP_CHECK(hipMalloc((void**)&dy, sizeof(float) * size));

    HIP_CHECK(hipMemcpy(dxInd, hxInd.data(), sizeof(int) * nnz, hipMemcpyHostToDevice));
    HIP_CHECK(hipMemcpy(dxVal, hxVal.data(), sizeof(float) * nnz, hipMemcpyHostToDevice));
    HIP_CHECK(hipMemcpy(dy, hy.data(), sizeof(float) * size, hipMemcpyHostToDevice));

    // hipSPARSE handle
    hipsparseHandle_t handle;
    HIPSPARSE_CHECK(hipsparseCreate(&handle));

    // Call ssctr
    HIPSPARSE_CHECK(hipsparseSsctr(handle, nnz, dxVal, dxInd, dy, idxBase));

    // Copy result back to host
    HIP_CHECK(hipMemcpy(hy.data(), dy, sizeof(float) * size, hipMemcpyDeviceToHost));

    std::cout << "hy" << std::endl;
    for(int i = 0; i < size; i++)
    {
        std::cout << hy[i] << " ";
    }
    std::cout << std::endl;

    // Clear hipSPARSE
    HIPSPARSE_CHECK(hipsparseDestroy(handle));

    // Clear device memory
    HIP_CHECK(hipFree(dxInd));
    HIP_CHECK(hipFree(dxVal));
    HIP_CHECK(hipFree(dy));

    return 0;
}