# hipSPARSE User Guide#

## HIP Device Management#

Before starting a HIP kernel you can call `hipSetDevice()`

to set a device. If you do not call the function, the system uses the default device. Unless you explicitly call `hipSetDevice()`

to specify another device, HIP kernels are always launched on device 0.
This is a HIP (and CUDA) device management approach and is not specific to the hipSPARSE library. hipSPARSE honors this approach and assumes you have already set the preferred device before a hipSPARSE routine call.

Once you set the device, you can create a handle with hipsparseCreate().
Subsequent hipSPARSE routines take this handle as an input parameter. hipSPARSE ONLY queries (by `hipGetDevice()`

) the specified device. If hipSPARSE does not see a valid device, it returns an error message. It is you responsibility to provide a valid device to hipSPARSE and ensure the device safety.

If you want to change device, you must destroy the current handle using hipsparseDestroy(), and create another handle using hipsparseCreate() specifying another device.

Note

`hipSetDevice()`

and `hipGetDevice()`

are NOT part of the hipSPARSE API. They are part of the HIP Runtime API - Device Management.

## HIP Stream Management#

HIP kernels are always launched in a queue (also known as stream). If you do not explicitly specify a stream, the system provides and maintains a default stream. You cannot create or destroy the default stream. However, you can freely create new streams (with `hipStreamCreate()`

) and bind it to the hipSPARSE handle using hipsparseSetStream(). HIP kernels are invoked in hipSPARSE routines. The hipSPARSE handle is always associated with a stream, and hipSPARSE passes its stream to the kernels inside the routine. One hipSPARSE routine only takes one stream in a single invocation. If you create a stream, you are responsible for destroying it. Refer to HIP Runtime API - Stream Management for more information.

## Asynchronous Execution#

Except functions having memory allocation inside preventing asynchronicity, all hipSPARSE library functions are non-blocking and executed asynchronously with respect to the host, unless otherwise stated. The function may return before the actual computation has finished. To force synchronization, use either `hipDeviceSynchronize()`

or `hipStreamSynchronize()`

. This will ensure that all previously executed hipSPARSE functions on the device, or in the particular stream, have completed.

## Multiple Streams and Multiple Devices#

If a system has multiple HIP devices, you can run multiple hipSPARSE handles concurrently. However, you can NOT run a single hipSPARSE handle on different discrete devices. Each handle is associated with a particular single device, and a new handle should be created for each additional device.

## Storage Formats#

The following describes supported matrix storage formats.

Note

The different storage formats support indexing from a base of 0 or 1 as described in Storage schemes and indexing base.

### COO storage format#

The Coordinate (COO) storage format represents a \(m \times n\) matrix by

m |
number of rows (integer). |

n |
number of columns (integer). |

nnz |
number of non-zero elements (integer). |

coo_val |
array of |

coo_row_ind |
array of |

coo_col_ind |
array of |

The COO matrix is expected to be sorted by row indices and column indices per row. Furthermore, each pair of indices should appear only once. Consider the following \(3 \times 5\) matrix and the corresponding COO structures, with \(m = 3, n = 5\) and \(\text{nnz} = 8\) using zero based indexing:

where

### COO (AoS) storage format#

The Coordinate (COO) Array of Structure (AoS) storage format represents a \(m \times n\) matrix by

m |
number of rows (integer). |

n |
number of columns (integer). |

nnz |
number of non-zero elements (integer). |

coo_val |
array of |

coo_ind |
array of |

The COO (AoS) matrix is expected to be sorted by row indices and column indices per row. Furthermore, each pair of indices should appear only once. Consider the following \(3 \times 5\) matrix and the corresponding COO (AoS) structures, with \(m = 3, n = 5\) and \(\text{nnz} = 8\) using zero based indexing:

where

### CSR storage format#

The Compressed Sparse Row (CSR) storage format represents a \(m \times n\) matrix by

m |
number of rows (integer). |

n |
number of columns (integer). |

nnz |
number of non-zero elements (integer). |

csr_val |
array of |

csr_row_ptr |
array of |

csr_col_ind |
array of |

The CSR matrix is expected to be sorted by column indices within each row. Furthermore, each pair of indices should appear only once. Consider the following \(3 \times 5\) matrix and the corresponding CSR structures, with \(m = 3, n = 5\) and \(\text{nnz} = 8\) using one based indexing:

where

### CSC storage format#

The Compressed Sparse Column (CSC) storage format represents a \(m \times n\) matrix by

m |
number of rows (integer). |

n |
number of columns (integer). |

nnz |
number of non-zero elements (integer). |

csc_val |
array of |

csc_col_ptr |
array of |

csc_row_ind |
array of |

The CSC matrix is expected to be sorted by row indices within each column. Furthermore, each pair of indices should appear only once. Consider the following \(3 \times 5\) matrix and the corresponding CSC structures, with \(m = 3, n = 5\) and \(\text{nnz} = 8\) using one based indexing:

where

### BSR storage format#

The Block Compressed Sparse Row (BSR) storage format represents a \((mb \cdot \text{bsr_dim}) \times (nb \cdot \text{bsr_dim})\) matrix by

mb |
number of block rows (integer) |

nb |
number of block columns (integer) |

nnzb |
number of non-zero blocks (integer) |

bsr_val |
array of |

bsr_row_ptr |
array of |

bsr_col_ind |
array of |

bsr_dim |
dimension of each block (integer). |

