hipSPARSE

https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/
Admin
hipSPARSE is a GPU-accelerated sparse linear algebra marshalling library that provides a common...
Tokens:66,444
Snippets:357
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Test hipSPARSE installation with example_csrmv

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/install/build-linux.html

Tests the hipSPARSE installation by running the example_csrmv example with argument 1000. Requires the library to be compiled with clients.

```bash
# Navigate to clients binary directory
cd build/release/clients/staging

# Execute hipSPARSE example
./example_csrmv 1000

```

--------------------------------

### hipsparseSgthr C++ example

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/reference/level1.html

Complete C++ example that allocates device memory, copies the dense vector and indices to the device, calls hipsparseSgthr, copies the gathered values back to the host, prints them, and cleans up. Uses HIP_CHECK, HIPSPARSE_CHECK, and hipsparseCreate/destroy. The example uses zero-based indexing and a dense vector of size 9 with 3 non-zeros.

```cpp
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;
}
```

--------------------------------

### Install amdrocm-sparse development package on Linux

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/install/install.html

Install the latest sparse math development package for supported GPU architectures. Use the command that matches your Linux distribution: apt for Debian-based, dnf for RHEL-based, and zypper for SLES. The package name includes the -dev or -devel suffix to install library files and headers.

```bash
sudo apt install amdrocm-sparse-dev

```

```bash
sudo dnf install amdrocm-sparse-devel

```

```bash
sudo zypper install amdrocm-sparse-devel

```

--------------------------------

### C++ example using hipsparseSroti

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/reference/level1.html

C++ example that allocates device memory, copies host vectors to device, calls hipsparseSroti, copies results back, and prints the updated sparse and dense vectors. It uses HIP_CHECK and HIPSPARSE_CHECK macros for error checking and cleans up with hipFree and hipsparseDestroy.

```cpp
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, hipMemcpyHostToDevice));
    HIP_CHECK(hipMemcpy(hy.data(), dy, sizeof(float) * size, hipMemcpyHostToDevice));

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

```

--------------------------------

### hipsparseXroti() Fortran example: hipsparseSroti call

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/reference/level1.html

Complete Fortran example for hipsparseXroti() that allocates device memory, copies host data, creates a hipSPARSE handle, calls hipsparseSroti with HIPSPARSE_INDEX_BASE_ZERO, copies results back, prints x and y values, then destroys the handle and frees device memory. Requires HIP_CHECK and HIPSPARSE_CHECK macros and the hipsparse module.

```fortran
program example_fortran_roti
    use iso_c_binding
    use hipsparse

    implicit none

    interface
        function hipMalloc(ptr, size) &
                bind(c, name = 'hipMalloc')
            use iso_c_binding
            implicit none
            integer :: hipMalloc
            type(c_ptr) :: ptr
            integer(c_size_t), value :: size
        end function hipMalloc

        function hipFree(ptr) &
                bind(c, name = 'hipFree')
            use iso_c_binding
            implicit none
            integer :: hipFree
            type(c_ptr), value :: ptr
        end function hipFree

        function hipMemcpy(dst, src, size, kind) &
                bind(c, name = 'hipMemcpy')
            use iso_c_binding
            implicit none
            integer :: hipMemcpy
            type(c_ptr), value :: dst
            type(c_ptr), intent(in), value :: src
            integer(c_size_t), value :: size
            integer(c_int), value :: kind
        end function hipMemcpy
    end interface

    integer, target :: h_xind(3)
    real(4), target :: h_xval(3), h_y(9)

    type(c_ptr) :: d_xind
    type(c_ptr) :: d_xval
    type(c_ptr) :: d_y

    integer :: i
    integer(c_int) :: size, nnz

    real(c_float), target :: c
    real(c_float), target :: s

    type(c_ptr) :: handle

!   Input data

!   Number of entries in the dense vector
    size = 9

!   Number of non-zero entries
    nnz = 3

!   Fill structures
    h_xind = (/0, 3, 5/)
    h_xval = (/1.0, 2.0, 3.0/)
    h_y    = (/1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0/)

!   c and s
    c = 3.7
    s = 1.3

!   Allocate device memory
    call HIP_CHECK(hipMalloc(d_xind, int(nnz, c_size_t) * 4))
    call HIP_CHECK(hipMalloc(d_xval, int(nnz, c_size_t) * 4))
    call HIP_CHECK(hipMalloc(d_y, int(size, c_size_t) * 4))

!   Copy host data to device
    call HIP_CHECK(hipMemcpy(d_xind, c_loc(h_xind), int(nnz, c_size_t) * 4, 1))
    call HIP_CHECK(hipMemcpy(d_xval, c_loc(h_xval), int(nnz, c_size_t) * 4, 1))
    call HIP_CHECK(hipMemcpy(d_y, c_loc(h_y), int(size, c_size_t) * 4, 1))

!   Create hipSPARSE handle
    call HIPSPARSE_CHECK(hipsparseCreate(handle))

!   Call sroti
    call HIPSPARSE_CHECK(hipsparseSroti(handle, &
                                        nnz, &
                                        d_xval, &
                                        d_xind, &
                                        d_y, &
                                        c_loc(c), &
                                        c_loc(s), &
                                        HIPSPARSE_INDEX_BASE_ZERO))

!   Copy results back to host
    call HIP_CHECK(hipMemcpy(c_loc(h_xval), d_xval, int(nnz, c_size_t) * 4, 2))
    call HIP_CHECK(hipMemcpy(c_loc(h_y), d_y, int(size, c_size_t) * 4, 2))

    do i = 1, nnz
        write(*,fmt='(A,I0,A,F0.2)') 'x(', h_xind(i), ') = ', h_xval(i)
    end do

    write(*,fmt='(A)',advance='no') 'y:'
    do i = 1, size
        write(*,fmt='(A,F0.2)',advance='no') ' ', h_y(i)
    end do
    write(*,*)

!   Clear hipSPARSE
    call HIPSPARSE_CHECK(hipsparseDestroy(handle))

!   Clear device memory
    call HIP_CHECK(hipFree(d_xind))
    call HIP_CHECK(hipFree(d_xval))
    call HIP_CHECK(hipFree(d_y))

end program example_fortran_roti
```

--------------------------------

### hipsparseXdoti() dot product example in C and Fortran

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/reference/level1.html

Complete C and Fortran examples for hipsparseXdoti() that compute the dot product of a sparse vector and a dense vector using hipsparseSdoti. Both versions allocate device memory, copy host data, create a hipSPARSE handle, call the routine, print the result, and clean up. The Fortran version includes explicit interface blocks for hipMalloc, hipFree, and hipMemcpy.

```C
 1int main(int argc, char* argv[])
 2{
 3    // Number of non-zeros of the sparse vector
 4    const int nnz = 3;
 5
 6    // Number of entries in the dense vector
 7    const int size = 9;
 8
 9    // Sparse index vector
10    int hxInd[] = {0, 3, 5};
11
12    // Sparse value vector
13    float hxVal[] = {1.0, 2.0, 3.0};
14
15    // Dense vector
16    float hy[] = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0};
17
18    // Index base
19    hipsparseIndexBase_t idxBase = HIPSPARSE_INDEX_BASE_ZERO;
20
21    // Offload data to device
22    int*   dxInd;
23    float* dxVal;
24    float* dy;
25
26    HIP_CHECK(hipMalloc((void**)&dxInd, sizeof(int) * nnz));
27    HIP_CHECK(hipMalloc((void**)&dxVal, sizeof(float) * nnz));
28    HIP_CHECK(hipMalloc((void**)&dy, sizeof(float) * size));
29
30    HIP_CHECK(hipMemcpy(dxInd, hxInd, sizeof(int) * nnz, hipMemcpyHostToDevice));
31    HIP_CHECK(hipMemcpy(dxVal, hxVal, sizeof(float) * nnz, hipMemcpyHostToDevice));
32    HIP_CHECK(hipMemcpy(dy, hy, sizeof(float) * size, hipMemcpyHostToDevice));
33
34    // hipSPARSE handle
35    hipsparseHandle_t handle;
36    HIPSPARSE_CHECK(hipsparseCreate(&handle));
37
38    // Call sdoti to compute the dot product
39    float dot;
40    HIPSPARSE_CHECK(hipsparseSdoti(handle, nnz, dxVal, dxInd, dy, &dot, idxBase));
41
42    printf("dot: %f\n", (double)dot);
43
44    // Clear hipSPARSE
45    HIPSPARSE_CHECK(hipsparseDestroy(handle));
46
47    // Clear device memory
48    HIP_CHECK(hipFree(dxInd));
49    HIP_CHECK(hipFree(dxVal));
50    HIP_CHECK(hipFree(dy));
51
52    return 0;
53}

```