The BSR matrix is expected to be sorted by column indices within each row. If \(m\) or \(n\) are not evenly divisible by the block dimension, then zeros are padded to the matrix, such that \(mb = (m + \text{bsr_dim} - 1) / \text{bsr_dim}\) and \(nb = (n + \text{bsr_dim} - 1) / \text{bsr_dim}\). Consider the following \(4 \times 3\) matrix and the corresponding BSR structures, with \(\text{bsr_dim} = 2, mb = 2, nb = 2\) and \(\text{nnzb} = 4\) using zero based indexing and column-major storage:

with the blocks \(A_{ij}\)

such that

with arrays representation

### GEBSR storage format#

The General Block Compressed Sparse Row (GEBSR) storage format represents a \((mb \cdot \text{bsr_row_dim}) \times (nb \cdot \text{bsr_col_dim})\) matrix by

mb |
number of block rows (integer) |

nb |
number of block columns (integer) |

nnzb |
number of non-zero blocks (integer) |

bsr_val |
array of |

bsr_row_ptr |
array of |

bsr_col_ind |
array of |

bsr_row_dim |
row dimension of each block (integer). |

bsr_col_dim |
column dimension of each block (integer). |

The GEBSR matrix is expected to be sorted by column indices within each row. If \(m\) is not evenly divisible by the row block dimension or \(n\) is not evenly divisible by the column block dimension, then zeros are padded to the matrix, such that \(mb = (m + \text{bsr_row_dim} - 1) / \text{bsr_row_dim}\) and \(nb = (n + \text{bsr_col_dim} - 1) / \text{bsr_col_dim}\). Consider the following \(4 \times 5\) matrix and the corresponding GEBSR structures, with \(\text{bsr_row_dim} = 2\), \(\text{bsr_col_dim} = 3\), mb = 2, nb = 2` and \(\text{nnzb} = 4\) using zero based indexing and column-major storage:

with the blocks \(A_{ij}\)

such that

with arrays representation

### ELL storage format#

The Ellpack-Itpack (ELL) storage format represents a \(m \times n\) matrix by

m |
number of rows (integer). |

n |
number of columns (integer). |

ell_width |
maximum number of non-zero elements per row (integer) |

ell_val |
array of |

ell_col_ind |
array of |

The ELL matrix is assumed to be stored in column-major format. Rows with less than `ell_width`

non-zero elements are padded with zeros (`ell_val`

) and \(-1\) (`ell_col_ind`

).
Consider the following \(3 \times 5\) matrix and the corresponding ELL structures, with \(m = 3, n = 5\) and \(\text{ell_width} = 3\) using zero based indexing:

where

### HYB storage format#

The Hybrid (HYB) storage format represents a \(m \times n\) matrix by

m |
number of rows (integer). |

n |
number of columns (integer). |

nnz |
number of non-zero elements of the COO part (integer) |

ell_width |
maximum number of non-zero elements per row of the ELL part (integer) |

ell_val |
array of |

ell_col_ind |
array of |

coo_val |
array of |

coo_row_ind |
array of |

coo_col_ind |
array of |

The HYB format is a combination of the ELL and COO sparse matrix formats. Typically, the regular part of the matrix is stored in ELL storage format, and the irregular part of the matrix is stored in COO storage format. Three different partitioning schemes can be applied when converting a CSR matrix to a matrix in HYB storage format. For further details on the partitioning schemes, see hipsparseHybPartition_t.

## Storage schemes and indexing base#

hipSPARSE supports 0 and 1 based indexing.
The index base is selected by the `hipsparseIndexBase_t`

type which is either passed as standalone parameter or as part of the `hipsparseMatDescr_t`

type.

Furthermore, dense vectors are represented with a 1D array, stored linearly in memory. Sparse vectors are represented by a 1D data array stored linearly in memory that hold all non-zero elements and a 1D indexing array stored linearly in memory that hold the positions of the corresponding non-zero elements.

## Pointer mode#

The auxiliary functions `hipsparseSetPointerMode()`

and `hipsparseGetPointerMode()`

are used to set and get the value of the state variable `hipsparsePointerMode_t`

.
If `hipsparsePointerMode_t`

is equal to `HIPSPARSE_POINTER_MODE_HOST`

, then scalar parameters must be allocated on the host.
If `hipsparsePointerMode_t`

is equal to `HIPSPARSE_POINTER_MODE_DEVICE`

, then scalar parameters must be allocated on the device.

There are two types of scalar parameter:

Scaling parameters, such as alpha and beta used for example in

`hipsparseScsrmv()`

and`hipsparseSbsrmv()`

Scalar results from functions such as

`hipsparseSdoti()`

or`hipsparseCdotci()`

For scalar parameters such as alpha and beta, memory can be allocated on the host heap or stack, when `hipsparsePointerMode_t`

is equal to `HIPSPARSE_POINTER_MODE_HOST`

.
The kernel launch is asynchronous, and if the scalar parameter is on the heap, it can be freed after the return from the kernel launch.
When `hipsparsePointerMode_t`

is equal to `HIPSPARSE_POINTER_MODE_DEVICE`

, the scalar parameter must not be changed till the kernel completes.

For scalar results, when `hipsparsePointerMode_t`

is equal to `HIPSPARSE_POINTER_MODE_HOST`

, the function blocks the CPU till the GPU has copied the result back to the host.
Using `hipsparsePointerMode_t`

equal to `HIPSPARSE_POINTER_MODE_DEVICE`

, the function will return after the asynchronous launch.
Similarly to vector and matrix results, the scalar result is only available when the kernel has completed execution.