```Fortran
 1program example_fortran_doti
 2    use iso_c_binding
 3    use hipsparse
 4
 5    implicit none
 6
 7    interface
 8        function hipMalloc(ptr, size) &
 9                bind(c, name = 'hipMalloc')
10            use iso_c_binding
11            implicit none
12            integer :: hipMalloc
13            type(c_ptr) :: ptr
14            integer(c_size_t), value :: size
15        end function hipMalloc
16
17        function hipFree(ptr) &
18                bind(c, name = 'hipFree')
19            use iso_c_binding
20            implicit none
21            integer :: hipFree
22            type(c_ptr), value :: ptr
23        end function hipFree
24
25        function hipMemcpy(dst, src, size, kind) &
26                bind(c, name = 'hipMemcpy')
27            use iso_c_binding
28            implicit none
29            integer :: hipMemcpy
30            type(c_ptr), value :: dst
31            type(c_ptr), intent(in), value :: src
32            integer(c_size_t), value :: size
33            integer(c_int), value :: kind
34        end function hipMemcpy
35    end interface
36
37    integer, target :: h_xind(3)
38    real(4), target :: h_xval(3), h_y(9)
39
40    type(c_ptr) :: d_xind
41    type(c_ptr) :: d_xval
42    type(c_ptr) :: d_y
43
44    integer(c_int) :: size, nnz
45    real(c_float), target :: dot
46
47    type(c_ptr) :: handle
48
!   Input data
49
!   Number of entries in the dense vector
50    size = 9
51
!   Number of non-zero entries
52    nnz = 3
53
!   Fill structures
54    h_xind = (/0, 3, 5/)
55    h_xval = (/1.0, 2.0, 3.0/)
56    h_y    = (/1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0/)
57
!   Allocate device memory
58    call HIP_CHECK(hipMalloc(d_xind, int(nnz, c_size_t) * 4))
59    call HIP_CHECK(hipMalloc(d_xval, int(nnz, c_size_t) * 4))
60    call HIP_CHECK(hipMalloc(d_y, int(size, c_size_t) * 4))
61
!   Copy host data to device
62    call HIP_CHECK(hipMemcpy(d_xind, c_loc(h_xind), int(nnz, c_size_t) * 4, 1))
63    call HIP_CHECK(hipMemcpy(d_xval, c_loc(h_xval), int(nnz, c_size_t) * 4, 1))
64    call HIP_CHECK(hipMemcpy(d_y, c_loc(h_y), int(size, c_size_t) * 4, 1))
65
!   Create hipSPARSE handle
66    call HIPSPARSE_CHECK(hipsparseCreate(handle))
67
!   Call sdoti to compute the dot product
68    call HIPSPARSE_CHECK(hipsparseSdoti(handle, &
69                                        nnz, &
70                                        d_xval, &
71                                        d_xind, &
72                                        d_y, &
73                                        c_loc(dot), &
74                                        HIPSPARSE_INDEX_BASE_ZERO))
75
76    write(*,fmt='(A,F0.2)') 'dot: ', dot
77
!   Clear hipSPARSE
78    call HIPSPARSE_CHECK(hipsparseDestroy(handle))
79
!   Clear device memory
80    call HIP_CHECK(hipFree(d_xind))
81    call HIP_CHECK(hipFree(d_xval))
82    call HIP_CHECK(hipFree(d_y))
83
84end program example_fortran_doti

```

--------------------------------

### hipsparseSpMatGetSize

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/reference/auxiliary.html

Gets the sizes of a sparse matrix.

```APIDOC
## hipsparseSpMatGetSize

### Description
Gets the sizes of a sparse matrix.

### Method
Function call

### Signature
hipsparseStatus_t hipsparseSpMatGetSize(hipsparseConstSpMatDescr_t spMatDescr, int64_t *rows, int64_t *cols, int64_t *nnz)

### Parameters
- **spMatDescr** (hipsparseConstSpMatDescr_t) - Required - The sparse matrix descriptor.
- **rows** (int64_t*) - Required - Pointer to store the number of rows.
- **cols** (int64_t*) - Required - Pointer to store the number of columns.
- **nnz** (int64_t*) - Required - Pointer to store the number of non-zero elements.

### Returns
hipsparseStatus_t - Status of the operation.
```

--------------------------------

### hipsparseSpMatGetFormat

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/reference/auxiliary.html

Gets the format of a sparse matrix.

```APIDOC
## hipsparseSpMatGetFormat

### Description
Gets the format of a sparse matrix.

### Method
Function call

### Signature
hipsparseStatus_t hipsparseSpMatGetFormat(hipsparseConstSpMatDescr_t spMatDescr, hipsparseFormat_t *format)

### Parameters
- **spMatDescr** (hipsparseConstSpMatDescr_t) - Required - The sparse matrix descriptor.
- **format** (hipsparseFormat_t*) - Required - Pointer to store the format.

### Returns
hipsparseStatus_t - Status of the operation.
```

--------------------------------

### hipsparseSdoti C++ example

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/reference/level1.html

C++ example using hipsparseSdoti to compute the dot product of a sparse vector (hxInd, hxVal) with a dense vector (hy) on the device. It allocates device memory, copies data, creates a hipSPARSE handle, calls sdoti, prints the result, and cleans up. Requires HIP_CHECK and HIPSPARSE_CHECK macros.

```cpp
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;
}
```

--------------------------------

### hipsparseSsctr C++ example

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/reference/level1.html

Complete C++ example for hipsparseSsctr: allocates device memory, copies host vectors to device, creates a hipSPARSE handle, calls hipsparseSsctr, copies the result back, prints the dense vector, and cleans up. Requires HIP_CHECK, HIPSPARSE_CHECK, and HIP_CHECK macros.

```cpp
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;
}

```

--------------------------------

### Build hipSPARSE with individual make commands

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/install/build-linux.html

Builds the hipSPARSE library from the projects/hipsparse directory. Requires CMake 3.5 or later. The default install path is /opt/rocm; use -DCMAKE_INSTALL_PREFIX=<path> to change it.

```bash
# Create and change to build directory
mkdir -p build/release ; cd build/release

# Default install path is /opt/rocm, use -DCMAKE_INSTALL_PREFIX=<path> to adjust it
cmake ../..

# Compile hipSPARSE library
make -j$(nproc)

# Install hipSPARSE to /opt/rocm
make install

```

--------------------------------

### hipsparseDaxpyi example: y = y + alpha * x (C++ and C)

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/reference/level1.html

Complete example for hipsparseDaxpyi that computes y = y + alpha * x for a sparse vector x and dense vector y. It allocates device memory, copies host data to device, calls hipsparseDaxpyi with HIPSPARSE_INDEX_BASE_ZERO, copies the result back, prints hy, and cleans up with hipsparseDestroy and hipFree. The C++ version uses std::vector and .data() for host data; the C version uses plain arrays.

```C++
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, dy, sizeof(double) * size, hipMemcpyDeviceToHost));

    printf("hy\n");
    for(int i = 0; i < size; i++)
    {
        printf("%f ", hy[i]);
    }
    printf("\n");

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

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

```C
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
    int hxInd[] = {0, 3, 5};

    // Sparse value vector
    double hxVal[] = {1.0, 2.0, 3.0};

    // Dense 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, sizeof(int) * nnz, hipMemcpyHostToDevice));
    HIP_CHECK(hipMemcpy(dxVal, hxVal, sizeof(double) * nnz, hipMemcpyHostToDevice));
    HIP_CHECK(hipMemcpy(dy, hy, 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, dy, sizeof(double) * size, hipMemcpyDeviceToHost));

    printf("hy\n");
    for(int i = 0; i < size; i++)
    {
        printf("%f ", hy[i]);
    }
    printf("\n");

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

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

--------------------------------

### hipsparseXgthr gather example in C and Fortran

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/reference/level1.html

Complete example for hipsparseXgthr (gather) in C and Fortran. The C version uses hipsparseSgthr with a dense vector, sparse indices, and index base zero; the Fortran version uses hipsparseSgthr with Fortran interfaces and hipMalloc/hipMemcpy. Both allocate device memory, copy data, call the gather routine, copy results back, and clean up.

```c
 1int main(int argc, char* argv[])
 2{
 3    // Number of non-zeros of the sparse vector
 4    const int nnz = 3;
 5
 6    // Number of entries in the dense vector
 7    const int size = 9;
 8
 9    // Sparse index vector
10    int hxInd[] = {0, 3, 5};
11
12    // Sparse value vector
13    float hxVal[nnz];
14
15    // Dense vector
16    float hy[] = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0};
17
18    // Index base
19    hipsparseIndexBase_t idxBase = HIPSPARSE_INDEX_BASE_ZERO;
20
21    // Offload data to device
22    int*   dxInd;
23    float* dxVal;
24    float* dy;
25
26    HIP_CHECK(hipMalloc((void**)&dxInd, sizeof(int) * nnz));
27    HIP_CHECK(hipMalloc((void**)&dxVal, sizeof(float) * nnz));
28    HIP_CHECK(hipMalloc((void**)&dy, sizeof(float) * size));
29
30    HIP_CHECK(hipMemcpy(dxInd, hxInd, sizeof(int) * nnz, hipMemcpyHostToDevice));
31    HIP_CHECK(hipMemcpy(dy, hy, sizeof(float) * size, hipMemcpyHostToDevice));
32
33    // hipSPARSE handle
34    hipsparseHandle_t handle;
35    HIPSPARSE_CHECK(hipsparseCreate(&handle));
36
37    // Call sgthr
38    HIPSPARSE_CHECK(hipsparseSgthr(handle, nnz, dy, dxVal, dxInd, idxBase));
39
40    // Copy result back to host
41    HIP_CHECK(hipMemcpy(hxVal, dxVal, sizeof(float) * nnz, hipMemcpyDeviceToHost));
42
43    printf("hxVal\n");
44    for(int i = 0; i < nnz; i++)
45    {
46        printf("%f ", hxVal[i]);
47    }
48    printf("\n");
49
50    // Clear hipSPARSE
51    HIPSPARSE_CHECK(hipsparseDestroy(handle));
52
53    // Clear device memory
54    HIP_CHECK(hipFree(dxInd));
55    HIP_CHECK(hipFree(dxVal));
56    HIP_CHECK(hipFree(dy));
57
58    return 0;
59}

```

```fortran
 1program example_fortran_gthr
 2    use iso_c_binding
 3    use hipsparse
 4
 5    implicit none
 6
 7    interface
 8        function hipMalloc(ptr, size) &
 9                bind(c, name = 'hipMalloc')
10            use iso_c_binding
11            implicit none
12            integer :: hipMalloc
13            type(c_ptr) :: ptr
14            integer(c_size_t), value :: size
15        end function hipMalloc
16
17        function hipFree(ptr) &
18                bind(c, name = 'hipFree')
19            use iso_c_binding
20            implicit none
21            integer :: hipFree
22            type(c_ptr), value :: ptr
23        end function hipFree
24
25        function hipMemcpy(dst, src, size, kind) &
26                bind(c, name = 'hipMemcpy')
27            use iso_c_binding
28            implicit none
29            integer :: hipMemcpy
30            type(c_ptr), value :: dst
31            type(c_ptr), intent(in), value :: src
32            integer(c_size_t), value :: size
33            integer(c_int), value :: kind
34        end function hipMemcpy
35    end interface
36
37    integer, target :: h_xind(3)
38    real(4), target :: h_xval(3), h_y(9)
39
40    type(c_ptr) :: d_xind
41    type(c_ptr) :: d_xval
42    type(c_ptr) :: d_y
43
44    integer :: i
45    integer(c_int) :: size, nnz
46
47    type(c_ptr) :: handle
48
49!   Input data
50
51!   Number of entries in the dense vector
52    size = 9
53
54!   Number of non-zero entries
55    nnz = 3
56
57!   Fill structures
58    h_xind = (/0, 3, 5/)
59    h_y    = (/1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0/)
60
61!   Allocate device memory
62    call HIP_CHECK(hipMalloc(d_xind, int(nnz, c_size_t) * 4))
63    call HIP_CHECK(hipMalloc(d_xval, int(nnz, c_size_t) * 4))
64    call HIP_CHECK(hipMalloc(d_y, int(size, c_size_t) * 4))
65
66!   Copy host data to device
67    call HIP_CHECK(hipMemcpy(d_xind, c_loc(h_xind), int(nnz, c_size_t) * 4, 1))
68    call HIP_CHECK(hipMemcpy(d_y, c_loc(h_y), int(size, c_size_t) * 4, 1))
69
70!   Create hipSPARSE handle
71    call HIPSPARSE_CHECK(hipsparseCreate(handle))
72
73!   Call sgthr
74    call HIPSPARSE_CHECK(hipsparseSgthr(handle, &
75                                        nnz, &
76                                        d_y, &
77                                        d_xval, &
78                                        d_xind, &
79                                        HIPSPARSE_INDEX_BASE_ZERO))
80
81!   Copy result back to host
82    call HIP_CHECK(hipMemcpy(c_loc(h_xval), d_xval, int(nnz, c_size_t) * 4, 2))
83
84    write(*,fmt='(A)',advance='no') 'hxVal:'
85    do i = 1, nnz
86        write(*,fmt='(A,F0.2)',advance='no') ' ', h_xval(i)
87    end do
88    write(*,*)
89
90!   Clear hipSPARSE
91    call HIPSPARSE_CHECK(hipsparseDestroy(handle))
92
93!   Clear device memory
94    call HIP_CHECK(hipFree(d_xind))
95    call HIP_CHECK(hipFree(d_xval))
96    call HIP_CHECK(hipFree(d_y))
97
98end program example_fortran_gthr

```

--------------------------------

### Add HIP SDK tools to PATH

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/install/build-windows.html

Adds the HIP SDK tools to the system PATH. The HIP_PATH environment variable should point to the HIP SDK installation directory.

```batch
%HIP_PATH%\bin

```

--------------------------------

### hipsparseConstCooGet()

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/reference/auxiliary.html

Gets the fields of a sparse COO matrix descriptor.

```APIDOC
## hipsparseConstCooGet()

### Description
Gets the fields of a sparse COO matrix descriptor.

### Method
N/A

### Endpoint
N/A

### Parameters
#### Function Parameters
- **spMatDescr** (hipsparseConstSpMatDescr_t) - Required - The sparse matrix descriptor.
- **rows** (int64_t*) - Required - Pointer to store the number of rows.
- **cols** (int64_t*) - Required - Pointer to store the number of columns.
- **nnz** (int64_t*) - Required - Pointer to store the number of non-zero elements.
- **cooRowInd** (const void**) - Required - Pointer to store the row indices.
- **cooColInd** (const void**) - Required - Pointer to store the column indices.
- **cooValues** (const void**) - Required - Pointer to store the values.
- **idxType** (hipsparseIndexType_t*) - Required - Pointer to store the index type.
- **idxBase** (hipsparseIndexBase_t*) - Required - Pointer to store the index base.
- **valueType** (hipDataType*) - Required - Pointer to store the value type.

### Request Example
N/A

### Response
#### Success Response
- **hipsparseStatus_t** - Status code indicating success or failure.

#### Response Example
N/A

### Error Handling
N/A
```

--------------------------------

### hipsparseCooGet()

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/reference/auxiliary.html

Gets the fields of a sparse COO matrix descriptor.

```APIDOC
## hipsparseCooGet()

### Description
Gets the fields of a sparse COO matrix descriptor.

### Method
N/A

### Endpoint
N/A

### Parameters
#### Function Parameters
- **spMatDescr** (const hipsparseSpMatDescr_t) - Required - The sparse matrix descriptor.
- **rows** (int64_t*) - Required - Pointer to store the number of rows.
- **cols** (int64_t*) - Required - Pointer to store the number of columns.
- **nnz** (int64_t*) - Required - Pointer to store the number of non-zero elements.
- **cooRowInd** (void**) - Required - Pointer to store the row indices.
- **cooColInd** (void**) - Required - Pointer to store the column indices.
- **cooValues** (void**) - Required - Pointer to store the values.
- **idxType** (hipsparseIndexType_t*) - Required - Pointer to store the index type.
- **idxBase** (hipsparseIndexBase_t*) - Required - Pointer to store the index base.
- **valueType** (hipDataType*) - Required - Pointer to store the value type.

### Request Example
N/A

### Response
#### Success Response
- **hipsparseStatus_t** - Status code indicating success or failure.

#### Response Example
N/A

### Error Handling
N/A
```

--------------------------------

### hipsparseConstCscGet

Source: https://rocm.docs.amd.com/projects/hipSPARSE/en/latest/reference/auxiliary.html

Get the pointers of a sparse CSC matrix. `hipsparseConstCscGet` gets the fields of the sparse CSC matrix descriptor.

```APIDOC
## hipsparseConstCscGet

### Description
Get the pointers of a sparse CSC matrix. `hipsparseConstCscGet` gets the fields of the sparse CSC matrix descriptor.

### Method
Function call

### Signature
hipsparseStatus_t hipsparseConstCscGet(hipsparseConstSpMatDescr_t spMatDescr, int64_t *rows, int64_t *cols, int64_t *nnz, const void **cscColOffsets, const void **cscRowInd, const void **cscValues, hipsparseIndexType_t *cscColOffsetsType, hipsparseIndexType_t *cscRowIndType, hipsparseIndexBase_t *idxBase, hipDataType *valueType)

### Parameters
- **spMatDescr** (hipsparseConstSpMatDescr_t) - Input - Sparse matrix descriptor.
- **rows** (int64_t*) - Output - Number of rows.
- **cols** (int64_t*) - Output - Number of columns.
- **nnz** (int64_t*) - Output - Number of non-zero elements.
- **cscColOffsets** (const void**) - Output - Pointer to CSC column offsets array.
- **cscRowInd** (const void**) - Output - Pointer to CSC row indices array.
- **cscValues** (const void**) - Output - Pointer to CSC values array.
- **cscColOffsetsType** (hipsparseIndexType_t*) - Output - Index type of column offsets.
- **cscRowIndType** (hipsparseIndexType_t*) - Output - Index type of row indices.
- **idxBase** (hipsparseIndexBase_t*) - Output - Index base.
- **valueType** (hipDataType*) - Output - Data type of values.

### Return Value
hipsparseStatus_t - Status of the operation.
```
Tokens:
Raw