Skip to main content
`Ctrl`+`K`

# Sparse conversion functions

This module contains all sparse conversion routines.

The sparse conversion routines describe operations performed on a matrix in sparse format to obtain a matrix in a different sparse format.

## hipsparseXnnz()

hipsparseStatus_t hipsparseSnnz(hipsparseHandle_t handle, hipsparseDirection_t dirA, int m, int n, const hipsparseMatDescr_t descrA, const float *A, int lda, int *nnzPerRowColumn, int *nnzTotalDevHostPtr)

hipsparseStatus_t hipsparseDnnz(hipsparseHandle_t handle, hipsparseDirection_t dirA, int m, int n, const hipsparseMatDescr_t descrA, const double *A, int lda, int *nnzPerRowColumn, int *nnzTotalDevHostPtr)

hipsparseStatus_t hipsparseCnnz(hipsparseHandle_t handle, hipsparseDirection_t dirA, int m, int n, const hipsparseMatDescr_t descrA, const hipComplex *A, int lda, int *nnzPerRowColumn, int *nnzTotalDevHostPtr)

hipsparseStatus_t hipsparseZnnz(hipsparseHandle_t handle, hipsparseDirection_t dirA, int m, int n, const hipsparseMatDescr_t descrA, const hipDoubleComplex *A, int lda, int *nnzPerRowColumn, int *nnzTotalDevHostPtr)

  `hipsparseXnnz` computes the number of nonzero elements per row or column and the total number of nonzero elements in a dense matrix.

  For example, given the dense matrix:

  \[\begin{split} \begin{bmatrix} 1 & 0 & 0 & 2 \\ 3 & 4 & 0 & 0 \\ 5 & 0 & 6 & 7 \end{bmatrix} \end{split}\]

  then using `dirA` == HIPSPARSE_DIRECTION_ROW results in:

  \[\begin{split} \begin{align} \text{nnzPerRowColumn} &= \begin{bmatrix} 2 & 2 & 3 \end{bmatrix} \\ \text{nnzTotalDevHostPtr} &= 7 \end{align} \end{split}\]

  while using `dirA` == HIPSPARSE_DIRECTION_COLUMN results in:

  \[\begin{split} \begin{align} \text{nnzPerRowColumn} &= \begin{bmatrix} 3 & 1 & 1 & 2 \end{bmatrix} \\ \text{nnzTotalDevHostPtr} &= 7 \end{align} \end{split}\]

  The array `nnzPerRowColumn` must be allocated by the user before calling `hipsparseXnnz` and has length equal to `m` if `dirA` == HIPSPARSE_DIRECTION_ROW or `n` if `dirA` == HIPSPARSE_DIRECTION_COLUMN.

  For a complete code example on its usage, see the example found with hipsparseSdense2csr().

  Note

  As indicated, `nnzTotalDevHostPtr` can point either to host or device memory. This is controlled by setting the pointer mode. See hipsparseSetPointerMode().

  Note

  The routine does support asynchronous execution if the pointer mode is set to device.

  Parameters:

    - handle – [in] handle to the rocsparse library context queue.

    - dirA – [in] direction that specified whether to count nonzero elements by HIPSPARSE_DIRECTION_ROW or by HIPSPARSE_DIRECTION_COLUMN.

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - descrA – [in] the descriptor of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - nnzPerRowColumn – [out] array of size `m` or `n` containing the number of nonzero elements per row or column, respectively.

    - nnzTotalDevHostPtr – [out] total number of nonzero elements in device or host memory.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `lda`, `A` or `nnzPerRowColumn` or `nnzTotalDevHostPtr` pointer is invalid.

## hipsparseXdense2csr()

hipsparseStatus_t hipsparseSdense2csr(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const float *A, int ld, const int *nnzPerRow, float *csrVal, int *csrRowPtr, int *csrColInd)

hipsparseStatus_t hipsparseDdense2csr(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const double *A, int ld, const int *nnzPerRow, double *csrVal, int *csrRowPtr, int *csrColInd)

hipsparseStatus_t hipsparseCdense2csr(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const hipComplex *A, int ld, const int *nnzPerRow, hipComplex *csrVal, int *csrRowPtr, int *csrColInd)

hipsparseStatus_t hipsparseZdense2csr(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const hipDoubleComplex *A, int ld, const int *nnzPerRow, hipDoubleComplex *csrVal, int *csrRowPtr, int *csrColInd)

  `hipsparseXdense2csr` converts the matrix A in dense format into a sparse matrix in CSR format.

  Given a dense, column ordered, matrix `A` with leading dimension `ld` where `ld>=m`, `hipsparseXdense2csr` converts the matrix to a sparse CSR format matrix. All the parameters are assumed to have been pre-allocated by the user and the arrays are filled in based on number of nonzeros per row, which can be pre-computed with hipsparseXnnz(). The desired index base in the output CSR matrix is set in the hipsparseMatDescr_t. See hipsparseSetMatIndexBase().

  As an example, if using index base zero (i.e. the default) and the dense matrix:

  \[\begin{split} \begin{bmatrix} 1 & 0 & 0 & 2 \\ 3 & 4 & 0 & 0 \\ 5 & 0 & 6 & 7 \end{bmatrix} \end{split}\]

  The conversion results in the CSR arrays:

  \[\begin{split} \begin{align} \text{csrRowPtr} &= \begin{bmatrix} 0 & 2 & 4 & 7 \end{bmatrix} \\ \text{csrColInd} &= \begin{bmatrix} 0 & 3 & 0 & 1 & 0 & 2 & 3 \end{bmatrix} \\ \text{csrVal} &= \begin{bmatrix} 1 & 2 & 3 & 4 & 5 & 6 & 7 \end{bmatrix} \\ \end{align} \end{split}\]

  Example

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

        // Matrix descriptor
        hipsparseMatDescr_t descr;
        hipsparseCreateMatDescr(&descr);

        // Dense matrix in column order
        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        float hdense_A[15] = {1.0f, 0.0f, 6.0f, 2.0f, 4.0f, 0.0f, 0.0f, 5.0f, 0.0f, 3.0f, 0.0f, 7.0f, 0.0f, 0.0f, 8.0f};

        int m         = 3;
        int n         = 5;
        hipsparseDirection_t dir = HIPSPARSE_DIRECTION_ROW;

        float* ddense_A = nullptr;
        hipMalloc((void**)&ddense_A, sizeof(float) * m * n);
        hipMemcpy(ddense_A, hdense_A, sizeof(float) * m * n, hipMemcpyHostToDevice);

        // Allocate memory for the nnz_per_row_columns array
        int* dnnz_per_row;
        hipMalloc((void**)&dnnz_per_row, sizeof(int) * m);

        int nnz_A;
        hipsparseSnnz(handle, dir, m, n, descr, ddense_A, m, dnnz_per_row, &nnz_A);

        // Allocate sparse CSR matrix
        int* dcsrRowPtr = nullptr;
        int* dcsrColInd = nullptr;
        float* dcsrVal = nullptr;
        hipMalloc((void**)&dcsrRowPtr, sizeof(int) * (m + 1));
        hipMalloc((void**)&dcsrColInd, sizeof(int) * nnz_A);
        hipMalloc((void**)&dcsrVal, sizeof(float) * nnz_A);

        hipsparseSdense2csr(handle, m, n, descr, ddense_A, m, dnnz_per_row, dcsrVal, dcsrRowPtr, dcsrColInd);

        hipFree(dcsrRowPtr);
        hipFree(dcsrColInd);
        hipFree(dcsrVal);
        hipFree(dnnz_per_row);
        hipFree(ddense_A);

        hipsparseDestroyMatDescr(descr);
        hipsparseDestroy(handle);

  Note

  It is executed asynchronously with respect to the host and may return control to the application on the host before the entire result is ready.

  Parameters:

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

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - A – [in] array of dimensions (`ld`, `n`)

    - ld – [in] leading dimension of dense array `A`.

    - nnzPerRow – [in] array of size `n` containing the number of non-zero elements per row.

    - csrVal – [out] array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) nonzero elements of matrix `A`.

    - csrRowPtr – [out] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - csrColInd – [out] integer array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) column indices of the non-zero elements of matrix `A`.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `ld`, `A`, `nnzPerRow`, `csrVal` `csrRowPtr` or `csrColInd` pointer is invalid.

## hipsparseXpruneDense2csr_bufferSize()

hipsparseStatus_t hipsparseSpruneDense2csr_bufferSize(hipsparseHandle_t handle, int m, int n, const float *A, int lda, const float *threshold, const hipsparseMatDescr_t descr, const float *csrVal, const int *csrRowPtr, const int *csrColInd, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseDpruneDense2csr_bufferSize(hipsparseHandle_t handle, int m, int n, const double *A, int lda, const double *threshold, const hipsparseMatDescr_t descr, const double *csrVal, const int *csrRowPtr, const int *csrColInd, size_t *pBufferSizeInBytes)

  `hipsparseXpruneDense2csr_bufferSize` computes the the size of the user allocated temporary storage buffer used when converting a dense matrix to a pruned CSR matrix.

  Specifically given an input dense column ordered matrix A, with leading dimension `lda` where `lda>=m`, the resulting pruned sparse CSR matrix C is computed using:

  \[ |C(i,j)| = A(i, j) \text{ if |A(i, j)| > threshold} \]

  The first step in this conversion is to determine the required user allocated buffer size using `hipsparseXpruneDense2csr_bufferSize()` that will be passed to the subsequent steps of the conversion. Once the buffer size has been determined the user must allocate it. This user allocated buffer is then passed to hipsparseXpruneDense2csrNnz() and hipsparseXpruneDense2csr() to complete the conversion. The user is responsible to then free the buffer once the conversion has been completed.

  See hipsparseSpruneDense2csr() for a full code example.

  Parameters:

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

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - threshold – [in] pointer to the pruning non-negative threshold which can exist in either host or device memory.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - csrVal – [in] array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) nonzero elements of matrix `A`.

    - csrRowPtr – [in] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - csrColInd – [in] integer array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) column indices of the non-zero elements of matrix `A`.

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseSpruneDense2csrNnz(), hipsparseDpruneDense2csrNnz(), hipsparseSpruneDense2csr() and hipsparseDpruneDense2csr().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle` or `pBufferSizeInBytes` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXpruneDense2csr_bufferSizeExt()

hipsparseStatus_t hipsparseSpruneDense2csr_bufferSizeExt(hipsparseHandle_t handle, int m, int n, const float *A, int lda, const float *threshold, const hipsparseMatDescr_t descr, const float *csrVal, const int *csrRowPtr, const int *csrColInd, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseDpruneDense2csr_bufferSizeExt(hipsparseHandle_t handle, int m, int n, const double *A, int lda, const double *threshold, const hipsparseMatDescr_t descr, const double *csrVal, const int *csrRowPtr, const int *csrColInd, size_t *pBufferSizeInBytes)

  `hipsparseXpruneDense2csr_bufferSize` computes the the size of the user allocated temporary storage buffer used when converting a dense matrix to a pruned CSR matrix.

  Specifically given an input dense column ordered matrix A, with leading dimension `lda` where `lda>=m`, the resulting pruned sparse CSR matrix C is computed using:

  \[ |C(i,j)| = A(i, j) \text{ if |A(i, j)| > threshold} \]

  The first step in this conversion is to determine the required user allocated buffer size using `hipsparseXpruneDense2csr_bufferSize()` that will be passed to the subsequent steps of the conversion. Once the buffer size has been determined the user must allocate it. This user allocated buffer is then passed to hipsparseXpruneDense2csrNnz() and hipsparseXpruneDense2csr() to complete the conversion. The user is responsible to then free the buffer once the conversion has been completed.

  See hipsparseSpruneDense2csr() for a full code example.

  Parameters:

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

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - threshold – [in] pointer to the pruning non-negative threshold which can exist in either host or device memory.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - csrVal – [in] array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) nonzero elements of matrix `A`.

    - csrRowPtr – [in] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - csrColInd – [in] integer array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) column indices of the non-zero elements of matrix `A`.

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseSpruneDense2csrNnz(), hipsparseDpruneDense2csrNnz(), hipsparseSpruneDense2csr() and hipsparseDpruneDense2csr().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle` or `pBufferSizeInBytes` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXpruneDense2csrNnz()

hipsparseStatus_t hipsparseSpruneDense2csrNnz(hipsparseHandle_t handle, int m, int n, const float *A, int lda, const float *threshold, const hipsparseMatDescr_t descr, int *csrRowPtr, int *nnzTotalDevHostPtr, void *buffer)

hipsparseStatus_t hipsparseDpruneDense2csrNnz(hipsparseHandle_t handle, int m, int n, const double *A, int lda, const double *threshold, const hipsparseMatDescr_t descr, int *csrRowPtr, int *nnzTotalDevHostPtr, void *buffer)

  `hipsparseXpruneDense2csrNnz` function computes the number of nonzero elements per row and the total number of nonzero elements in a dense matrix once the elements less than the (non-negative) threshold are pruned from the matrix.

  Specifically given an input dense column ordered matrix A, with leading dimension `lda` where `lda>=m`, the resulting pruned sparse CSR matrix C is computed using:

  \[ |C(i,j)| = A(i, j) \text{ if |A(i, j)| > threshold} \]

  First the user must determine the size of the required temporary buffer using the routine hipsparseXpruneDense2csr_bufferSize() and then allocate it. Next the user allocates `csrRowPtr` with size `m+1`. Then the passes both the temporary storage buffer as well as `csrRowPtr` to `hipsparseXpruneDense2csrNnz` in order to determine the total number of non-zeros that will exist in the sparse CSR matrix C (after pruning has been performed on A) as well as fill the output CSR row pointer array `csrRowPtr`.

  For example, given the dense matrix:

  \[\begin{split} \begin{bmatrix} 6 & 2 & 3 & 7 \\ 5 & 6 & 7 & 8 \\ 5 & 4 & 8 & 1 \end{bmatrix} \end{split}\]

  and the `threshold` value 5, the resulting matrix after pruning is:

  \[\begin{split} \begin{bmatrix} 6 & 0 & 0 & 7 \\ 0 & 6 & 7 & 8 \\ 0 & 0 & 8 & 0 \end{bmatrix} \end{split}\]

  and corresponding row pointer array and non-zero count:

  \[\begin{split} \begin{align} \text{csrRowPtr} &= \begin{bmatrix} 0 & 2 & 5 & 6 \end{bmatrix} \\ \text{nnzTotalDevHostPtr} &= 6 \end{align} \end{split}\]

  The above example assumes a zero index base for the output CSR matrix. We can set the desired index base in the output CSR matrix by setting it in the hipsparseMatDescr_t. See hipsparseSetMatIndexBase().

  For a full code example on how to use this routine, see hipsparseSpruneDense2csr().

  Note

  The routine does support asynchronous execution if the pointer mode is set to device.

  Parameters:

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

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - threshold – [in] pointer to the pruning non-negative threshold which can exist in either host or device memory.

    - descr – [in] the descriptor of the dense matrix `A`.

    - csrRowPtr – [out] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - nnzTotalDevHostPtr – [out] total number of nonzero elements in device or host memory.

    - buffer – [out] buffer allocated by the user whose size is determined by calling hipsparseXpruneDense2csr_bufferSize() or hipsparseXpruneDense2csr_bufferSizeExt().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `lda`, `A`, `threshold`, `descr`, `csrRowPtr` `nnzTotalDevHostPtr` or `buffer` pointer is invalid.

## hipsparseXpruneDense2csr()

hipsparseStatus_t hipsparseSpruneDense2csr(hipsparseHandle_t handle, int m, int n, const float *A, int lda, const float *threshold, const hipsparseMatDescr_t descr, float *csrVal, const int *csrRowPtr, int *csrColInd, void *buffer)

hipsparseStatus_t hipsparseDpruneDense2csr(hipsparseHandle_t handle, int m, int n, const double *A, int lda, const double *threshold, const hipsparseMatDescr_t descr, double *csrVal, const int *csrRowPtr, int *csrColInd, void *buffer)

  `hipsparseXpruneDense2csr` converts the matrix A in dense format into a sparse matrix in CSR format while pruning values that are less than the (non-negative) threshold. All the parameters are assumed to have been pre-allocated by the user.

  Specifically given an input dense column ordered matrix A, with leading dimension `lda` where `lda>=m`, the resulting pruned sparse CSR matrix C is computed using:

  \[ |C(i,j)| = A(i, j) \text{ if |A(i, j)| > threshold} \]

  The user first calls hipsparseXpruneDense2csr_bufferSize() to determine the size of the required user allocate temporary storage buffer. The user then allocates this buffer. Next, the user allocates `csrRowPtr` to have `m+1` elements and then calls hipsparseXpruneDense2csrNnz() which fills in the `csrRowPtr` array and stores the number of elements that are larger than the pruning `threshold` in `nnzTotalDevHostPtr`. The user then allocates `csrColInd` and `csrVal` to have size `nnzTotalDevHostPtr` and completes the conversion by calling `hipsparseXpruneDense2csr()`.

  For example, performing these steps with the dense input matrix A:

  \[\begin{split} \begin{bmatrix} 6 & 2 & 3 & 7 \\ 5 & 6 & 7 & 8 \\ 5 & 4 & 8 & 1 \end{bmatrix} \end{split}\]

  and the `threshold` value 5, results in the pruned matrix C:

  \[\begin{split} \begin{bmatrix} 6 & 0 & 0 & 7 \\ 0 & 6 & 7 & 8 \\ 0 & 0 & 8 & 0 \end{bmatrix} \end{split}\]

  and corresponding CSR row, column, and values arrays:

  \[\begin{split} \begin{align} \text{csrRowPtr} &= \begin{bmatrix} 0 & 2 & 5 & 6 \end{bmatrix} \\ \text{csrColInd} &= \begin{bmatrix} 0 & 3 & 1 & 2 & 3 & 2 \end{bmatrix} \\ \text{csrVal} &= \begin{bmatrix} 6 & 7 & 6 & 7 & 8 & 8 \end{bmatrix} \\ \end{align} \end{split}\]

  Example

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

        // Matrix descriptor
        hipsparseMatDescr_t descr;
        hipsparseCreateMatDescr(&descr);

        // Dense matrix in column order
        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        float hdense_A[15] = {1.0f, 0.0f, 6.0f, 2.0f, 4.0f, 0.0f, 0.0f, 5.0f, 0.0f, 3.0f, 0.0f, 7.0f, 0.0f, 0.0f, 8.0f};

        int m         = 3;
        int n         = 5;
        int lda       = m;
        float threshold = 4.0f;

        float* ddense_A = nullptr;
        hipMalloc((void**)&ddense_A, sizeof(float) * lda * n);
        hipMemcpy(ddense_A, hdense_A, sizeof(float) * lda * n, hipMemcpyHostToDevice);

        // Allocate sparse CSR matrix
        int* dcsrRowPtr = nullptr;
        hipMalloc((void**)&dcsrRowPtr, sizeof(int) * (m + 1));

        size_t bufferSize;
        hipsparseSpruneDense2csr_bufferSize(handle, m, n, ddense_A, lda, &threshold, descr, nullptr, dcsrRowPtr, nullptr, &bufferSize);

        void* dbuffer = nullptr;
        hipMalloc((void**)&dbuffer, bufferSize);

        int nnz_A;
        hipsparseSpruneDense2csrNnz(handle, m, n, ddense_A, lda, &threshold, descr, dcsrRowPtr, &nnz_A, dbuffer);

        int* dcsrColInd = nullptr;
        float* dcsrVal = nullptr;
        hipMalloc((void**)&dcsrColInd, sizeof(int) * nnz_A);
        hipMalloc((void**)&dcsrVal, sizeof(float) * nnz_A);

        hipsparseSpruneDense2csr(handle, m, n, ddense_A, lda, &threshold, descr, dcsrVal, dcsrRowPtr, dcsrColInd, dbuffer);

        hipFree(dcsrRowPtr);
        hipFree(dcsrColInd);
        hipFree(dcsrVal);
        hipFree(ddense_A);
        hipFree(dbuffer);

        hipsparseDestroyMatDescr(descr);
        hipsparseDestroy(handle);

  Note

  The routine `hipsparseXpruneDense2csr()` is executed asynchronously with respect to the host and may return control to the application on the host before the entire result is ready.

  Parameters:

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

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - threshold – [in] pointer to the non-negative pruning threshold which can exist in either host or device memory.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - csrVal – [out] array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) nonzero elements of matrix `A`.

    - csrRowPtr – [in] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - csrColInd – [out] integer array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) column indices of the non-zero elements of matrix `A`.

    - buffer – [in] temporary storage buffer allocated by the user, size is returned by hipsparseXpruneDense2csr_bufferSize() or hipsparseXpruneDense2csr_bufferSizeExt().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `lda`, `A`, `descr`, `threshold`, `csrVal` `csrRowPtr`, `csrColInd`, `buffer` pointer is invalid.

## hipsparseXpruneDense2csrByPercentage_bufferSize()

hipsparseStatus_t hipsparseSpruneDense2csrByPercentage_bufferSize(hipsparseHandle_t handle, int m, int n, const float *A, int lda, float percentage, const hipsparseMatDescr_t descr, const float *csrVal, const int *csrRowPtr, const int *csrColInd, pruneInfo_t info, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseDpruneDense2csrByPercentage_bufferSize(hipsparseHandle_t handle, int m, int n, const double *A, int lda, double percentage, const hipsparseMatDescr_t descr, const double *csrVal, const int *csrRowPtr, const int *csrColInd, pruneInfo_t info, size_t *pBufferSizeInBytes)

  `hipsparseXpruneDense2csrByPercentage_bufferSize` computes the size of the user allocated temporary storage buffer used when converting a dense matrix to a pruned CSR matrix where the pruning is done based on a percantage.

  When converting and pruning a dense matrix A to a CSR matrix by percentage the following steps are performed. First the user calls `hipsparseXpruneDense2csrByPercentage_bufferSize` which determines the size of the temporary storage buffer. Once determined, this buffer must be allocated by the user. Next the user allocates the `csrRowPtr` array to have `m+1` elements and calls hipsparseXpruneDense2csrNnzByPercentage(). Finally the user finishes the conversion by allocating the `csrColInd` and `csrVal` arrays (whose size is determined by the value at `nnzTotalDevHostPtr`) and calling hipsparseXpruneDense2csrByPercentage().

  The pruning by percentage works by first sorting the absolute values of the dense matrix `A`. We then determine a position in this sorted array by

  \[\begin{split} pos = ceil(m \cdot n \cdot (percentage/100)) - 1 \\ pos = \min(pos, m \cdot n-1) \\ pos = \max(pos, 0) \\ threshold = sorted_A[pos] \end{split}\]

  Once we have this threshold we prune values in the dense matrix `A` as in hipsparseXpruneDense2csr().

  Note

  It is executed asynchronously with respect to the host and may return control to the application on the host before the entire result is ready.

  Parameters:

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

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - percentage – [in] `percentage>=0` and `percentage<=100`.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - csrVal – [in] array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) nonzero elements of matrix `A`.

    - csrRowPtr – [in] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - csrColInd – [in] integer array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) column indices of the non-zero elements of matrix `A`.

    - info – [in] prune information structure

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseSpruneDense2csrNnzByPercentage(), hipsparseDpruneDense2csrNnzByPercentage().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – the `handle` or `pBufferSizeInBytes` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXpruneDense2csrByPercentage_bufferSizeExt()

hipsparseStatus_t hipsparseSpruneDense2csrByPercentage_bufferSizeExt(hipsparseHandle_t handle, int m, int n, const float *A, int lda, float percentage, const hipsparseMatDescr_t descr, const float *csrVal, const int *csrRowPtr, const int *csrColInd, pruneInfo_t info, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseDpruneDense2csrByPercentage_bufferSizeExt(hipsparseHandle_t handle, int m, int n, const double *A, int lda, double percentage, const hipsparseMatDescr_t descr, const double *csrVal, const int *csrRowPtr, const int *csrColInd, pruneInfo_t info, size_t *pBufferSizeInBytes)

  This function computes the size of the user allocated temporary storage buffer used when converting and pruning by percentage a dense matrix to a CSR matrix.

  When converting and pruning a dense matrix A to a CSR matrix by percentage the following steps are performed. First the user calls `hipsparseXpruneDense2csrByPercentage_bufferSizeExt` which determines the size of the temporary storage buffer. Once determined, this buffer must be allocated by the user. Next the user allocates the `csrRowPtr` array to have `m+1` elements and calls hipsparseXpruneDense2csrNnzByPercentage(). Finally the user finishes the conversion by allocating the `csrColInd` and `csrVal` arrays (whos size is determined by the value at `nnzTotalDevHostPtr`) and calling hipsparseXpruneDense2csrByPercentage().

  The pruning by percentage works by first sorting the absolute values of the dense matrix `A`. We then determine a position in this sorted array by

  \[\begin{split} pos = ceil(m \cdot n \cdot (percentage/100)) - 1 \\ pos = \min(pos, m \cdot n-1) \\ pos = \max(pos, 0) \\ threshold = sorted_A[pos] \end{split}\]

  Once we have this threshold we prune values in the dense matrix `A` as in hipsparseXpruneDense2csr().

  Note

  It is executed asynchronously with respect to the host and may return control to the application on the host before the entire result is ready.

  Parameters:

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

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - percentage – [in] `percentage>=0` and `percentage<=100`.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - csrVal – [in] array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) nonzero elements of matrix `A`.

    - csrRowPtr – [in] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - csrColInd – [in] integer array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) column indices of the non-zero elements of matrix `A`.

    - info – [in] prune information structure

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseSpruneDense2csrNnzByPercentage(), hipsparseDpruneDense2csrNnzByPercentage().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – the `handle` or `pBufferSizeInBytes` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXpruneDense2csrNnzByPercentage()

hipsparseStatus_t hipsparseSpruneDense2csrNnzByPercentage(hipsparseHandle_t handle, int m, int n, const float *A, int lda, float percentage, const hipsparseMatDescr_t descr, int *csrRowPtr, int *nnzTotalDevHostPtr, pruneInfo_t info, void *buffer)

hipsparseStatus_t hipsparseDpruneDense2csrNnzByPercentage(hipsparseHandle_t handle, int m, int n, const double *A, int lda, double percentage, const hipsparseMatDescr_t descr, int *csrRowPtr, int *nnzTotalDevHostPtr, pruneInfo_t info, void *buffer)

  This function computes the number of nonzero elements per row and the total number of nonzero elements in a dense matrix when converting and pruning by percentage a dense matrix to a CSR matrix.

  When converting and pruning a dense matrix A to a CSR matrix by percentage the following steps are performed. First the user calls hipsparseXpruneDense2csrByPercentage_bufferSize() which determines the size of the temporary storage buffer. Once determined, this buffer must be allocated by the user. Next the user allocates the `csrRowPtr` array to have `m+1` elements and calls `hipsparseXpruneDense2csrNnzByPercentage`. Finally the user finishes the conversion by allocating the `csrColInd` and `csrVal` arrays (whos size is determined by the value at `nnzTotalDevHostPtr`) and calling hipsparseXpruneDense2csrByPercentage().

  The pruning by percentage works by first sorting the absolute values of the dense matrix `A`. We then determine a position in this sorted array by

  \[\begin{split} pos = ceil(m \cdot n \cdot (percentage/100)) - 1 \\ pos = \min(pos, m \cdot n-1) \\ pos = \max(pos, 0) \\ threshold = sorted_A[pos] \end{split}\]

  Once we have this threshold we prune values in the dense matrix `A` as in hipsparseXpruneDense2csr().

  Note

  The routine does support asynchronous execution if the pointer mode is set to device.

  Parameters:

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

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - percentage – [in] `percentage>=0` and `percentage<=100`.

    - descr – [in] the descriptor of the dense matrix `A`.

    - csrRowPtr – [out] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - nnzTotalDevHostPtr – [out] total number of nonzero elements in device or host memory.

    - info – [in] prune information structure

    - buffer – [out] buffer allocated by the user whose size is determined by calling hipsparseXpruneDense2csrByPercentage_bufferSize() or hipsparseXpruneDense2csrByPercentage_bufferSizeExt().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `lda`, `percentage`, `A`, `descr`, `info`, `csrRowPtr` `nnzTotalDevHostPtr` or `buffer` pointer is invalid.

## hipsparseXpruneDense2csrByPercentage()

hipsparseStatus_t hipsparseSpruneDense2csrByPercentage(hipsparseHandle_t handle, int m, int n, const float *A, int lda, float percentage, const hipsparseMatDescr_t descr, float *csrVal, const int *csrRowPtr, int *csrColInd, pruneInfo_t info, void *buffer)

hipsparseStatus_t hipsparseDpruneDense2csrByPercentage(hipsparseHandle_t handle, int m, int n, const double *A, int lda, double percentage, const hipsparseMatDescr_t descr, double *csrVal, const int *csrRowPtr, int *csrColInd, pruneInfo_t info, void *buffer)

  This function computes the number of nonzero elements per row and the total number of nonzero elements in a dense matrix when converting and pruning by percentage a dense matrix to a CSR matrix.

  When converting and pruning a dense matrix A to a CSR matrix by percentage the following steps are performed. First the user calls hipsparseXpruneDense2csrByPercentage_bufferSize() which determines the size of the temporary storage buffer. Once determined, this buffer must be allocated by the user. Next the user allocates the `csrRowPtr` array to have `m+1` elements and calls hipsparseXpruneDense2csrNnzByPercentage(). Finally the user finishes the conversion by allocating the `csrColInd` and `csrVal` arrays (whos size is determined by the value at `nnzTotalDevHostPtr`) and calling `hipsparseXpruneDense2csrByPercentage`.

  The pruning by percentage works by first sorting the absolute values of the dense matrix `A`. We then determine a position in this sorted array by

  \[\begin{split} pos = ceil(m \ cdot n \cdot (percentage/100)) - 1 \\ pos = \min(pos, m \cdot n-1) \\ pos = \max(pos, 0) \\ threshold = sorted_A[pos] \end{split}\]

  Once we have this threshold we prune values in the dense matrix `A` as in hipsparseXpruneDense2csr().

  Example

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

        // Matrix descriptor
        hipsparseMatDescr_t descr;
        hipsparseCreateMatDescr(&descr);

        // Dense matrix in column order
        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        float hdense_A[15] = {1.0f, 0.0f, 6.0f, 2.0f, 4.0f, 0.0f, 0.0f, 5.0f, 0.0f, 3.0f, 0.0f, 7.0f, 0.0f, 0.0f, 8.0f};

        int m         = 3;
        int n         = 5;
        int lda       = m;
        float percentage = 70.0f;

        float* ddense_A = nullptr;
        hipMalloc((void**)&ddense_A, sizeof(float) * lda * n);
        hipMemcpy(ddense_A, hdense_A, sizeof(float) * lda * n, hipMemcpyHostToDevice);

        // Allocate sparse CSR matrix
        int* dcsrRowPtr = nullptr;
        hipMalloc((void**)&dcsrRowPtr, sizeof(int) * (m + 1));

        pruneInfo_t info;
        hipsparseCreatePruneInfo(&info);

        size_t bufferSize;
        hipsparseSpruneDense2csrByPercentage_bufferSize(handle, m, n, ddense_A, lda, percentage, descr, nullptr, dcsrRowPtr, nullptr, info, &bufferSize);

        void* dbuffer = nullptr;
        hipMalloc((void**)&dbuffer, bufferSize);

        int nnz_A;
        hipsparseSpruneDense2csrNnzByPercentage(handle, m, n, ddense_A, lda, percentage, descr, dcsrRowPtr, &nnz_A, info, dbuffer);

        int* dcsrColInd = nullptr;
        float* dcsrVal = nullptr;
        hipMalloc((void**)&dcsrColInd, sizeof(int) * nnz_A);
        hipMalloc((void**)&dcsrVal, sizeof(float) * nnz_A);

        hipsparseSpruneDense2csrByPercentage(handle, m, n, ddense_A, lda, percentage, descr, dcsrVal, dcsrRowPtr, dcsrColInd, info, dbuffer);

        hipFree(dcsrRowPtr);
        hipFree(dcsrColInd);
        hipFree(dcsrVal);
        hipFree(ddense_A);
        hipFree(dbuffer);

        hipsparseDestroyPruneInfo(info);
        hipsparseDestroyMatDescr(descr);
        hipsparseDestroy(handle);

  Note

  The routine does support asynchronous execution if the pointer mode is set to device.

  Parameters:

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

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - A – [in] array of dimensions (`lda`, `n`)

    - lda – [in] leading dimension of dense array `A`.

    - percentage – [in] `percentage>=0` and `percentage<=100`.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - csrVal – [out] array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) nonzero elements of matrix `A`.

    - csrRowPtr – [in] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - csrColInd – [out] integer array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) column indices of the non-zero elements of matrix `A`.

    - info – [in] prune information structure

    - buffer – [in] temporary storage buffer allocated by the user, size is returned by hipsparseXpruneDense2csrByPercentage_bufferSize() or hipsparseXpruneDense2csrByPercentage_bufferSizeExt().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `lda`, `percentage`, `A`, `descr`, `info`, `csrVal` `csrRowPtr`, `csrColInd` or `buffer` pointer is invalid.

## hipsparseXdense2csc()

hipsparseStatus_t hipsparseSdense2csc(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const float *A, int ld, const int *nnzPerColumn, float *cscVal, int *cscRowInd, int *cscColPtr)

hipsparseStatus_t hipsparseDdense2csc(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const double *A, int ld, const int *nnzPerColumn, double *cscVal, int *cscRowInd, int *cscColPtr)

hipsparseStatus_t hipsparseCdense2csc(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const hipComplex *A, int ld, const int *nnzPerColumn, hipComplex *cscVal, int *cscRowInd, int *cscColPtr)

hipsparseStatus_t hipsparseZdense2csc(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const hipDoubleComplex *A, int ld, const int *nnzPerColumn, hipDoubleComplex *cscVal, int *cscRowInd, int *cscColPtr)

  `hipsparseXdense2csc` converts the matrix A in dense format into a sparse matrix in CSC format.

  Given a dense, column ordered, matrix `A` with leading dimension `ld` where `ld>=m`, `hipsparseXdense2csc` converts the matrix to a sparse CSC format matrix. All the parameters are assumed to have been pre-allocated by the user and the arrays are filled in based on number of nonzeros per row, which can be pre-computed with hipsparseXnnz(). We can set the desired index base in the output CSC matrix by setting it in the hipsparseMatDescr_t. See hipsparseSetMatIndexBase().

  As an example, if using index base zero (i.e. the default) and the dense matrix:

  \[\begin{split} \begin{bmatrix} 1 & 0 & 0 & 2 \\ 3 & 4 & 0 & 0 \\ 5 & 0 & 6 & 7 \end{bmatrix} \end{split}\]

  where the `A` values have column ordering with leading dimension `ld=m:`

  \[\begin{split} \text{A} &= \begin{bmatrix} 1 & 3 & 5 & 0 & 4 & 0 & 0 & 0 & 6 & 2 & 0 & 7 \end{bmatrix} \\ \end{split}\]

  the conversion results in the CSC arrays:

  \[\begin{split} \begin{align} \text{cscRowInd} &= \begin{bmatrix} 0 & 1 & 2 & 1 & 2 & 0 & 2 \end{bmatrix} \\ \text{cscColPtr} &= \begin{bmatrix} 0 & 3 & 4 & 5 & 7 \end{bmatrix} \\ \text{cscVal} &= \begin{bmatrix} 1 & 3 & 5 & 4 & 6 & 2 & 7 \end{bmatrix} \\ \end{align} \end{split}\]

  This function works very similar to hipsparseXdense2csr(). & See hipsparseSdense2csr() for a code example.

  Note

  It is executed asynchronously with respect to the host and may return control to the application on the host before the entire result is ready.

  Parameters:

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

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - A – [in] array of dimensions (`ld`, `n`)

    - ld – [in] leading dimension of dense array `A`.

    - nnzPerColumn – [in] array of size `n` containing the number of non-zero elements per column.

    - cscVal – [out] array of nnz ( = `cscColPtr`[n] - `cscColPtr`[0] ) nonzero elements of matrix `A`.

    - cscRowInd – [out] integer array of nnz ( = `cscColPtr`[n] - `cscColPtr`[0] ) column indices of the non-zero elements of matrix `A`.

    - cscColPtr – [out] integer array of `n+1` elements that contains the start of every column and the end of the last column plus one.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `ld`, `A`, `nnzPerColumn` or `cscVal` `cscColPtr` or `cscRowInd` pointer is invalid.

## hipsparseXcsr2dense()

hipsparseStatus_t hipsparseScsr2dense(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const float *csrVal, const int *csrRowPtr, const int *csrColInd, float *A, int ld)

hipsparseStatus_t hipsparseDcsr2dense(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const double *csrVal, const int *csrRowPtr, const int *csrColInd, double *A, int ld)

hipsparseStatus_t hipsparseCcsr2dense(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const hipComplex *csrVal, const int *csrRowPtr, const int *csrColInd, hipComplex *A, int ld)

hipsparseStatus_t hipsparseZcsr2dense(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const hipDoubleComplex *csrVal, const int *csrRowPtr, const int *csrColInd, hipDoubleComplex *A, int ld)

  `hipsparseXcsr2dense` function converts the sparse matrix in CSR format into a dense matrix.

  Given the input CSR matrix of size `mxn`, the routine writes the matrix to the dense array `A` such that `A` has leading dimension `ld` and is column ordered. This means that `A` has size `ldxn` where `ld>=m`. All the parameters are assumed to have been pre-allocated by the user. If the input CSR matrix has index base of one, it must be set in the hipsparseMatDescr_t. See hipsparseSetMatIndexBase() prior to calling `hipsparseXcsr2dense`.

  For example, consider the sparse CSR matrix:

  \[\begin{split} \begin{align} \text{csrRowPtr} &= \begin{bmatrix} 0 & 2 & 4 & 7 \end{bmatrix} \\ \text{csrColInd} &= \begin{bmatrix} 0 & 3 & 0 & 1 & 0 & 2 & 3 \end{bmatrix} \\ \text{csrVal} &= \begin{bmatrix} 1 & 2 & 3 & 4 & 5 & 6 & 7 \end{bmatrix} \\ \end{align} \end{split}\]

  `hipsparseXcsr2dense` is used to convert to the dense matrix:

  \[\begin{split} \begin{bmatrix} 1 & 0 & 0 & 2 \\ 3 & 4 & 0 & 0 \\ 5 & 0 & 6 & 7 \end{bmatrix} \end{split}\]

  where the values in the `A` array are column ordered:

  \[\begin{split} \text{A} &= \begin{bmatrix} 1 & 3 & 5 & 0 & 4 & 0 & 0 & 0 & 6 & 2 & 0 & 7 \end{bmatrix} \\ \end{split}\]

  Example

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

        // Matrix descriptor
        hipsparseMatDescr_t descr;
        hipsparseCreateMatDescr(&descr);

        // Sparse matrix in CSR format
        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        int hcsrRowPtr[4] = {0, 3, 5, 8};
        int hcsrColInd[8] = {0, 1, 3, 1, 2, 0, 3, 4};
        float hcsrVal[8]   = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f};

        int m         = 3;
        int n         = 5;
        int ld        = 3;
        int nnz       = 8;

        int* dcsrRowPtr = nullptr;
        int* dcsrColInd = nullptr;
        float* dcsrVal = nullptr;
        hipMalloc((void**)&dcsrRowPtr, sizeof(int) * (m + 1));
        hipMalloc((void**)&dcsrColInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcsrVal, sizeof(float) * nnz);

        hipMemcpy(dcsrRowPtr, hcsrRowPtr, sizeof(int) * (m + 1), hipMemcpyHostToDevice);
        hipMemcpy(dcsrColInd, hcsrColInd, sizeof(int) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dcsrVal, hcsrVal, sizeof(float) * nnz, hipMemcpyHostToDevice);

        float* ddense_A = nullptr;
        hipMalloc((void**)&ddense_A, sizeof(float) * ld * n);

        hipsparseScsr2dense(handle, m, n, descr, dcsrVal, dcsrRowPtr, dcsrColInd, ddense_A, ld);

        hipFree(dcsrRowPtr);
        hipFree(dcsrColInd);
        hipFree(dcsrVal);
        hipFree(ddense_A);

        hipsparseDestroyMatDescr(descr);
        hipsparseDestroy(handle);

  Note

  It is executed asynchronously with respect to the host and may return control to the application on the host before the entire result is ready.

  Parameters:

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

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - csrVal – [in] array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) nonzero elements of matrix `A`.

    - csrRowPtr – [in] integer array of `m+1` elements that contains the start of every row and the end of the last row plus one.

    - csrColInd – [in] integer array of nnz ( = `csrRowPtr`[m] - `csrRowPtr`[0] ) column indices of the non-zero elements of matrix `A`.

    - A – [out] array of dimensions (`ld`, `n`)

    - ld – [out] leading dimension of dense array `A`.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `ld`, `A`, `csrVal`, `csrRowPtr` or `csrColInd` pointer is invalid.

## hipsparseXcsc2dense()

hipsparseStatus_t hipsparseScsc2dense(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const float *cscVal, const int *cscRowInd, const int *cscColPtr, float *A, int ld)

hipsparseStatus_t hipsparseDcsc2dense(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const double *cscVal, const int *cscRowInd, const int *cscColPtr, double *A, int ld)

hipsparseStatus_t hipsparseCcsc2dense(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const hipComplex *cscVal, const int *cscRowInd, const int *cscColPtr, hipComplex *A, int ld)

hipsparseStatus_t hipsparseZcsc2dense(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descr, const hipDoubleComplex *cscVal, const int *cscRowInd, const int *cscColPtr, hipDoubleComplex *A, int ld)

  `hipsparseXcsc2dense` function converts the sparse matrix in CSC format into a dense matrix.

  Given the input CSC matrix of size `mxn`, the routine writes the matrix to the dense array `A` such that `A` has leading dimension `ld` and is column ordered. This means that `A` has size `ldxn` where `ld>=m`. All the parameters are assumed to have been pre-allocated by the user. If the input CSC matrix has index base of one, it must be set in the hipsparseMatDescr_t. See hipsparseSetMatIndexBase() prior to calling `hipsparseXcsc2dense`.

  For example, consider the sparse CSC matrix:

  \[\begin{split} \begin{align} \text{cscRowInd} &= \begin{bmatrix} 0 & 1 & 2 & 1 & 2 & 0 & 2 \end{bmatrix} \\ \text{cscColPtr} &= \begin{bmatrix} 0 & 3 & 4 & 5 & 7 \end{bmatrix} \\ \text{cscVal} &= \begin{bmatrix} 1 & 3 & 5 & 4 & 6 & 2 & 7 \end{bmatrix} \\ \end{align} \end{split}\]

  `hipsparseXcsc2dense` is used to convert to the dense matrix:

  \[\begin{split} \begin{bmatrix} 1 & 0 & 0 & 2 \\ 3 & 4 & 0 & 0 \\ 5 & 0 & 6 & 7 \end{bmatrix} \end{split}\]

  where the values in the `A` array are column ordered:

  \[\begin{split} \text{A} &= \begin{bmatrix} 1 & 3 & 5 & 0 & 4 & 0 & 0 & 0 & 6 & 2 & 0 & 7 \end{bmatrix} \\ \end{split}\]

  Note

  It is executed asynchronously with respect to the host and may return control to the application on the host before the entire result is ready.

  Parameters:

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

    - m – [in] number of rows of the dense matrix `A`.

    - n – [in] number of columns of the dense matrix `A`.

    - descr – [in] the descriptor of the dense matrix `A`, the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - cscVal – [in] array of nnz ( = `cscColPtr`[n] - `cscColPtr`[0] ) nonzero elements of matrix `A`.

    - cscRowInd – [in] integer array of nnz ( = `cscColPtr`[n] - `cscColPtr`[0] ) column indices of the non-zero elements of matrix `A`.

    - cscColPtr – [in] integer array of `n+1` elements that contains the start of every column and the end of the last column plus one.

    - A – [out] array of dimensions (`ld`, `n`)

    - ld – [out] leading dimension of dense array `A`.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `ld`, `A`, `cscVal` `cscColPtr` or `cscRowInd` pointer is invalid.

## hipsparseXcsr2bsrNnz()

hipsparseStatus_t hipsparseXcsr2bsrNnz(hipsparseHandle_t handle, hipsparseDirection_t dirA, int m, int n, const hipsparseMatDescr_t descrA, const int *csrRowPtrA, const int *csrColIndA, int blockDim, const hipsparseMatDescr_t descrC, int *bsrRowPtrC, int *bsrNnzb)

  This function computes the number of nonzero block columns per row and the total number of nonzero blocks in a sparse BSR matrix given a sparse CSR matrix as input.

  Consider the matrix:

  \[\begin{split} \begin{bmatrix} 1 & 0 & 0 & 2 \\ 3 & 4 & 0 & 0 \\ 5 & 0 & 6 & 7 \\ 1 & 2 & 3 & 4 \end{bmatrix} \end{split}\]

  stored as a sparse CSR matrix. This function computes both the BSR row pointer array as well as the total number of non-zero blocks that results when converting the CSR matrix to the BSR format. Assuming a block dimension of 2, the above matrix once converted to BSR format looks like:

  \[\begin{split} \left[ \begin{array}{c | c} \begin{array}{c c} 1 & 0 \\ 3 & 4 \end{array} & \begin{array}{c c} 0 & 2 \\ 0 & 0 \end{array} \\ \hline \begin{array}{c c} 5 & 0 \\ 1 & 2 \end{array} & \begin{array}{c c} 6 & 7 \\ 3 & 4 \end{array} \\ \end{array} \right] \end{split}\]

  and the resulting BSR row pointer array and total non-zero blocks once `hipsparseXcsr2bsrNnz` has been called:

  \[\begin{split} \begin{align} \text{bsrRowPtrC} &= \begin{bmatrix} 0 & 2 & 4 \end{bmatrix} \\ \text{bsrNnzb} &= 4 \end{align} \end{split}\]

  In general, when converting a CSR matrix of size `m` x `n` to a BSR matrix, the resulting BSR matrix will have size `mb` x `nb` where `mb` and `nb` equal:

  \[\begin{split} \begin{align} \text{mb} &= \text{(m - 1) / blockDim + 1} \\ \text{nb} &= \text{(n - 1) / blockDim + 1} \end{align} \end{split}\]

  In particular, it may be the case that `blockDim` does not divide evenly into `m` and/or `n`. In these cases, the CSR matrix is expanded in size in order to fit full BSR blocks. For example, using the original CSR matrix and block dimension 3 instead of 2, the function `hipsparseXcsr2bsrNnz` computes the BSR row pointer array and total number of non-zero blocks for the BSR matrix:

  \[\begin{split} \left[ \begin{array}{c | c} \begin{array}{c c c} 1 & 0 & 0 \\ 3 & 4 & 0 \\ 5 & 0 & 6 \end{array} & \begin{array}{c c c} 2 & 0 & 0 \\ 0 & 0 & 0 \\ 7 & 0 & 0 \end{array} \\ \hline \begin{array}{c c c} 1 & 2 & 3 \\ 0 & 0 & 0 \\ 0 & 0 & 0 \end{array} & \begin{array}{c c c} 4 & 0 & 0 \\ 0 & 0 & 0 \\ 0 & 0 & 0 \end{array} \\ \end{array} \right] \end{split}\]

  See hipsparseScsr2bsr() for full code example.

  Note

  The routine does support asynchronous execution if the pointer mode is set to device.

  Parameters:

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

    - dirA – [in] direction that specified whether to count nonzero elements by HIPSPARSE_DIRECTION_ROW or by HIPSPARSE_DIRECTION_COLUMN.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - descrA – [in] descriptor of the sparse CSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrRowPtrA – [in] integer array containing `m+1` elements that point to the start of each row of the CSR matrix

    - csrColIndA – [in] integer array of the column indices for each non-zero element in the CSR matrix

    - blockDim – [in] the block dimension of the BSR matrix. Between \(1\) and \(\min(m, n)\)

    - descrC – [in] descriptor of the sparse BSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - bsrRowPtrC – [out] integer array containing `mb+1` elements that point to the start of each block row of the BSR matrix

    - bsrNnzb – [out] total number of nonzero elements in device or host memory.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `blockDim`, `csrRowPtrA`, `csrColIndA`, `bsrRowPtrC` or `bsrNnzb` pointer is invalid.

## hipsparseXcsr2bsr()

hipsparseStatus_t hipsparseScsr2bsr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int m, int n, const hipsparseMatDescr_t descrA, const float *csrValA, const int *csrRowPtrA, const int *csrColIndA, int blockDim, const hipsparseMatDescr_t descrC, float *bsrValC, int *bsrRowPtrC, int *bsrColIndC)

hipsparseStatus_t hipsparseDcsr2bsr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int m, int n, const hipsparseMatDescr_t descrA, const double *csrValA, const int *csrRowPtrA, const int *csrColIndA, int blockDim, const hipsparseMatDescr_t descrC, double *bsrValC, int *bsrRowPtrC, int *bsrColIndC)

hipsparseStatus_t hipsparseCcsr2bsr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int m, int n, const hipsparseMatDescr_t descrA, const hipComplex *csrValA, const int *csrRowPtrA, const int *csrColIndA, int blockDim, const hipsparseMatDescr_t descrC, hipComplex *bsrValC, int *bsrRowPtrC, int *bsrColIndC)

hipsparseStatus_t hipsparseZcsr2bsr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int m, int n, const hipsparseMatDescr_t descrA, const hipDoubleComplex *csrValA, const int *csrRowPtrA, const int *csrColIndA, int blockDim, const hipsparseMatDescr_t descrC, hipDoubleComplex *bsrValC, int *bsrRowPtrC, int *bsrColIndC)

  Convert a sparse CSR matrix into a sparse BSR matrix.

  `hipsparseXcsr2bsr` completes the conversion of a CSR matrix into a BSR matrix. It is assumed, that `bsrValC`, `bsrColIndC` and `bsrRowPtrC` are allocated. The allocation size for `bsrRowPtr` is computed as `mb+1` where `mb` is the number of block rows in the BSR matrix defined as:

  \[ \begin{align} \text{mb} &= \text{(m - 1) / blockDim + 1} \end{align} \]

  The allocation size for `bsrColIndC`, i.e. `bsrNnzb`, is computed using hipsparseXcsr2bsrNnz() which also fills the `bsrRowPtrC` array. The allocation size for `bsrValC` is then equal to:

  \[ \text{bsrNnzb * blockDim * blockDim} \]

  For example, given the CSR matrix:

  \[\begin{split} \begin{bmatrix} 1 & 0 & 0 & 2 \\ 3 & 4 & 0 & 0 \\ 5 & 0 & 6 & 7 \\ 1 & 2 & 3 & 4 \end{bmatrix} \end{split}\]

  The resulting BSR matrix using block dimension 2 would look like:

  \[\begin{split} \left[ \begin{array}{c | c} \begin{array}{c c} 1 & 0 \\ 3 & 4 \end{array} & \begin{array}{c c} 0 & 2 \\ 0 & 0 \end{array} \\ \hline \begin{array}{c c} 5 & 0 \\ 1 & 2 \end{array} & \begin{array}{c c} 6 & 7 \\ 3 & 4 \end{array} \\ \end{array} \right] \end{split}\]

  The call to hipsparseXcsr2bsrNnz results in the BSR row pointer array:

  \[\begin{split} \begin{align} \text{bsrRowPtrC} &= \begin{bmatrix} 0 & 2 & 4 \end{bmatrix} \\ \end{align} \end{split}\]

  and the call to `hipsparseXcsr2bsr` completes the conversion resulting in the BSR column indices and values arrays:

  \[\begin{split} \begin{align} \text{bsrColIndC} &= \begin{bmatrix} 0 & 1 & 0 & 1 \end{bmatrix} \\ \text{bsrValC} &= \begin{bmatrix} 1 & 0 & 3 & 4 & 0 & 2 & 0 & 0 & 5 & 0 & 1 & 2 & 6 & 7 & 3 & 4 \end{bmatrix} \\ \end{align} \end{split}\]

  The `dirA` parameter determines the order of the BSR block values. The example above uses row order. Using column ordering would result instead in the BSR values array:

  \[\begin{split} \text{bsrValC} &= \begin{bmatrix} 1 & 3 & 0 & 4 & 0 & 0 & 2 & 0 & 5 & 1 & 0 & 2 & 6 & 3 & 7 & 4 \end{bmatrix} \\ \end{split}\]

  Example

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

        // Matrix descriptor
        hipsparseMatDescr_t csr_descr;
        hipsparseCreateMatDescr(&csr_descr);

        hipsparseMatDescr_t bsr_descr;
        hipsparseCreateMatDescr(&bsr_descr);

        // Sparse matrix in CSR format
        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        int hcsrRowPtr[4] = {0, 3, 5, 8};
        int hcsrColInd[8] = {0, 1, 3, 1, 2, 0, 3, 4};
        float hcsrVal[8]   = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f};

        int m         = 3;
        int n         = 5;
        int nnz       = 8;
        int blockDim  = 3;
        hipsparseDirection_t dir = HIPSPARSE_DIRECTION_ROW;

        int mb = (m + blockDim - 1) / blockDim;
        int nb = (n + blockDim - 1) / blockDim;

        int* dcsrRowPtr = nullptr;
        int* dcsrColInd = nullptr;
        float* dcsrVal = nullptr;
        hipMalloc((void**)&dcsrRowPtr, sizeof(int) * (m + 1));
        hipMalloc((void**)&dcsrColInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcsrVal, sizeof(float) * nnz);

        hipMemcpy(dcsrRowPtr, hcsrRowPtr, sizeof(int) * (m + 1), hipMemcpyHostToDevice);
        hipMemcpy(dcsrColInd, hcsrColInd, sizeof(int) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dcsrVal, hcsrVal, sizeof(float) * nnz, hipMemcpyHostToDevice);

        int* dbsrRowPtr = nullptr;
        hipMalloc((void**)&dbsrRowPtr, sizeof(int) * (mb + 1));

        int nnzb;
        hipsparseXcsr2bsrNnz(handle, dir, m, n, csr_descr, dcsrRowPtr, dcsrColInd, blockDim, bsr_descr, dbsrRowPtr, &nnzb);

        int* dbsrColInd = nullptr;
        float* dbsrVal = nullptr;
        hipMalloc((void**)&dbsrColInd, sizeof(int) * nnzb);
        hipMalloc((void**)&dbsrVal, sizeof(float) * blockDim * blockDim * nnzb);

        hipsparseScsr2bsr(handle, dir, m, n, csr_descr, dcsrVal, dcsrRowPtr, dcsrColInd, blockDim, bsr_descr, dbsrVal, dbsrRowPtr, dbsrColInd);

        hipFree(dcsrRowPtr);
        hipFree(dcsrColInd);
        hipFree(dcsrVal);

        hipFree(dbsrRowPtr);
        hipFree(dbsrColInd);
        hipFree(dbsrVal);

        hipsparseDestroyMatDescr(csr_descr);
        hipsparseDestroyMatDescr(bsr_descr);
        hipsparseDestroy(handle);

  Note

  `hipsparseXcsr2bsr` requires extra temporary storage that is allocated internally if `blockDim>16`

  Parameters:

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

    - dirA – [in] the storage format of the blocks, HIPSPARSE_DIRECTION_ROW or HIPSPARSE_DIRECTION_COLUMN

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - descrA – [in] descriptor of the sparse CSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValA – [in] array of `nnz` elements containing the values of the sparse CSR matrix.

    - csrRowPtrA – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csrColIndA – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - blockDim – [in] size of the blocks in the sparse BSR matrix.

    - descrC – [in] descriptor of the sparse BSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - bsrValC – [out] array of `nnzb*blockDim*blockDim` containing the values of the sparse BSR matrix.

    - bsrRowPtrC – [out] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsrColIndC – [out] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `blockDim`, `bsrValC`, `bsrRowPtrC`, `bsrColIndC`, `csrValA`, `csrRowPtrA` or `csrColIndA` pointer is invalid.

## hipsparseXnnz_compress()

hipsparseStatus_t hipsparseSnnz_compress(hipsparseHandle_t handle, int m, const hipsparseMatDescr_t descrA, const float *csrValA, const int *csrRowPtrA, int *nnzPerRow, int *nnzC, float tol)

hipsparseStatus_t hipsparseDnnz_compress(hipsparseHandle_t handle, int m, const hipsparseMatDescr_t descrA, const double *csrValA, const int *csrRowPtrA, int *nnzPerRow, int *nnzC, double tol)

hipsparseStatus_t hipsparseCnnz_compress(hipsparseHandle_t handle, int m, const hipsparseMatDescr_t descrA, const hipComplex *csrValA, const int *csrRowPtrA, int *nnzPerRow, int *nnzC, hipComplex tol)

hipsparseStatus_t hipsparseZnnz_compress(hipsparseHandle_t handle, int m, const hipsparseMatDescr_t descrA, const hipDoubleComplex *csrValA, const int *csrRowPtrA, int *nnzPerRow, int *nnzC, hipDoubleComplex tol)

  This function is used as the first step in converting a CSR matrix to a compressed CSR matrix.

  Given a sparse CSR matrix and a non-negative tolerance, this function computes how many entries would be left in each row of the matrix if elements less than the tolerance were removed. It also computes the total number of remaining elements in the matrix.

  Specifically given an input sparse matrix A in CSR format, the resulting compressed sparse CSR matrix C is computed using:

  \[ C(i,j) = A(i, j) \text{ if |A(i, j)| > tol} \]

  The user first allocates `nnzPerRow` with size `m` elements. Then calling `hipsparseXnnz_compress`, the function fills in the `nnzPerRow` array and sets the total number of nonzeros found in `nnzC`.

  See hipsparseScsr2csr_compress() for full code example.

  Example

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

        // Matrix descriptor
        hipsparseMatDescr_t descr_A;
        hipsparseCreateMatDescr(&descr_A);

        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        float tol = 4.2f;

        int m     = 3;
        int n     = 5;
        int nnz_A = 8;

        int hcsrRowPtr_A[4] = {0, 3, 5, 8};
        float hcsrVal_A[8]   = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f};

        int* dcsrRowPtr_A = nullptr;
        float* dcsrVal_A = nullptr;
        hipMalloc((void**)&dcsrRowPtr_A, sizeof(int) * (m + 1));
        hipMalloc((void**)&dcsrVal_A, sizeof(float) * nnz_A);

        hipMemcpy(dcsrRowPtr_A, hcsrRowPtr_A, sizeof(int) * (m + 1), hipMemcpyHostToDevice);
        hipMemcpy(dcsrVal_A, hcsrVal_A, sizeof(float) * nnz_A, hipMemcpyHostToDevice);

        // Allocate memory for the nnz_per_row array
        int* dnnz_per_row;
        hipMalloc((void**)&dnnz_per_row, sizeof(int) * m);

        // Call snnz_compress() which fills in nnz_per_row array and finds the number
        // of entries that will be in the compressed CSR matrix
        int nnz_C;
        hipsparseSnnz_compress(handle, m, descr_A, dcsrVal_A, dcsrRowPtr_A, dnnz_per_row, &nnz_C, tol);

        hipFree(dcsrRowPtr_A);
        hipFree(dcsrVal_A);
        hipFree(dnnz_per_row);

        hipsparseDestroyMatDescr(descr_A);
        hipsparseDestroy(handle);

  Note

  In the case of complex matrices only the magnitude of the real part of `tol` is used.

  Parameters:

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

    - m – [in] number of rows of the sparse CSR matrix.

    - descrA – [in] the descriptor of the sparse CSR matrix.

    - csrValA – [in] array of `nnzA` elements of the sparse CSR matrix.

    - csrRowPtrA – [in] array of `m+1` elements that point to the start of every row of the uncompressed sparse CSR matrix.

    - nnzPerRow – [out] array of length `m` containing the number of entries that will be kept per row in the final compressed CSR matrix.

    - nnzC – [out] number of elements in the column indices and values arrays of the compressed sparse CSR matrix. Can be either host or device pointer.

    - tol – [in] the non-negative tolerance used for compression. If `tol` is complex then only the magnitude of the real part is used. Entries in the input uncompressed CSR array that are below the tolerance are removed in output compressed CSR matrix.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `tol`, `csrValA`, `csrRowPtrA`, `nnzPerRow` or `nnzC` pointer is invalid.

## hipsparseXcsr2coo()

hipsparseStatus_t hipsparseXcsr2coo(hipsparseHandle_t handle, const int *csrRowPtr, int nnz, int m, int *cooRowInd, hipsparseIndexBase_t idxBase)

  Convert a sparse CSR matrix into a sparse COO matrix.

  `hipsparseXcsr2coo` converts the CSR array containing the row offsets, that point to the start of every row, into a COO array of row indices. All arrays are assumed to be allocated by the user prior to calling `hipsparseXcsr2coo`.

  For example, given the CSR row pointer array (assuming zero index base):

  \[ \begin{align} \text{csrRowPtr} &= \begin{bmatrix} 0 & 1 & 3 & 4 \end{bmatrix} \end{align} \]

  Calling `hipsparseXcsr2coo()` results in the COO row indices array:

  \[ \begin{align} \text{cooRowInd} &= \begin{bmatrix} 0 & 1 & 1 & 2 \end{bmatrix} \end{align} \]

  Note

  It can also be used to convert a CSC array containing the column offsets into a COO array of column indices.

  Note

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

  Parameters:

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

    - csrRowPtr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - m – [in] number of rows of the sparse CSR matrix.

    - cooRowInd – [out] array of `nnz` elements containing the row indices of the sparse COO matrix.

    - idxBase – [in] HIPSPARSE_INDEX_BASE_ZERO or HIPSPARSE_INDEX_BASE_ONE.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `nnz`, `csrRowPtr` or `cooRowInd` pointer is invalid.

    - HIPSPARSE_STATUS_ARCH_MISMATCH – the device is not supported.

## hipsparseXcsr2csc()

hipsparseStatus_t hipsparseScsr2csc(hipsparseHandle_t handle, int m, int n, int nnz, const float *csrSortedVal, const int *csrSortedRowPtr, const int *csrSortedColInd, float *cscSortedVal, int *cscSortedRowInd, int *cscSortedColPtr, hipsparseAction_t copyValues, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseDcsr2csc(hipsparseHandle_t handle, int m, int n, int nnz, const double *csrSortedVal, const int *csrSortedRowPtr, const int *csrSortedColInd, double *cscSortedVal, int *cscSortedRowInd, int *cscSortedColPtr, hipsparseAction_t copyValues, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseCcsr2csc(hipsparseHandle_t handle, int m, int n, int nnz, const hipComplex *csrSortedVal, const int *csrSortedRowPtr, const int *csrSortedColInd, hipComplex *cscSortedVal, int *cscSortedRowInd, int *cscSortedColPtr, hipsparseAction_t copyValues, hipsparseIndexBase_t idxBase)

hipsparseStatus_t hipsparseZcsr2csc(hipsparseHandle_t handle, int m, int n, int nnz, const hipDoubleComplex *csrSortedVal, const int *csrSortedRowPtr, const int *csrSortedColInd, hipDoubleComplex *cscSortedVal, int *cscSortedRowInd, int *cscSortedColPtr, hipsparseAction_t copyValues, hipsparseIndexBase_t idxBase)

  Convert a sparse CSR matrix into a sparse CSC matrix.

  `hipsparseXcsr2csc` converts a CSR matrix into a CSC matrix. `hipsparseXcsr2csc` can also be used to convert a CSC matrix into a CSR matrix. `copyValues` decides whether `cscSortedVal` is being filled during conversion (HIPSPARSE_ACTION_NUMERIC) or not (HIPSPARSE_ACTION_SYMBOLIC).

  For example given the matrix:

  \[\begin{split} \begin{bmatrix} 1 & 0 & 0 & 2 \\ 3 & 4 & 0 & 0 \\ 5 & 0 & 6 & 7 \end{bmatrix} \end{split}\]

  Represented using the sparse CSR format as:

  \[\begin{split} \begin{align} \text{csrSortedRowPtr} &= \begin{bmatrix} 0 & 2 & 4 & 7 \end{bmatrix} \\ \text{csrSortedColInd} &= \begin{bmatrix} 0 & 3 & 0 & 1 & 0 & 2 & 3 \end{bmatrix} \\ \text{csrSortedVal} &= \begin{bmatrix} 1 & 2 & 3 & 4 & 5 & 6 & 7 \end{bmatrix} \end{align} \end{split}\]

  this function converts to sparse CSC format:

  \[\begin{split} \begin{align} \text{cscSortedRowInd} &= \begin{bmatrix} 0 & 1 & 2 & 1 & 2 & 0 & 2 \end{bmatrix} \\ \text{cscSortedColPtr} &= \begin{bmatrix} 0 & 3 & 4 & 5 & 7 \end{bmatrix} \\ \text{cscSortedVal} &= \begin{bmatrix} 1 & 3 & 5 & 4 & 6 & 2 & 7 \end{bmatrix} \end{align} \end{split}\]

  The CSC arrays, `cscSortedRowInd`, `cscSortedColPtr`, and `cscSortedVal` must be allocated by the user prior to calling `hipsparseXcsr2csc()`.

  Example

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

        // Sparse matrix in CSR format
        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        int hcsrRowPtr[4] = {0, 3, 5, 8};
        int hcsrColInd[8] = {0, 1, 3, 1, 2, 0, 3, 4};
        float hcsrVal[8]   = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f};

        int m         = 3;
        int n         = 5;
        int nnz       = 8;
        hipsparseIndexBase_t base = HIPSPARSE_INDEX_BASE_ZERO;
        hipsparseAction_t action = HIPSPARSE_ACTION_NUMERIC;

        int* dcsrRowPtr = nullptr;
        int* dcsrColInd = nullptr;
        float* dcsrVal = nullptr;
        hipMalloc((void**)&dcsrRowPtr, sizeof(int) * (m + 1));
        hipMalloc((void**)&dcsrColInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcsrVal, sizeof(float) * nnz);

        hipMemcpy(dcsrRowPtr, hcsrRowPtr, sizeof(int) * (m + 1), hipMemcpyHostToDevice);
        hipMemcpy(dcsrColInd, hcsrColInd, sizeof(int) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dcsrVal, hcsrVal, sizeof(float) * nnz, hipMemcpyHostToDevice);

        int* dcscRowInd = nullptr;
        int* dcscColPtr = nullptr;
        float* dcsc_val   = nullptr;
        hipMalloc((void**)&dcscRowInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcscColPtr, sizeof(int) * (n + 1));
        hipMalloc((void**)&dcsc_val, sizeof(float) * nnz);

        hipsparseScsr2csc(handle, m, n, nnz, dcsrVal, dcsrRowPtr, dcsrColInd, dcsc_val, dcscRowInd, dcscColPtr, action, base);

        hipFree(dcsrRowPtr);
        hipFree(dcsrColInd);
        hipFree(dcsrVal);

        hipFree(dcscRowInd);
        hipFree(dcscColPtr);
        hipFree(dcsc_val);

        hipsparseDestroy(handle);

  Note

  The resulting matrix can also be seen as the transpose of the input matrix.

  Note

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

  Parameters:

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

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - csrSortedVal – [in] array of `nnz` elements of the sparse CSR matrix.

    - csrSortedRowPtr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csrSortedColInd – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - cscSortedVal – [out] array of `nnz` elements of the sparse CSC matrix.

    - cscSortedRowInd – [out] array of `nnz` elements containing the row indices of the sparse CSC matrix.

    - cscSortedColPtr – [out] array of `n+1` elements that point to the start of every column of the sparse CSC matrix.

    - copyValues – [in] HIPSPARSE_ACTION_SYMBOLIC or HIPSPARSE_ACTION_NUMERIC.

    - idxBase – [in] HIPSPARSE_INDEX_BASE_ZERO or HIPSPARSE_INDEX_BASE_ONE.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnz`, `csrSortedVal`, `csrSortedRowPtr`, `csrSortedColInd`, `cscSortedVal`, `cscSortedRowInd` or `cscSortedColPtr` pointer is invalid.

    - HIPSPARSE_STATUS_ARCH_MISMATCH – the device is not supported.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXcsr2cscEx2_bufferSize()

hipsparseStatus_t hipsparseCsr2cscEx2_bufferSize(hipsparseHandle_t handle, int m, int n, int nnz, const void *csrVal, const int *csrRowPtr, const int *csrColInd, void *cscVal, int *cscColPtr, int *cscRowInd, hipDataType valType, hipsparseAction_t copyValues, hipsparseIndexBase_t idxBase, hipsparseCsr2CscAlg_t alg, size_t *pBufferSizeInBytes)

  This function computes the size of the user allocated temporary storage buffer used when converting a sparse CSR matrix into a sparse CSC matrix.

  `hipsparseCsr2cscEx2_bufferSize` calculates the required user allocated temporary buffer needed by hipsparseCsr2cscEx2 to convert a CSR matrix into a CSC matrix. hipsparseCsr2cscEx2 can also be used to convert a CSC matrix into a CSR matrix. `copyValues` decides whether `cscVal` is being filled during conversion (HIPSPARSE_ACTION_NUMERIC) or not (HIPSPARSE_ACTION_SYMBOLIC).

  Note

  The resulting matrix can also be seen as the transpose of the input matrix.

  Note

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

  Parameters:

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

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - csrVal – [in] array of `nnz` elements of the sparse CSR matrix.

    - csrRowPtr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csrColInd – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - cscVal – [in] array of `nnz` elements of the sparse CSC matrix.

    - cscColPtr – [in] array of `n+1` elements that point to the start of every column of the sparse CSC matrix.

    - cscRowInd – [in] array of `nnz` elements containing the row indices of the sparse CSC matrix.

    - valType – [in] The data type of the values arrays `csrVal` and `cscVal`. Can be HIP_R_32F, HIP_R_64F, HIP_C_32F or HIP_C_64F

    - copyValues – [in] HIPSPARSE_ACTION_SYMBOLIC or HIPSPARSE_ACTION_NUMERIC.

    - idxBase – [in] HIPSPARSE_INDEX_BASE_ZERO or HIPSPARSE_INDEX_BASE_ONE.

    - alg – [in] HIPSPARSE_CSR2CSC_ALG_DEFAULT, HIPSPARSE_CSR2CSC_ALG1 or HIPSPARSE_CSR2CSC_ALG2.

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseCsr2cscEx2().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnz`, `csrRowPtr`, `csrColInd` or `pBufferSizeInBytes` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXcsr2cscEx2()

hipsparseStatus_t hipsparseCsr2cscEx2(hipsparseHandle_t handle, int m, int n, int nnz, const void *csrVal, const int *csrRowPtr, const int *csrColInd, void *cscVal, int *cscColPtr, int *cscRowInd, hipDataType valType, hipsparseAction_t copyValues, hipsparseIndexBase_t idxBase, hipsparseCsr2CscAlg_t alg, void *buffer)

  Convert a sparse CSR matrix into a sparse CSC matrix.

  `hipsparseCsr2cscEx2` converts a CSR matrix into a CSC matrix. `hipsparseCsr2cscEx2` can also be used to convert a CSC matrix into a CSR matrix. `copyValues` decides whether `cscVal` is being filled during conversion (HIPSPARSE_ACTION_NUMERIC) or not (HIPSPARSE_ACTION_SYMBOLIC).

  Example

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

        // Sparse matrix in CSR format
        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        int hcsrRowPtr[4] = {0, 3, 5, 8};
        int hcsrColInd[8] = {0, 1, 3, 1, 2, 0, 3, 4};
        float hcsrVal[8]   = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f};

        int m         = 3;
        int n         = 5;
        int nnz       = 8;
        hipsparseIndexBase_t base = HIPSPARSE_INDEX_BASE_ZERO;
        hipsparseAction_t action = HIPSPARSE_ACTION_NUMERIC;
        hipsparseCsr2CscAlg_t alg = HIPSPARSE_CSR2CSC_ALG_DEFAULT;

        int* dcsrRowPtr = nullptr;
        int* dcsrColInd = nullptr;
        float* dcsrVal = nullptr;
        hipMalloc((void**)&dcsrRowPtr, sizeof(int) * (m + 1));
        hipMalloc((void**)&dcsrColInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcsrVal, sizeof(float) * nnz);

        hipMemcpy(dcsrRowPtr, hcsrRowPtr, sizeof(int) * (m + 1), hipMemcpyHostToDevice);
        hipMemcpy(dcsrColInd, hcsrColInd, sizeof(int) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dcsrVal, hcsrVal, sizeof(float) * nnz, hipMemcpyHostToDevice);

        int* dcscRowInd = nullptr;
        int* dcscColPtr = nullptr;
        float* dcsc_val   = nullptr;
        hipMalloc((void**)&dcscRowInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcscColPtr, sizeof(int) * (n + 1));
        hipMalloc((void**)&dcsc_val, sizeof(float) * nnz);

        size_t bufferSize;
        hipsparseCsr2cscEx2_bufferSize(handle,
                                       m,
                                       n,
                                       nnz,
                                       dcsrVal,
                                       dcsrRowPtr,
                                       dcsrColInd,
                                       dcsc_val,
                                       dcscColPtr,
                                       dcscRowInd,
                                       HIP_R_32F,
                                       action,
                                       base,
                                       alg,
                                       &bufferSize);

        void* dbuffer = nullptr;
        hipMalloc((void**)&dbuffer, bufferSize);

        hipsparseCsr2cscEx2(handle,
                            m,
                            n,
                            nnz,
                            dcsrVal,
                            dcsrRowPtr,
                            dcsrColInd,
                            dcsc_val,
                            dcscColPtr,
                            dcscRowInd,
                            HIP_R_32F,
                            action,
                            base,
                            alg,
                            dbuffer);

        hipFree(dcsrRowPtr);
        hipFree(dcsrColInd);
        hipFree(dcsrVal);

        hipFree(dcscRowInd);
        hipFree(dcscColPtr);
        hipFree(dcsc_val);

        hipFree(dbuffer);

        hipsparseDestroy(handle);

  Note

  The resulting matrix can also be seen as the transpose of the input matrix.

  Note

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

  Parameters:

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

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - csrVal – [in] array of `nnz` elements of the sparse CSR matrix.

    - csrRowPtr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csrColInd – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - cscVal – [in] array of `nnz` elements of the sparse CSC matrix.

    - cscColPtr – [in] array of `n+1` elements that point to the start of every column of the sparse CSC matrix.

    - cscRowInd – [in] array of `nnz` elements containing the row indices of the sparse CSC matrix.

    - valType – [in] The data type of the values arrays `csrVal` and `cscVal`. Can be HIP_R_32F, HIP_R_64F, HIP_C_32F or HIP_C_64F

    - copyValues – [in] HIPSPARSE_ACTION_SYMBOLIC or HIPSPARSE_ACTION_NUMERIC.

    - idxBase – [in] HIPSPARSE_INDEX_BASE_ZERO or HIPSPARSE_INDEX_BASE_ONE.

    - alg – [in] HIPSPARSE_CSR2CSC_ALG_DEFAULT, HIPSPARSE_CSR2CSC_ALG1 or HIPSPARSE_CSR2CSC_ALG2.

    - buffer – [in] temporary storage buffer allocated by the user, size is returned by hipsparseCsr2cscEx2_bufferSize().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnz`, `csrRowPtr`, `csrColInd` or `pBufferSizeInBytes` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXcsr2hyb()

hipsparseStatus_t hipsparseScsr2hyb(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descrA, const float *csrSortedValA, const int *csrSortedRowPtrA, const int *csrSortedColIndA, hipsparseHybMat_t hybA, int userEllWidth, hipsparseHybPartition_t partitionType)

hipsparseStatus_t hipsparseDcsr2hyb(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descrA, const double *csrSortedValA, const int *csrSortedRowPtrA, const int *csrSortedColIndA, hipsparseHybMat_t hybA, int userEllWidth, hipsparseHybPartition_t partitionType)

hipsparseStatus_t hipsparseCcsr2hyb(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descrA, const hipComplex *csrSortedValA, const int *csrSortedRowPtrA, const int *csrSortedColIndA, hipsparseHybMat_t hybA, int userEllWidth, hipsparseHybPartition_t partitionType)

hipsparseStatus_t hipsparseZcsr2hyb(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descrA, const hipDoubleComplex *csrSortedValA, const int *csrSortedRowPtrA, const int *csrSortedColIndA, hipsparseHybMat_t hybA, int userEllWidth, hipsparseHybPartition_t partitionType)

  Convert a sparse CSR matrix into a sparse HYB matrix.

  `hipsparseXcsr2hyb` converts a CSR matrix into a HYB matrix. It is assumed that `hyb` has been initialized with hipsparseCreateHybMat().

  Example

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

        hipsparseMatDescr_t descr;
        hipsparseCreateMatDescr(&descr);

        // Sparse matrix in CSR format
        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        int hcsrRowPtr[4] = {0, 3, 5, 8};
        int hcsrColInd[8] = {0, 1, 3, 1, 2, 0, 3, 4};
        float hcsrVal[8]   = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f};

        int m         = 3;
        int n         = 5;
        int nnz       = 8;
        int userEllWidth = 2;
        hipsparseHybPartition_t partitionType = HIPSPARSE_HYB_PARTITION_AUTO;

        int* dcsrRowPtr = nullptr;
        int* dcsrColInd = nullptr;
        float* dcsrVal = nullptr;
        hipMalloc((void**)&dcsrRowPtr, sizeof(int) * (m + 1));
        hipMalloc((void**)&dcsrColInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcsrVal, sizeof(float) * nnz);

        hipMemcpy(dcsrRowPtr, hcsrRowPtr, sizeof(int) * (m + 1), hipMemcpyHostToDevice);
        hipMemcpy(dcsrColInd, hcsrColInd, sizeof(int) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dcsrVal, hcsrVal, sizeof(float) * nnz, hipMemcpyHostToDevice);

        hipsparseHybMat_t hyb;
        hipsparseCreateHybMat(&hyb);

        hipsparseScsr2hyb(handle, m, n, descr, dcsrVal, dcsrRowPtr, dcsrColInd, hyb, userEllWidth, partitionType);

        hipFree(dcsrRowPtr);
        hipFree(dcsrColInd);
        hipFree(dcsrVal);

        hipsparseDestroyHybMat(hyb);
        hipsparseDestroyMatDescr(descr);

        hipsparseDestroy(handle);

  Note

  This function requires a significant amount of storage for the HYB matrix, depending on the matrix structure.

  Note

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

  Parameters:

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

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - descrA – [in] descriptor of the sparse CSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrSortedValA – [in] array containing the values of the sparse CSR matrix.

    - csrSortedRowPtrA – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csrSortedColIndA – [in] array containing the column indices of the sparse CSR matrix.

    - hybA – [out] sparse matrix in HYB format.

    - userEllWidth – [in] width of the ELL part of the HYB matrix (only required if `partitionType` == HIPSPARSE_HYB_PARTITION_USER).

    - partitionType – [in] HIPSPARSE_HYB_PARTITION_AUTO (recommended), HIPSPARSE_HYB_PARTITION_USER or HIPSPARSE_HYB_PARTITION_MAX.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `userEllWidth`, `partitionType`, `descrA`, `hybA`, `csrSortedValA`, `csrSortedRowPtrA` or `csrSortedColIndA` pointer is invalid.

    - HIPSPARSE_STATUS_ALLOC_FAILED – the buffer for the HYB matrix could not be allocated.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

    - HIPSPARSE_STATUS_NOT_SUPPORTED – hipsparseMatrixType_t != HIPSPARSE_MATRIX_TYPE_GENERAL.

## hipsparseXgebsr2gebsc_bufferSize()

hipsparseStatus_t hipsparseSgebsr2gebsc_bufferSize(hipsparseHandle_t handle, int mb, int nb, int nnzb, const float *bsrVal, const int *bsrRowPtr, const int *bsrColInd, int rowBlockDim, int colBlockDim, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseDgebsr2gebsc_bufferSize(hipsparseHandle_t handle, int mb, int nb, int nnzb, const double *bsrVal, const int *bsrRowPtr, const int *bsrColInd, int rowBlockDim, int colBlockDim, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseCgebsr2gebsc_bufferSize(hipsparseHandle_t handle, int mb, int nb, int nnzb, const hipComplex *bsrVal, const int *bsrRowPtr, const int *bsrColInd, int rowBlockDim, int colBlockDim, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseZgebsr2gebsc_bufferSize(hipsparseHandle_t handle, int mb, int nb, int nnzb, const hipDoubleComplex *bsrVal, const int *bsrRowPtr, const int *bsrColInd, int rowBlockDim, int colBlockDim, size_t *pBufferSizeInBytes)

  Convert a sparse GEBSR matrix into a sparse GEBSC matrix.

  `hipsparseXgebsr2gebsc_bufferSize` returns the size of the temporary storage buffer required by hipsparseXgebsr2gebsc() and is the first step in converting a sparse matrix in GEBSR format to a sparse matrix in GEBSC format. Once the size of the temporary storage buffer has been determined, it must be allocated by the user.

  See hipsparseSgebsr2gebsc() for a complete code example.

  Parameters:

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

    - mb – [in] number of rows of the sparse GEneral BSR matrix.

    - nb – [in] number of columns of the sparse GEneral BSR matrix.

    - nnzb – [in] number of non-zero entries of the sparse GEneral BSR matrix.

    - bsrVal – [in] array of `nnzb*rowBlockDim*colBlockDim` containing the values of the sparse GEneral BSR matrix.

    - bsrRowPtr – [in] array of `mb+1` elements that point to the start of every row of the sparse GEneral BSR matrix.

    - bsrColInd – [in] array of `nnzb` elements containing the column indices of the sparse GEneral BSR matrix.

    - rowBlockDim – [in] row size of the blocks in the sparse general BSR matrix.

    - colBlockDim – [in] col size of the blocks in the sparse general BSR matrix.

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseSgebsr2gebsc(), hipsparseDgebsr2gebsc(), hipsparseCgebsr2gebsc() and hipsparseZgebsr2gebsc().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `mb`, `nb`, `nnzb`, `bsrRowPtr`, `bsrColInd` or `pBufferSizeInBytes` pointer is invalid.

    - rocsparse_status_internal_error – an internal error occurred.

## hipsparseXgebsr2gebsc()

hipsparseStatus_t hipsparseSgebsr2gebsc(hipsparseHandle_t handle, int mb, int nb, int nnzb, const float *bsrVal, const int *bsrRowPtr, const int *bsrColInd, int rowBlockDim, int colBlockDim, float *bscVal, int *bscRowInd, int *bscColPtr, hipsparseAction_t copyValues, hipsparseIndexBase_t idxBase, void *temp_buffer)

hipsparseStatus_t hipsparseDgebsr2gebsc(hipsparseHandle_t handle, int mb, int nb, int nnzb, const double *bsrVal, const int *bsrRowPtr, const int *bsrColInd, int rowBlockDim, int colBlockDim, double *bscVal, int *bscRowInd, int *bscColPtr, hipsparseAction_t copyValues, hipsparseIndexBase_t idxBase, void *temp_buffer)

hipsparseStatus_t hipsparseCgebsr2gebsc(hipsparseHandle_t handle, int mb, int nb, int nnzb, const hipComplex *bsrVal, const int *bsrRowPtr, const int *bsrColInd, int rowBlockDim, int colBlockDim, hipComplex *bscVal, int *bscRowInd, int *bscColPtr, hipsparseAction_t copyValues, hipsparseIndexBase_t idxBase, void *temp_buffer)

hipsparseStatus_t hipsparseZgebsr2gebsc(hipsparseHandle_t handle, int mb, int nb, int nnzb, const hipDoubleComplex *bsrVal, const int *bsrRowPtr, const int *bsrColInd, int rowBlockDim, int colBlockDim, hipDoubleComplex *bscVal, int *bscRowInd, int *bscColPtr, hipsparseAction_t copyValues, hipsparseIndexBase_t idxBase, void *temp_buffer)

  Convert a sparse GEBSR matrix into a sparse GEBSC matrix.

  `hipsparseXgebsr2gebsc` converts a GEBSR matrix into a GEBSC matrix. `hipsparseXgebsr2gebsc` can also be used to convert a GEBSC matrix into a GEBSR matrix. `copyValues` decides whether `bscVal` is being filled during conversion (HIPSPARSE_ACTION_NUMERIC) or not (HIPSPARSE_ACTION_SYMBOLIC).

  `hipsparseXgebsr2gebsc` requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by hipsparseXgebsr2gebsc_bufferSize().

  For example, given the GEBSR matrix:

  \[\begin{split} \left[ \begin{array}{c | c} \begin{array}{c c} 1 & 2 \\ 3 & 4 \\ 6 & 0 \end{array} & \begin{array}{c c} 0 & 2 \\ 0 & 0 \\ 3 & 4 \end{array} \\ \hline \begin{array}{c c} 5 & 0 \\ 1 & 2 \\ 3 & 4 \end{array} & \begin{array}{c c} 6 & 7 \\ 3 & 4 \\ 3 & 4 \end{array} \\ \end{array} \right] \end{split}\]

  represented with the arrays:

  \[\begin{split} \begin{align} \text{bsrRowPtr} &= \begin{bmatrix} 0 & 2 & 4 \end{bmatrix} \\ \text{bsrColInd} &= \begin{bmatrix} 0 & 1 & 0 & 1 \end{bmatrix} \\ \text{bsrVal} &= \begin{bmatrix} 1 & 2 & 3 & 4 & 6 & 0 & 0 & 2 & 0 & 0 & 3 & 4 & 5 & 0 & 1 & 2 & 3 & 4 & 6 & 7 & 3 & 4 & 3 & 4 \end{bmatrix} \end{align} \end{split}\]

  this function converts the matrix to GEBSC format:

  \[\begin{split} \begin{align} \text{bscRowInd} &= \begin{bmatrix} 0 & 1 & 0 & 1 \end{bmatrix} \\ \text{bscColPtr} &= \begin{bmatrix} 0 & 2 & 4 \end{bmatrix} \\ \text{bscVal} &= \begin{bmatrix} 1 & 2 & 3 & 4 & 6 & 0 & 5 & 0 & 1 & 2 & 3 & 4 & 0 & 2 & 0 & 0 & 3 & 4 & 6 & 7 & 3 & 4 & 3 & 4 \end{bmatrix} \end{align} \end{split}\]

  The GEBSC arrays, `bscRowInd`, `bscColPtr`, and `bscVal` must be allocated by the user prior to calling `hipsparseXgebsr2gebsc()`. The `bscRowInd` array has size `nnzb`, the `bscColPtr` array has size `nb+1`, and the `bscVal` array has size `nnzb*rowBlockDim*colBlockDim`.

  Example

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

        // Sparse matrix in BSR format
        //     1 2 | 0 3 | 0 0
        //     0 4 | 5 0 | 0 1
        // A = 6 0 | 0 7 | 8 0
        //     ---------------
        //     0 0 | 3 0 | 2 2
        //     1 0 | 0 0 | 4 3
        //     7 2 | 0 0 | 1 4
        int hbsrRowPtr[3] = {0, 3, 6};
        int hbsrColInd[6] = {0, 1, 2, 0, 1, 2};
        float hbsrVal[36]  = {1.0f, 2.0f, 0.0f, 4.0f, 6.0f, 0.0f,
                               0.0f, 3.0f, 5.0f, 0.0f, 0.0f, 7.0f,
                               0.0f, 0.0f, 0.0f, 1.0f, 8.0f, 0.0f,
                               0.0f, 0.0f, 1.0f, 0.0f, 7.0f, 2.0f,
                               3.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f,
                               2.0f, 2.0f, 4.0f, 3.0f, 1.0f, 4.0f};

        int m           = 6;
        int n           = 6;
        int rowBlockDim = 3;
        int colBlockDim = 2;
        int nnzb        = 6;
        hipsparseDirection_t dir = HIPSPARSE_DIRECTION_ROW;
        hipsparseAction_t    action = HIPSPARSE_ACTION_NUMERIC;
        hipsparseIndexBase_t base = HIPSPARSE_INDEX_BASE_ZERO;

        int mb = (m + rowBlockDim - 1) / rowBlockDim;
        int nb = (n + colBlockDim - 1) / colBlockDim;

        int* dbsrRowPtr = nullptr;
        int* dbsrColInd = nullptr;
        float* dbsrVal = nullptr;
        hipMalloc((void**)&dbsrRowPtr, sizeof(int) * (mb + 1));
        hipMalloc((void**)&dbsrColInd, sizeof(int) * nnzb);
        hipMalloc((void**)&dbsrVal, sizeof(float) * rowBlockDim * colBlockDim * nnzb);

        hipMemcpy(dbsrRowPtr, hbsrRowPtr, sizeof(int) * (mb + 1), hipMemcpyHostToDevice);
        hipMemcpy(dbsrColInd, hbsrColInd, sizeof(int) * nnzb, hipMemcpyHostToDevice);
        hipMemcpy(dbsrVal, hbsrVal, sizeof(float) * rowBlockDim * colBlockDim * nnzb, hipMemcpyHostToDevice);

        int* dbscRowInd = nullptr;
        int* dbscColPtr = nullptr;
        float* dbscVal = nullptr;
        hipMalloc((void**)&dbscRowInd, sizeof(int) * nnzb);
        hipMalloc((void**)&dbscColPtr, sizeof(int) * (nb + 1));
        hipMalloc((void**)&dbscVal, sizeof(float) * rowBlockDim * colBlockDim * nnzb);

        size_t bufferSize;
        hipsparseSgebsr2gebsc_bufferSize(handle,
                                         mb,
                                         nb,
                                         nnzb,
                                         dbsrVal,
                                         dbsrRowPtr,
                                         dbsrColInd,
                                         rowBlockDim,
                                         colBlockDim,
                                         &bufferSize);

        void* dbuffer = nullptr;
        hipMalloc((void**)&dbuffer, bufferSize);

        hipsparseSgebsr2gebsc(handle,
                              mb,
                              nb,
                              nnzb,
                              dbsrVal,
                              dbsrRowPtr,
                              dbsrColInd,
                              rowBlockDim,
                              colBlockDim,
                              dbscVal,
                              dbscRowInd,
                              dbscColPtr,
                              action,
                              base,
                              dbuffer);

        hipFree(dbsrRowPtr);
        hipFree(dbsrColInd);
        hipFree(dbsrVal);

        hipFree(dbscRowInd);
        hipFree(dbscColPtr);
        hipFree(dbscVal);

        hipFree(dbuffer);

        hipsparseDestroy(handle);

  Note

  The resulting matrix can also be seen as the transpose of the input matrix.

  Note

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

  Parameters:

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

    - mb – [in] number of rows of the sparse GEneral BSR matrix.

    - nb – [in] number of columns of the sparse GEneral BSR matrix.

    - nnzb – [in] number of non-zero entries of the sparse GEneral BSR matrix.

    - bsrVal – [in] array of `nnzb` * `rowBlockDim` * `colBlockDim` elements of the sparse GEneral BSR matrix.

    - bsrRowPtr – [in] array of `m+1` elements that point to the start of every row of the sparse GEneral BSR matrix.

    - bsrColInd – [in] array of `nnz` elements containing the column indices of the sparse GEneral BSR matrix.

    - rowBlockDim – [in] row size of the blocks in the sparse general BSR matrix.

    - colBlockDim – [in] col size of the blocks in the sparse general BSR matrix.

    - bscVal – [out] array of `nnz` elements of the sparse BSC matrix.

    - bscRowInd – [out] array of `nnz` elements containing the row indices of the sparse BSC matrix.

    - bscColPtr – [out] array of `n+1` elements that point to the start of every column of the sparse BSC matrix.

    - copyValues – [in] HIPSPARSE_ACTION_SYMBOLIC or HIPSPARSE_ACTION_NUMERIC.

    - idxBase – [in] HIPSPARSE_INDEX_BASE_ZERO or HIPSPARSE_INDEX_BASE_ONE.

    - temp_buffer – [in] temporary storage buffer allocated by the user, size is returned by hipsparseXgebsr2gebsc_bufferSize().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `mb`, `nb`, `nnzb`, `bsrVal`, `bsrRowPtr`, `bsrColInd`, `bscVal`, `bscRowInd`, `bscColPtr` or `temp_buffer` pointer is invalid.

    - HIPSPARSE_STATUS_ARCH_MISMATCH – the device is not supported.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXcsr2gebsr_bufferSize()

hipsparseStatus_t hipsparseScsr2gebsr_bufferSize(hipsparseHandle_t handle, hipsparseDirection_t dir, int m, int n, const hipsparseMatDescr_t csr_descr, const float *csrVal, const int *csrRowPtr, const int *csrColInd, int rowBlockDim, int colBlockDim, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseDcsr2gebsr_bufferSize(hipsparseHandle_t handle, hipsparseDirection_t dir, int m, int n, const hipsparseMatDescr_t csr_descr, const double *csrVal, const int *csrRowPtr, const int *csrColInd, int rowBlockDim, int colBlockDim, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseCcsr2gebsr_bufferSize(hipsparseHandle_t handle, hipsparseDirection_t dir, int m, int n, const hipsparseMatDescr_t csr_descr, const hipComplex *csrVal, const int *csrRowPtr, const int *csrColInd, int rowBlockDim, int colBlockDim, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseZcsr2gebsr_bufferSize(hipsparseHandle_t handle, hipsparseDirection_t dir, int m, int n, const hipsparseMatDescr_t csr_descr, const hipDoubleComplex *csrVal, const int *csrRowPtr, const int *csrColInd, int rowBlockDim, int colBlockDim, size_t *pBufferSizeInBytes)

  Convert a sparse CSR matrix into a sparse GEBSR matrix.

  `hipsparseXcsr2gebsr_bufferSize` returns the size of the temporary buffer that is required by hipsparseXcsr2gebsrNnz and hipsparseXcsr2gebsr(). Once the temporary buffer size has been determined, it must be allocated by the user prior to calling hipsparseXcsr2gebsrNnz and hipsparseXcsr2gebsr().

  See hipsparseScsr2gebsr() for complete code example.

  Note

  The routine does support asynchronous execution if the pointer mode is set to device.

  Parameters:

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

    - dir – [in] direction that specified whether to count nonzero elements by HIPSPARSE_DIRECTION_ROW or by HIPSPARSE_DIRECTION_COLUMN.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - csr_descr – [in] descriptor of the sparse CSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrVal – [in] array of `nnz` elements containing the values of the sparse CSR matrix.

    - csrRowPtr – [in] integer array containing `m+1` elements that point to the start of each row of the CSR matrix

    - csrColInd – [in] integer array of the column indices for each non-zero element in the CSR matrix

    - rowBlockDim – [in] the row block dimension of the GEneral BSR matrix. Between 1 and `m`

    - colBlockDim – [in] the col block dimension of the GEneral BSR matrix. Between 1 and `n`

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseXcsr2gebsrNnz() and hipsparseXcsr2gebsr().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `rowBlockDim`, `colBlockDim`, `csrVal`, `csrRowPtr`, `csrColInd` or `pBufferSizeInBytes` pointer is invalid.

## hipsparseXcsr2gebsrNnz()

hipsparseStatus_t hipsparseXcsr2gebsrNnz(hipsparseHandle_t handle, hipsparseDirection_t dir, int m, int n, const hipsparseMatDescr_t csr_descr, const int *csrRowPtr, const int *csrColInd, const hipsparseMatDescr_t bsr_descr, int *bsrRowPtr, int rowBlockDim, int colBlockDim, int *bsrNnzDevhost, void *pbuffer)

  This function computes the number of nonzero block columns per row and the total number of nonzero blocks in a sparse GEBSR matrix given a sparse CSR matrix as input.

  This is the second step in conveting a CSR matrix to a GEBSR matrix. The user must first call hipsparseXcsr2gebsr_bufferSize() to determine the size of the required temporary storage buffer. The user then allocates this buffer as well as the `bsrRowPtr` array ( size `mb+1` ) and passes both to `hipsparseXcsr2gebsrNnz()`. This second step then computes the number of nonzero block columns per row and the total number of nonzero blocks.

  In general, when converting a CSR matrix of size `m` x `n` to a GEBSR matrix, the resulting GEBSR matrix will have size `mb` x `nb` where `mb` and `nb` equal:

  \[\begin{split} \begin{align} \text{mb} &= \text{(m - 1) / rowBlockDim + 1} \\ \text{nb} &= \text{(n - 1) / colBlockDim + 1} \end{align} \end{split}\]

  For example given a matrix:

  \[\begin{split} \begin{bmatrix} 1 & 0 & 0 & 2 & 4 & 0 \\ 3 & 4 & 0 & 0 & 5 & 1 \\ 5 & 0 & 6 & 7 & 6 & 2 \end{bmatrix} \end{split}\]

  represented in CSR format with the arrays:

  \[\begin{split} \begin{align} \text{csrRowPtr} &= \begin{bmatrix} 0 & 3 & 7 & 12 \end{bmatrix} \\ \text{csrColInd} &= \begin{bmatrix} 0 & 3 & 4 & 0 & 1 & 4 & 5 & 0 & 2 & 3 & 4 & 5 \end{bmatrix} \\ \text{csrVal} &= \begin{bmatrix} 1 & 2 & 4 & 3 & 4 & 5 & 1 & 5 & 6 & 7 & 6 & 2 \end{bmatrix} \end{align} \end{split}\]

  the `bsrRowPtr` array and total nonzero block count will be filled with:

  \[\begin{split} \begin{align} \text{bsrRowPtr} &= \begin{bmatrix} 0 & 3 \end{bmatrix} \\ \text{*bsrNnzDevhost} &= 3 \end{align} \end{split}\]

  after calling `hipsparseXcsr2gebsrNnz` with `rowBlockDim=3` and `colBlockDim=2`.

  It may be the case that `rowBlockDim` does not divide evenly into `m` and/or that `colBlockDim` does not divide evenly into `n`. In these cases, the CSR matrix is expanded in size in order to fit full GEBSR blocks. For example, using the original CSR matrix but this time with `rowBlockDim=2` and `colBlockDim=3`, the function `hipsparseXcsr2gebsrNnz` computes the GEBSR row pointer array and total number of non-zero blocks for the GEBSR matrix:

  \[\begin{split} \left[ \begin{array}{c | c} \begin{array}{c c c} 1 & 0 & 0 \\ 3 & 4 & 0 \end{array} & \begin{array}{c c c} 2 & 4 & 0 \\ 0 & 5 & 1 \end{array} \\ \hline \begin{array}{c c c} 5 & 0 & 6 \\ 0 & 0 & 0 \end{array} & \begin{array}{c c c} 7 & 6 & 2 \\ 0 & 0 & 0 \end{array} \end{array} \right] \end{split}\]

  See hipsparseScsr2gebsr() for full code example.

  Note

  As indicated, `bsrNnzDevhost` can point either to host or device memory. This is controlled by setting the pointer mode. See hipsparseSetPointerMode().

  Parameters:

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

    - dir – [in] direction that specified whether to count nonzero elements by HIPSPARSE_DIRECTION_ROW or by HIPSPARSE_DIRECTION_COLUMN.

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - csr_descr – [in] descriptor of the sparse CSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrRowPtr – [in] integer array containing `m+1` elements that point to the start of each row of the CSR matrix

    - csrColInd – [in] integer array of the column indices for each non-zero element in the CSR matrix

    - bsr_descr – [in] descriptor of the sparse GEneral BSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - bsrRowPtr – [out] integer array containing `mb+1` elements that point to the start of each block row of the General BSR matrix

    - rowBlockDim – [in] the row block dimension of the GEneral BSR matrix. Between \(1\) and \(\min(m, n)\)

    - colBlockDim – [in] the col block dimension of the GEneral BSR matrix. Between \(1\) and \(\min(m, n)\)

    - bsrNnzDevhost – [out] total number of nonzero elements in device or host memory.

    - pbuffer – [in] buffer allocated by the user whose size is determined by calling hipsparseXcsr2gebsr_bufferSize().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `rowBlockDim`, `colBlockDim`, `csrRowPtr`, `csrColInd`, `bsrRowPtr` or `bsrNnzDevhost` pointer is invalid.

## hipsparseXcsr2gebsr()

hipsparseStatus_t hipsparseScsr2gebsr(hipsparseHandle_t handle, hipsparseDirection_t dir, int m, int n, const hipsparseMatDescr_t csr_descr, const float *csrVal, const int *csrRowPtr, const int *csrColInd, const hipsparseMatDescr_t bsr_descr, float *bsrVal, int *bsrRowPtr, int *bsrColInd, int rowBlockDim, int colBlockDim, void *pbuffer)

hipsparseStatus_t hipsparseDcsr2gebsr(hipsparseHandle_t handle, hipsparseDirection_t dir, int m, int n, const hipsparseMatDescr_t csr_descr, const double *csrVal, const int *csrRowPtr, const int *csrColInd, const hipsparseMatDescr_t bsr_descr, double *bsrVal, int *bsrRowPtr, int *bsrColInd, int rowBlockDim, int colBlockDim, void *pbuffer)

hipsparseStatus_t hipsparseCcsr2gebsr(hipsparseHandle_t handle, hipsparseDirection_t dir, int m, int n, const hipsparseMatDescr_t csr_descr, const hipComplex *csrVal, const int *csrRowPtr, const int *csrColInd, const hipsparseMatDescr_t bsr_descr, hipComplex *bsrVal, int *bsrRowPtr, int *bsrColInd, int rowBlockDim, int colBlockDim, void *pbuffer)

hipsparseStatus_t hipsparseZcsr2gebsr(hipsparseHandle_t handle, hipsparseDirection_t dir, int m, int n, const hipsparseMatDescr_t csr_descr, const hipDoubleComplex *csrVal, const int *csrRowPtr, const int *csrColInd, const hipsparseMatDescr_t bsr_descr, hipDoubleComplex *bsrVal, int *bsrRowPtr, int *bsrColInd, int rowBlockDim, int colBlockDim, void *pbuffer)

  Convert a sparse CSR matrix into a sparse GEBSR matrix.

  `hipsparseXcsr2gebsr` converts a CSR matrix into a GEBSR matrix. It is assumed, that `bsrVal`, `bsrColInd` and `bsrRowPtr` are allocated. Allocation size for `bsrRowPtr` is computed as `mb+1` where `mb` is the number of block rows in the GEBSR matrix. The number of nonzero blocks in the resulting GEBSR matrix is computed using hipsparseXcsr2gebsrNnz which also fills in `bsrRowPtr`.

  In more detail, `hipsparseXcsr2gebsr` is the third and final step on the conversion from CSR to GEBSR. The user first determines the size of the required user allocated temporary storage buffer using hipsparseXcsr2gebsr_bufferSize(). The user then allocates this buffer as well as the row pointer array `bsrRowPtr` with size `mb+1`, where `mb` is the number of block rows in the GEBSR matrix and `nb` is the number of block columns in GEBSR matrix:

  \[\begin{split} \begin{align} \text{mb} &= \text{(m - 1) / rowBlockDim + 1} \\ \text{nb} &= \text{(n - 1) / colBlockDim + 1} \end{align} \end{split}\]

  Both the temporary storage buffer and the GEBSR row pointer array are then passed to hipsparseXcsr2gebsrNnz which fills the GEBSR row pointer array `bsrRowPtr` and also computes the number of nonzero blocks, `bsrNnzDevhost`, that will exist in the GEBSR matrix. The user then allocates both the GEBSR column indices array `bsrColInd` with size `bsrNnzDevhost` as well as the GEBSR values array `bsrVal` with size `bsrNnzDevhost*rowBlockDim*colBlockDim`. Finally, with all arrays allocated, the conversion is completed by calling `hipsparseXcsr2gebsr`.

  For example, assuming the matrix:

  \[\begin{split} \begin{bmatrix} 1 & 0 & 0 & 2 & 4 & 0 \\ 3 & 4 & 0 & 0 & 5 & 1 \\ 5 & 0 & 6 & 7 & 6 & 2 \end{bmatrix} \end{split}\]

  represented in CSR format with the arrays:

  \[\begin{split} \begin{align} \text{csrRowPtr} &= \begin{bmatrix} 0 & 3 & 7 & 12 \end{bmatrix} \\ \text{csrColInd} &= \begin{bmatrix} 0 & 3 & 4 & 0 & 1 & 4 & 5 & 0 & 2 & 3 & 4 & 5 \end{bmatrix} \\ \text{csrVal} &= \begin{bmatrix} 1 & 2 & 4 & 3 & 4 & 5 & 1 & 5 & 6 & 7 & 6 & 2 \end{bmatrix} \end{align} \end{split}\]

  then using `rowBlockDim=3` and `colBlockDim=2`, the final GEBSR matrix is:

  \[\begin{split} \left[ \begin{array}{c | c} \begin{array}{c c} 1 & 0 \\ 3 & 4 \\ 3 & 0 \end{array} & \begin{array}{c c} 0 & 2 \\ 0 & 0 \\ 6 & 7 \end{array} & \begin{array}{c c} 4 & 0 \\ 5 & 1 \\ 6 & 2 \end{array} \end{array} \right] \end{split}\]

  and is represented with the arrays:

  \[\begin{split} \begin{align} \text{bsrRowPtr} &= \begin{bmatrix} 0 & 3 \end{bmatrix} \\ \text{bsrColInd} &= \begin{bmatrix} 0 & 1 & 2 \end{bmatrix} \\ \text{bsrVal} &= \begin{bmatrix} 1 & 0 & 3 & 4 & 3 & 0 & 0 & 2 & 0 & 0 & 6 & 7 & 4 & 0 & 5 & 1 & 6 & 2 \end{bmatrix} \end{align} \end{split}\]

  The above example assumes that the blocks are row ordered. If instead the blocks are column ordered, the `bsrVal` arrays becomes:

  \[ \begin{align} \text{bsrVal} &= \begin{bmatrix} 1 & 3 & 3 & 0 & 4 & 0 & 0 & 0 & 6 & 2 & 0 & 7 & 4 & 5 & 6 & 0 & 1 & 2 \end{bmatrix} \end{align} \]

  The block order direction is determined by `dir`.

  It may be the case that `rowBlockDim` does not divide evenly into `m` and/or that `colBlockDim` does not divide evenly into `n`. In these cases, the CSR matrix is expanded in size in order to fit full GEBSR blocks. For example, using the original CSR matrix but this time with `rowBlockDim=2` and `colBlockDim=3`, the resulting GEBSR matrix would looks like:

  \[\begin{split} \left[ \begin{array}{c | c} \begin{array}{c c c} 1 & 0 & 0 \\ 3 & 4 & 0 \end{array} & \begin{array}{c c c} 2 & 4 & 0 \\ 0 & 5 & 1 \end{array} \\ \hline \begin{array}{c c c} 5 & 0 & 6 \\ 0 & 0 & 0 \end{array} & \begin{array}{c c c} 7 & 6 & 2 \\ 0 & 0 & 0 \end{array} \end{array} \right] \end{split}\]

  Example

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

        hipsparseMatDescr_t csr_descr;
        hipsparseCreateMatDescr(&csr_descr);

        hipsparseMatDescr_t bsr_descr;
        hipsparseCreateMatDescr(&bsr_descr);

        // Sparse matrix in CSR format
        //     1 2 0 3 0 0
        //     0 4 5 0 0 1
        // A = 6 0 0 7 8 0
        //     0 0 3 0 2 2
        //     1 0 0 0 4 3
        //     7 2 0 0 1 4
        int hcsrRowPtr[7] = {0, 3, 6, 9, 12, 15, 19};
        int hcsrColInd[19] = {0, 1, 3, 1, 2, 5, 0, 3, 4, 2, 4, 5, 0, 4, 5, 0, 1, 4, 5};
        float hcsrVal[19]   = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 1.0f, 6.0f, 7.0f, 8.0f, 3.0f, 2.0f, 2.0f,
                               1.0f, 4.0f, 3.0f, 7.0f, 2.0f, 1.0f, 4.0f};

        int m           = 6;
        int n           = 6;
        int nnz         = 19;
        int rowBlockDim = 3;
        int colBlockDim = 2;
        hipsparseDirection_t dir = HIPSPARSE_DIRECTION_ROW;
        hipsparseIndexBase_t base = HIPSPARSE_INDEX_BASE_ZERO;

        int mb = (m + rowBlockDim - 1) / rowBlockDim;
        int nb = (n + colBlockDim - 1) / colBlockDim;

        int* dcsrRowPtr = nullptr;
        int* dcsrColInd = nullptr;
        float* dcsrVal = nullptr;
        hipMalloc((void**)&dcsrRowPtr, sizeof(int) * (m + 1));
        hipMalloc((void**)&dcsrColInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcsrVal, sizeof(float) * nnz);

        hipMemcpy(dcsrRowPtr, hcsrRowPtr, sizeof(int) * (m + 1), hipMemcpyHostToDevice);
        hipMemcpy(dcsrColInd, hcsrColInd, sizeof(int) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dcsrVal, hcsrVal, sizeof(float) * nnz, hipMemcpyHostToDevice);

        int* dbsrRowPtr = nullptr;
        hipMalloc((void**)&dbsrRowPtr, sizeof(int) * (mb + 1));

        size_t bufferSize;
        hipsparseScsr2gebsr_bufferSize(handle,
                                       dir,
                                       m,
                                       n,
                                       csr_descr,
                                       dcsrVal,
                                       dcsrRowPtr,
                                       dcsrColInd,
                                       rowBlockDim,
                                       colBlockDim,
                                       &bufferSize);

        void* dbuffer = nullptr;
        hipMalloc((void**)&dbuffer, bufferSize);

        int nnzb;
        hipsparseXcsr2gebsrNnz(handle,
                               dir,
                               m,
                               n,
                               csr_descr,
                               dcsrRowPtr,
                               dcsrColInd,
                               bsr_descr,
                               dbsrRowPtr,
                               rowBlockDim,
                               colBlockDim,
                               &nnzb,
                               dbuffer);

        int* dbsrColInd = nullptr;
        float* dbsrVal = nullptr;
        hipMalloc((void**)&dbsrColInd, sizeof(int) * nnzb);
        hipMalloc((void**)&dbsrVal, sizeof(float) * rowBlockDim * colBlockDim * nnzb);

        hipsparseScsr2gebsr(handle,
                            dir,
                            m,
                            n,
                            csr_descr,
                            dcsrVal,
                            dcsrRowPtr,
                            dcsrColInd,
                            bsr_descr,
                            dbsrVal,
                            dbsrRowPtr,
                            dbsrColInd,
                            rowBlockDim,
                            colBlockDim,
                            dbuffer);

        hipFree(dcsrRowPtr);
        hipFree(dcsrColInd);
        hipFree(dcsrVal);

        hipFree(dbsrRowPtr);
        hipFree(dbsrColInd);
        hipFree(dbsrVal);

        hipFree(dbuffer);

        hipsparseDestroyMatDescr(csr_descr);
        hipsparseDestroyMatDescr(bsr_descr);
        hipsparseDestroy(handle);

  Parameters:

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

    - dir – [in] the storage format of the blocks, HIPSPARSE_DIRECTION_ROW or HIPSPARSE_DIRECTION_COLUMN

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - csr_descr – [in] descriptor of the sparse CSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrVal – [in] array of `nnz` elements containing the values of the sparse CSR matrix.

    - csrRowPtr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csrColInd – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - bsr_descr – [in] descriptor of the sparse BSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - bsrVal – [out] array of `nnzb*` `rowBlockDim*` `colBlockDim` containing the values of the sparse BSR matrix.

    - bsrRowPtr – [out] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsrColInd – [out] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - rowBlockDim – [in] row size of the blocks in the sparse GEneral BSR matrix.

    - colBlockDim – [in] col size of the blocks in the sparse GEneral BSR matrix.

    - pbuffer – [in] buffer allocated by the user whose size is determined by calling hipsparseXcsr2gebsr_bufferSize().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `rowBlockDim`, `colBlockDim`, `bsrVal`, `bsrRowPtr`, `bsrColInd`, `csrVal`, `csrRowPtr` or `csrColInd` pointer is invalid.

## hipsparseXbsr2csr()

hipsparseStatus_t hipsparseSbsr2csr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, const hipsparseMatDescr_t descrA, const float *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int blockDim, const hipsparseMatDescr_t descrC, float *csrValC, int *csrRowPtrC, int *csrColIndC)

hipsparseStatus_t hipsparseDbsr2csr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, const hipsparseMatDescr_t descrA, const double *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int blockDim, const hipsparseMatDescr_t descrC, double *csrValC, int *csrRowPtrC, int *csrColIndC)

hipsparseStatus_t hipsparseCbsr2csr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, const hipsparseMatDescr_t descrA, const hipComplex *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int blockDim, const hipsparseMatDescr_t descrC, hipComplex *csrValC, int *csrRowPtrC, int *csrColIndC)

hipsparseStatus_t hipsparseZbsr2csr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, const hipsparseMatDescr_t descrA, const hipDoubleComplex *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int blockDim, const hipsparseMatDescr_t descrC, hipDoubleComplex *csrValC, int *csrRowPtrC, int *csrColIndC)

  Convert a sparse BSR matrix into a sparse CSR matrix.

  `hipsparseXbsr2csr` converts a BSR matrix into a CSR matrix. It is assumed, that `csrValC`, `csrColIndC` and `csrRowPtrC` are allocated. Allocation size for `csrRowPtrC` is computed by the number of block rows multiplied by the block dimension plus one. Allocation for `csrValC` and `csrColInd` is computed by the the number of blocks in the BSR matrix multiplied by the block dimension squared.

  For example, given the BSR matrix using block dimension 2:

  \[\begin{split} \left[ \begin{array}{c | c} \begin{array}{c c} 1 & 0 \\ 3 & 4 \end{array} & \begin{array}{c c} 0 & 2 \\ 0 & 0 \end{array} \\ \hline \begin{array}{c c} 5 & 0 \\ 1 & 2 \end{array} & \begin{array}{c c} 6 & 7 \\ 3 & 4 \end{array} \\ \end{array} \right] \end{split}\]

  The resulting CSR matrix row pointer, column indices, and values arrays are:

  \[\begin{split} \begin{align} \text{csrRowPtrC} &= \begin{bmatrix} 0 & 4 & 8 & 12 & 16 \end{bmatrix} \\ \text{csrColIndC} &= \begin{bmatrix} 0 & 1 & 2 & 3 & 0 & 1 & 2 & 3 & 0 & 1 & 2 & 3 & 0 & 1 & 2 & 3 \end{bmatrix} \\ \text{csrValC} &= \begin{bmatrix} 1 & 0 & 0 & 2 & 3 & 4 & 0 & 0 & 5 & 0 & 6 & 7 & 1 & 2 & 3 & 4 \end{bmatrix} \\ \end{align} \end{split}\]

  Example

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

        hipsparseMatDescr_t csr_descr;
        hipsparseCreateMatDescr(&csr_descr);

        hipsparseMatDescr_t bsr_descr;
        hipsparseCreateMatDescr(&bsr_descr);

        // Sparse matrix in BSR format
        //     1 2 | 0 3 | 0 0
        //     0 4 | 5 0 | 0 1
        //     ---------------
        // A = 6 0 | 0 7 | 8 0
        //     0 0 | 3 0 | 2 2
        //     ---------------
        //     1 0 | 0 0 | 4 3
        //     7 2 | 0 0 | 1 4
        int hbsrRowPtr[4] = {0, 3, 6, 8};
        int hbsrColInd[8] = {0, 1, 2, 0, 1, 2, 0, 2};
        float hbsrVal[32]  = {1.0f, 2.0f, 0.0f, 4.0f,
                                0.0f, 3.0f, 5.0f, 0.0f,
                                0.0f, 0.0f, 0.0f, 1.0f,
                                6.0f, 0.0f, 0.0f, 0.0f,
                                0.0f, 7.0f, 3.0f, 0.0f,
                                8.0f, 0.0f, 2.0f, 2.0f,
                                1.0f, 0.0f, 7.0f, 2.0f,
                                4.0f, 3.0f, 1.0f, 4.0f};

        int m        = 6;
        int n        = 6;
        int nnz      = 32;
        int mb       = 3;
        int nb       = 3;
        int nnzb     = 8;
        int blockDim = 2;
        hipsparseDirection_t dir = HIPSPARSE_DIRECTION_ROW;

        int* dbsrRowPtr = nullptr;
        int* dbsrColInd = nullptr;
        float* dbsrVal = nullptr;
        hipMalloc((void**)&dbsrRowPtr, sizeof(int) * (mb + 1));
        hipMalloc((void**)&dbsrColInd, sizeof(int) * nnzb);
        hipMalloc((void**)&dbsrVal, sizeof(float) * blockDim * blockDim * nnzb);

        hipMemcpy(dbsrRowPtr, hbsrRowPtr, sizeof(int) * (mb + 1), hipMemcpyHostToDevice);
        hipMemcpy(dbsrColInd, hbsrColInd, sizeof(int) * nnzb, hipMemcpyHostToDevice);
        hipMemcpy(dbsrVal, hbsrVal, sizeof(float) * blockDim * blockDim * nnzb, hipMemcpyHostToDevice);

        int* dcsrRowPtr = nullptr;
        int* dcsrColInd = nullptr;
        float* dcsrVal = nullptr;
        hipMalloc((void**)&dcsrRowPtr, sizeof(int) * (m + 1));
        hipMalloc((void**)&dcsrColInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcsrVal, sizeof(float) * nnz);

        hipsparseSbsr2csr(handle,
                          dir,
                          mb,
                          nb,
                          bsr_descr,
                          dbsrVal,
                          dbsrRowPtr,
                          dbsrColInd,
                          blockDim,
                          csr_descr,
                          dcsrVal,
                          dcsrRowPtr,
                          dcsrColInd);

        hipFree(dbsrRowPtr);
        hipFree(dbsrColInd);
        hipFree(dbsrVal);

        hipFree(dcsrRowPtr);
        hipFree(dcsrColInd);
        hipFree(dcsrVal);

        hipsparseDestroyMatDescr(csr_descr);
        hipsparseDestroyMatDescr(bsr_descr);
        hipsparseDestroy(handle);

  Note

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

  Parameters:

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

    - dirA – [in] the storage format of the blocks, HIPSPARSE_DIRECTION_ROW or HIPSPARSE_DIRECTION_COLUMN

    - mb – [in] number of block rows in the sparse BSR matrix.

    - nb – [in] number of block columns in the sparse BSR matrix.

    - descrA – [in] descriptor of the sparse BSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - bsrValA – [in] array of `nnzb*blockDim*blockDim` containing the values of the sparse BSR matrix.

    - bsrRowPtrA – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsrColIndA – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - blockDim – [in] size of the blocks in the sparse BSR matrix.

    - descrC – [in] descriptor of the sparse CSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValC – [out] array of `nnzb*blockDim*blockDim` elements containing the values of the sparse CSR matrix.

    - csrRowPtrC – [out] array of `m+1` where `m=mb*blockDim` elements that point to the start of every row of the sparse CSR matrix.

    - csrColIndC – [out] array of `nnzb*blockDim*blockDim` elements containing the column indices of the sparse CSR matrix.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `mb`, `nb`, `blockDim`, `bsrValA`, `bsrRowPtrA`, `bsrColIndA`, `csrValC`, `csrRowPtrC` or `csrColIndC` pointer is invalid.

## hipsparseXgebsr2csr()

hipsparseStatus_t hipsparseSgebsr2csr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, const hipsparseMatDescr_t descrA, const float *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int rowBlockDim, int colBlockDim, const hipsparseMatDescr_t descrC, float *csrValC, int *csrRowPtrC, int *csrColIndC)

hipsparseStatus_t hipsparseDgebsr2csr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, const hipsparseMatDescr_t descrA, const double *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int rowBlockDim, int colBlockDim, const hipsparseMatDescr_t descrC, double *csrValC, int *csrRowPtrC, int *csrColIndC)

hipsparseStatus_t hipsparseCgebsr2csr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, const hipsparseMatDescr_t descrA, const hipComplex *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int rowBlockDim, int colBlockDim, const hipsparseMatDescr_t descrC, hipComplex *csrValC, int *csrRowPtrC, int *csrColIndC)

hipsparseStatus_t hipsparseZgebsr2csr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, const hipsparseMatDescr_t descrA, const hipDoubleComplex *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int rowBlockDim, int colBlockDim, const hipsparseMatDescr_t descrC, hipDoubleComplex *csrValC, int *csrRowPtrC, int *csrColIndC)

  Convert a sparse GEBSR matrix into a sparse CSR matrix.

  `hipsparseXgebsr2csr` converts a GEBSR matrix into a CSR matrix. It is assumed, that `csrValC`, `csrColIndC` and `csrRowPtrC` are already allocated prior to calling `hipsparseXgebsr2csr`. Allocation size for `csrRowPtrC` equals `m+1` where:

  \[\begin{split} \begin{align} \text{m} &= \text{mb * rowBlockDim} \\ \text{n} &= \text{nb * colBlockDim} \end{align} \end{split}\]

  Allocation size for `csrValC` and `csrColIndC` is computed by the the number of blocks in the GEBSR matrix, `nnzb`, multiplied by the product of the block dimensions, i.e. `nnz=nnzb*rocBlockDim*colBlockDim`.

  For example, given the GEBSR matrix:

  \[\begin{split} \left[ \begin{array}{c | c | c} \begin{array}{c c} 6 & 2 \\ 1 & 4 \\ 5 & 4 \end{array} & \begin{array}{c c} 0 & 3 \\ 5 & 0 \\ 0 & 7 \end{array} & \begin{array}{c c} 0 & 0 \\ 0 & 0 \\ 0 & 0 \end{array} \\ \hline \begin{array}{c c} 0 & 0 \\ 0 & 0 \\ 0 & 0 \end{array} & \begin{array}{c c} 3 & 0 \\ 0 & 0 \\ 0 & 7 \end{array} & \begin{array}{c c} 2 & 2 \\ 4 & 3 \\ 1 & 4 \end{array} \\ \end{array} \right] \end{split}\]

  Example

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

        hipsparseMatDescr_t csr_descr;
        hipsparseCreateMatDescr(&csr_descr);

        hipsparseMatDescr_t bsr_descr;
        hipsparseCreateMatDescr(&bsr_descr);

        // Sparse matrix in GEBSR format
        //     1 2 | 0 3 | 0 0
        //     0 4 | 5 0 | 0 1
        // A = 6 0 | 0 7 | 8 0
        //     ---------------
        //     0 0 | 3 0 | 2 2
        //     1 0 | 0 0 | 4 3
        //     7 2 | 0 0 | 1 4
        int hbsrRowPtr[3] = {0, 3, 6};
        int hbsrColInd[6] = {0, 1, 2, 0, 1, 2};
        float hbsrVal[36]  = {1.0f, 2.0f, 0.0f, 4.0f, 6.0f, 0.0f,
                               0.0f, 3.0f, 5.0f, 0.0f, 0.0f, 7.0f,
                               0.0f, 0.0f, 0.0f, 1.0f, 8.0f, 0.0f,
                               0.0f, 0.0f, 1.0f, 0.0f, 7.0f, 2.0f,
                               3.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f,
                               2.0f, 2.0f, 4.0f, 3.0f, 1.0f, 4.0f};

        int m        = 6;
        int n        = 6;
        int nnz      = 36;
        int mb       = 2;
        int nb       = 3;
        int nnzb     = 6;
        int rowBlockDim = 3;
        int colBlockDim = 2;
        hipsparseDirection_t dir = HIPSPARSE_DIRECTION_ROW;

        int* dbsrRowPtr = nullptr;
        int* dbsrColInd = nullptr;
        float* dbsrVal = nullptr;
        hipMalloc((void**)&dbsrRowPtr, sizeof(int) * (mb + 1));
        hipMalloc((void**)&dbsrColInd, sizeof(int) * nnzb);
        hipMalloc((void**)&dbsrVal, sizeof(float) * rowBlockDim * colBlockDim * nnzb);

        hipMemcpy(dbsrRowPtr, hbsrRowPtr, sizeof(int) * (mb + 1), hipMemcpyHostToDevice);
        hipMemcpy(dbsrColInd, hbsrColInd, sizeof(int) * nnzb, hipMemcpyHostToDevice);
        hipMemcpy(dbsrVal, hbsrVal, sizeof(float) * rowBlockDim * colBlockDim * nnzb, hipMemcpyHostToDevice);

        int* dcsrRowPtr = nullptr;
        int* dcsrColInd = nullptr;
        float* dcsrVal = nullptr;
        hipMalloc((void**)&dcsrRowPtr, sizeof(int) * (m + 1));
        hipMalloc((void**)&dcsrColInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcsrVal, sizeof(float) * nnz);

        hipsparseSgebsr2csr(handle,
                            dir,
                            mb,
                            nb,
                            bsr_descr,
                            dbsrVal,
                            dbsrRowPtr,
                            dbsrColInd,
                            rowBlockDim,
                            colBlockDim,
                            csr_descr,
                            dcsrVal,
                            dcsrRowPtr,
                            dcsrColInd);

        hipFree(dbsrRowPtr);
        hipFree(dbsrColInd);
        hipFree(dbsrVal);

        hipFree(dcsrRowPtr);
        hipFree(dcsrColInd);
        hipFree(dcsrVal);

        hipsparseDestroyMatDescr(csr_descr);
        hipsparseDestroyMatDescr(bsr_descr);
        hipsparseDestroy(handle);

  Note

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

  Parameters:

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

    - dirA – [in] the storage format of the blocks, HIPSPARSE_DIRECTION_ROW or HIPSPARSE_DIRECTION_COLUMN

    - mb – [in] number of block rows in the sparse general BSR matrix.

    - nb – [in] number of block columns in the sparse general BSR matrix.

    - descrA – [in] descriptor of the sparse general BSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - bsrValA – [in] array of `nnzb*rowBlockDim*colBlockDim` containing the values of the sparse BSR matrix.

    - bsrRowPtrA – [in] array of `mb+1` elements that point to the start of every block row of the sparse BSR matrix.

    - bsrColIndA – [in] array of `nnzb` elements containing the block column indices of the sparse BSR matrix.

    - rowBlockDim – [in] row size of the blocks in the sparse general BSR matrix.

    - colBlockDim – [in] column size of the blocks in the sparse general BSR matrix.

    - descrC – [in] descriptor of the sparse CSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValC – [out] array of `nnzb*rowBlockDim*colBlockDim` elements containing the values of the sparse CSR matrix.

    - csrRowPtrC – [out] array of `m+1` where `m=mb*rowBlockDim` elements that point to the start of every row of the sparse CSR matrix.

    - csrColIndC – [out] array of `nnzb*block_dim*block_dim` elements containing the column indices of the sparse CSR matrix.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `mb`, `nb`, `block_dim`, `bsrValA`, `bsrRowPtrA`, `bsrColIndA`, `csrValC`, `csrRowPtrC` or `csrColIndC` pointer is invalid.

## hipsparseXcsr2csr_compress()

hipsparseStatus_t hipsparseScsr2csr_compress(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descrA, const float *csrValA, const int *csrColIndA, const int *csrRowPtrA, int nnzA, const int *nnzPerRow, float *csrValC, int *csrColIndC, int *csrRowPtrC, float tol)

hipsparseStatus_t hipsparseDcsr2csr_compress(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descrA, const double *csrValA, const int *csrColIndA, const int *csrRowPtrA, int nnzA, const int *nnzPerRow, double *csrValC, int *csrColIndC, int *csrRowPtrC, double tol)

hipsparseStatus_t hipsparseCcsr2csr_compress(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descrA, const hipComplex *csrValA, const int *csrColIndA, const int *csrRowPtrA, int nnzA, const int *nnzPerRow, hipComplex *csrValC, int *csrColIndC, int *csrRowPtrC, hipComplex tol)

hipsparseStatus_t hipsparseZcsr2csr_compress(hipsparseHandle_t handle, int m, int n, const hipsparseMatDescr_t descrA, const hipDoubleComplex *csrValA, const int *csrColIndA, const int *csrRowPtrA, int nnzA, const int *nnzPerRow, hipDoubleComplex *csrValC, int *csrColIndC, int *csrRowPtrC, hipDoubleComplex tol)

  Convert a sparse CSR matrix into a compressed sparse CSR matrix.

  `hipsparseXcsr2csr_compress` converts a CSR matrix into a compressed CSR matrix by removing entries in the input CSR matrix that are below a non-negative threshold `tol:`

  \[ C(i,j) = A(i, j) \text{ if |A(i, j)| > tol} \]

  The user must first call hipsparseXnnz_compress() to determine the number of nonzeros per row as well as the total number of nonzeros that will exist in resulting compressed CSR matrix. The user then uses this information to allocate the column indices array `csrColIndC` and the values array `csrValC`. The user then calls `hipsparseXcsr2csr_compress` to complete the conversion.

  Example

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

        // Matrix descriptor
        hipsparseMatDescr_t descr;
        hipsparseCreateMatDescr(&descr);

        // Sparse matrix in CSR format
        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        int hcsrRowPtrA[4] = {0, 3, 5, 8};
        int hcsrColIndA[8] = {0, 1, 3, 1, 2, 0, 3, 4};
        float hcsrValA[8]   = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f};

        int m    = 3;
        int n    = 5;
        int nnzA = 8;

        float tol = 5.9f;

        int* dcsrRowPtrA = nullptr;
        int* dcsrColIndA = nullptr;
        float* dcsrValA = nullptr;
        hipMalloc((void**)&dcsrRowPtrA, sizeof(int) * (m + 1));
        hipMalloc((void**)&dcsrColIndA, sizeof(int) * nnzA);
        hipMalloc((void**)&dcsrValA, sizeof(float) * nnzA);

        hipMemcpy(dcsrRowPtrA, hcsrRowPtrA, sizeof(int) * (m + 1), hipMemcpyHostToDevice);
        hipMemcpy(dcsrColIndA, hcsrColIndA, sizeof(int) * nnzA, hipMemcpyHostToDevice);
        hipMemcpy(dcsrValA, hcsrValA, sizeof(float) * nnzA, hipMemcpyHostToDevice);

        // Allocate memory for the nnz_per_row array
        int* dnnz_per_row;
        hipMalloc((void**)&dnnz_per_row, sizeof(int) * m);

        // Call snnz_compress() which fills in nnz_per_row array and finds the number
        // of entries that will be in the compressed CSR matrix
        int nnzC;
        hipsparseSnnz_compress(handle, m, descr, dcsrValA, dcsrRowPtrA, dnnz_per_row, &nnzC, tol);

        int* dcsrRowPtrC = nullptr;
        int* dcsrColIndC = nullptr;
        float* dcsrValC = nullptr;
        hipMalloc((void**)&dcsrRowPtrC, sizeof(int) * (m + 1));
        hipMalloc((void**)&dcsrColIndC, sizeof(int) * nnzC);
        hipMalloc((void**)&dcsrValC, sizeof(float) * nnzC);

        hipsparseScsr2csr_compress(handle,
                                   m,
                                   n,
                                   descr,
                                   dcsrValA,
                                   dcsrColIndA,
                                   dcsrRowPtrA,
                                   nnzA,
                                   dnnz_per_row,
                                   dcsrValC,
                                   dcsrColIndC,
                                   dcsrRowPtrC,
                                   tol);

        hipFree(dcsrRowPtrA);
        hipFree(dcsrColIndA);
        hipFree(dcsrValA);

        hipFree(dcsrRowPtrC);
        hipFree(dcsrColIndC);
        hipFree(dcsrValC);

        hipFree(dnnz_per_row);

        hipsparseDestroyMatDescr(descr);
        hipsparseDestroy(handle);

  Note

  In the case of complex matrices only the magnitude of the real part of `tol` is used.

  Parameters:

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

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - descrA – [in] matrix descriptor for the CSR matrix

    - csrValA – [in] array of `nnzA` elements of the sparse CSR matrix.

    - csrRowPtrA – [in] array of `m+1` elements that point to the start of every row of the uncompressed sparse CSR matrix.

    - csrColIndA – [in] array of `nnzA` elements containing the column indices of the uncompressed sparse CSR matrix.

    - nnzA – [in] number of elements in the column indices and values arrays of the uncompressed sparse CSR matrix.

    - nnzPerRow – [in] array of length `m` containing the number of entries that will be kept per row in the final compressed CSR matrix.

    - csrValC – [out] array of `nnzC` elements of the compressed sparse CSC matrix.

    - csrRowPtrC – [out] array of `m+1` elements that point to the start of every column of the compressed sparse CSR matrix.

    - csrColIndC – [out] array of `nnzC` elements containing the row indices of the compressed sparse CSR matrix.

    - tol – [in] the non-negative tolerance used for compression. If `tol` is complex then only the magnitude of the real part is used. Entries in the input uncompressed CSR array that are below the tolerance are removed in output compressed CSR matrix.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnzA`, `tol`, `csrValA`, `csrRowPtrA`, `csrColIndA`, `csrValC`, `csrRowPtrC`, `csrColIndC` or `nnzPerRow` pointer is invalid.

## hipsparseXpruneCsr2csr_bufferSize()

hipsparseStatus_t hipsparseSpruneCsr2csr_bufferSize(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const float *csrValA, const int *csrRowPtrA, const int *csrColIndA, const float *threshold, const hipsparseMatDescr_t descrC, const float *csrValC, const int *csrRowPtrC, const int *csrColIndC, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseDpruneCsr2csr_bufferSize(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const double *csrValA, const int *csrRowPtrA, const int *csrColIndA, const double *threshold, const hipsparseMatDescr_t descrC, const double *csrValC, const int *csrRowPtrC, const int *csrColIndC, size_t *pBufferSizeInBytes)

  Convert and prune sparse CSR matrix into a sparse CSR matrix.

  `hipsparseXpruneCsr2csr_bufferSize` returns the size of the temporary buffer that is required by `hipsparseXpruneCsr2csrNnz` and hipsparseXpruneCsr2csr. The temporary storage buffer must be allocated by the user.

  Parameters:

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

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - nnzA – [in] number of non-zeros in the sparse CSR matrix A.

    - descrA – [in] descriptor of the sparse CSR matrix A. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValA – [in] array of `nnzA` elements containing the values of the sparse CSR matrix A.

    - csrRowPtrA – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csrColIndA – [in] array of `nnzA` elements containing the column indices of the sparse CSR matrix A.

    - threshold – [in] pointer to the non-negative pruning threshold which can exist in either host or device memory.

    - descrC – [in] descriptor of the sparse CSR matrix C. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValC – [in] array of `nnzC` elements containing the values of the sparse CSR matrix C.

    - csrRowPtrC – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix C.

    - csrColIndC – [in] array of `nnzC` elements containing the column indices of the sparse CSR matrix C.

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseSpruneCsr2csrNnz(), hipsparseDpruneCsr2csrNnz(), hipsparseSpruneCsr2csr(), and hipsparseDpruneCsr2csr().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle` or `pBufferSizeInBytes` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXpruneCsr2csr_bufferSizeExt()

hipsparseStatus_t hipsparseSpruneCsr2csr_bufferSizeExt(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const float *csrValA, const int *csrRowPtrA, const int *csrColIndA, const float *threshold, const hipsparseMatDescr_t descrC, const float *csrValC, const int *csrRowPtrC, const int *csrColIndC, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseDpruneCsr2csr_bufferSizeExt(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const double *csrValA, const int *csrRowPtrA, const int *csrColIndA, const double *threshold, const hipsparseMatDescr_t descrC, const double *csrValC, const int *csrRowPtrC, const int *csrColIndC, size_t *pBufferSizeInBytes)

  Convert and prune sparse CSR matrix into a sparse CSR matrix.

  `hipsparseXpruneCsr2csr_bufferSizeExt` returns the size of the temporary buffer that is required by hipsparseXpruneCsr2csrNnz() and hipsparseXpruneCsr2csr(). The temporary storage buffer must be allocated by the user.

  Parameters:

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

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - nnzA – [in] number of non-zeros in the sparse CSR matrix A.

    - descrA – [in] descriptor of the sparse CSR matrix A. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValA – [in] array of `nnzA` elements containing the values of the sparse CSR matrix A.

    - csrRowPtrA – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csrColIndA – [in] array of `nnzA` elements containing the column indices of the sparse CSR matrix A.

    - threshold – [in] pointer to the non-negative pruning threshold which can exist in either host or device memory.

    - descrC – [in] descriptor of the sparse CSR matrix C. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValC – [in] array of `nnzC` elements containing the values of the sparse CSR matrix C.

    - csrRowPtrC – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix C.

    - csrColIndC – [in] array of `nnzC` elements containing the column indices of the sparse CSR matrix C.

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseSpruneCsr2csrNnz(), hipsparseDpruneCsr2csrNnz(), hipsparseSpruneCsr2csr(), and hipsparseDpruneCsr2csr().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle` or `pBufferSizeInBytes` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXpruneCsr2csrNnz()

hipsparseStatus_t hipsparseSpruneCsr2csrNnz(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const float *csrValA, const int *csrRowPtrA, const int *csrColIndA, const float *threshold, const hipsparseMatDescr_t descrC, int *csrRowPtrC, int *nnzTotalDevHostPtr, void *buffer)

hipsparseStatus_t hipsparseDpruneCsr2csrNnz(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const double *csrValA, const int *csrRowPtrA, const int *csrColIndA, const double *threshold, const hipsparseMatDescr_t descrC, int *csrRowPtrC, int *nnzTotalDevHostPtr, void *buffer)

  Convert and prune sparse CSR matrix into a sparse CSR matrix.

  `hipsparseXpruneCsr2csrNnz` computes the number of nonzero elements per row and the total number of nonzero elements in a sparse CSR matrix once elements less than the threshold are pruned from the matrix.

  Note

  The routine does support asynchronous execution if the pointer mode is set to device.

  Parameters:

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

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - nnzA – [in] number of non-zeros in the sparse CSR matrix A.

    - descrA – [in] descriptor of the sparse CSR matrix A. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValA – [in] array of `nnzA` elements containing the values of the sparse CSR matrix A.

    - csrRowPtrA – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csrColIndA – [in] array of `nnzA` elements containing the column indices of the sparse CSR matrix A.

    - threshold – [in] pointer to the non-negative pruning threshold which can exist in either host or device memory.

    - descrC – [in] descriptor of the sparse CSR matrix C. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrRowPtrC – [out] array of `m+1` elements that point to the start of every row of the sparse CSR matrix C.

    - nnzTotalDevHostPtr – [out] total number of nonzero elements in device or host memory.

    - buffer – [out] buffer allocated by the user whose size is determined by calling hipsparseXpruneCsr2csr_bufferSize().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnzA`, `threshold`, `descrA`, `descrC`, `csrValA`, `csrRowPtrA`, `csrColIndA`, `csrRowPtrC`, `nnzTotalDevHostPtr` or `buffer` pointer is invalid.

## hipsparseXpruneCsr2csr()

hipsparseStatus_t hipsparseSpruneCsr2csr(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const float *csrValA, const int *csrRowPtrA, const int *csrColIndA, const float *threshold, const hipsparseMatDescr_t descrC, float *csrValC, const int *csrRowPtrC, int *csrColIndC, void *buffer)

hipsparseStatus_t hipsparseDpruneCsr2csr(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const double *csrValA, const int *csrRowPtrA, const int *csrColIndA, const double *threshold, const hipsparseMatDescr_t descrC, double *csrValC, const int *csrRowPtrC, int *csrColIndC, void *buffer)

  Convert and prune sparse CSR matrix into a sparse CSR matrix.

  This function converts the sparse CSR matrix A into a sparse CSR matrix C by pruning values in A that are less than the threshold. All the parameters are assumed to have been pre-allocated by the user. The user first calls hipsparseXpruneCsr2csr_bufferSize() to determine the size of the buffer used by hipsparseXpruneCsr2csrNnz() and `hipsparseXpruneCsr2csr()` which the user then allocates. The user then allocates `csrRowPtrC` to have `m+1` elements and then calls hipsparseXpruneCsr2csrNnz() which fills in the `csrRowPtrC` array stores then number of elements that are larger than the pruning `threshold` in `nnzTotalDevHostPtr`. The user then calls `hipsparseXpruneCsr2csr()` to complete the conversion. It is executed asynchronously with respect to the host and may return control to the application on the host before the entire result is ready.

  Parameters:

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

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - nnzA – [in] number of non-zeros in the sparse CSR matrix A.

    - descrA – [in] descriptor of the sparse CSR matrix A. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValA – [in] array of `nnzA` elements containing the values of the sparse CSR matrix A.

    - csrRowPtrA – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csrColIndA – [in] array of `nnzA` elements containing the column indices of the sparse CSR matrix A.

    - threshold – [in] pointer to the non-negative pruning threshold which can exist in either host or device memory.

    - descrC – [in] descriptor of the sparse CSR matrix C. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValC – [out] array of `nnzC` elements containing the values of the sparse CSR matrix C.

    - csrRowPtrC – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix C.

    - csrColIndC – [out] array of `nnzC` elements containing the column indices of the sparse CSR matrix C.

    - buffer – [in] buffer allocated by the user whose size is determined by calling hipsparseXpruneCsr2csr_bufferSize().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnzA`, `threshold`, `descrA`, `descrC`, `csrValA`, `csrRowPtrA`, `csrcolindA`, `csrvalC`, `csrrowptrC`, `csrcolIndC` or `buffer` pointer is invalid.

## hipsparseXpruneCsr2csrByPercentage_bufferSize()

hipsparseStatus_t hipsparseSpruneCsr2csrByPercentage_bufferSize(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const float *csrValA, const int *csrRowPtrA, const int *csrColIndA, float percentage, const hipsparseMatDescr_t descrC, const float *csrValC, const int *csrRowPtrC, const int *csrColIndC, pruneInfo_t info, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseDpruneCsr2csrByPercentage_bufferSize(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const double *csrValA, const int *csrRowPtrA, const int *csrColIndA, double percentage, const hipsparseMatDescr_t descrC, const double *csrValC, const int *csrRowPtrC, const int *csrColIndC, pruneInfo_t info, size_t *pBufferSizeInBytes)

  Convert and prune by percentage a sparse CSR matrix into a sparse CSR matrix.

  `hipsparseXpruneCsr2csrByPercentage_bufferSize` returns the size of the temporary buffer that is required by hipsparseXpruneCsr2csrNnzByPercentage(). The temporary storage buffer must be allocated by the user.

  Parameters:

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

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - nnzA – [in] number of non-zeros in the sparse CSR matrix A.

    - descrA – [in] descriptor of the sparse CSR matrix A. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValA – [in] array of `nnzA` elements containing the values of the sparse CSR matrix A.

    - csrRowPtrA – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csrColIndA – [in] array of `nnzA` elements containing the column indices of the sparse CSR matrix A.

    - percentage – [in] `percentage>=0` and `percentage<=100`.

    - descrC – [in] descriptor of the sparse CSR matrix C. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValC – [in] array of `nnzC` elements containing the values of the sparse CSR matrix C.

    - csrRowPtrC – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix C.

    - csrColIndC – [in] array of `nnzC` elements containing the column indices of the sparse CSR matrix C.

    - info – [in] prune info structure.

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseSpruneCsr2csrNnzByPercentage(), hipsparseDpruneCsr2csrNnzByPercentage(), hipsparseSpruneCsr2csrByPercentage(), and hipsparseDpruneCsr2csrByPercentage().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle` or `pBufferSizeInBytes` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXpruneCsr2csrByPercentage_bufferSizeExt()

hipsparseStatus_t hipsparseSpruneCsr2csrByPercentage_bufferSizeExt(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const float *csrValA, const int *csrRowPtrA, const int *csrColIndA, float percentage, const hipsparseMatDescr_t descrC, const float *csrValC, const int *csrRowPtrC, const int *csrColIndC, pruneInfo_t info, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseDpruneCsr2csrByPercentage_bufferSizeExt(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const double *csrValA, const int *csrRowPtrA, const int *csrColIndA, double percentage, const hipsparseMatDescr_t descrC, const double *csrValC, const int *csrRowPtrC, const int *csrColIndC, pruneInfo_t info, size_t *pBufferSizeInBytes)

  Convert and prune by percentage a sparse CSR matrix into a sparse CSR matrix.

  `hipsparseXpruneCsr2csrByPercentage_bufferSizeExt` returns the size of the temporary buffer that is required by hipsparseXpruneCsr2csrNnzByPercentage(). The temporary storage buffer must be allocated by the user.

  Parameters:

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

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - nnzA – [in] number of non-zeros in the sparse CSR matrix A.

    - descrA – [in] descriptor of the sparse CSR matrix A. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValA – [in] array of `nnzA` elements containing the values of the sparse CSR matrix A.

    - csrRowPtrA – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csrColIndA – [in] array of `nnzA` elements containing the column indices of the sparse CSR matrix A.

    - percentage – [in] `percentage>=0` and `percentage<=100`.

    - descrC – [in] descriptor of the sparse CSR matrix C. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValC – [in] array of `nnzC` elements containing the values of the sparse CSR matrix C.

    - csrRowPtrC – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix C.

    - csrColIndC – [in] array of `nnzC` elements containing the column indices of the sparse CSR matrix C.

    - info – [in] prune info structure.

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseSpruneCsr2csrNnzByPercentage(), hipsparseDpruneCsr2csrNnzByPercentage(), hipsparseSpruneCsr2csrByPercentage(), and hipsparseDpruneCsr2csrByPercentage().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle` or `pBufferSizeInBytes` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXpruneCsr2csrNnzByPercentage()

hipsparseStatus_t hipsparseSpruneCsr2csrNnzByPercentage(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const float *csrValA, const int *csrRowPtrA, const int *csrColIndA, float percentage, const hipsparseMatDescr_t descrC, int *csrRowPtrC, int *nnzTotalDevHostPtr, pruneInfo_t info, void *buffer)

hipsparseStatus_t hipsparseDpruneCsr2csrNnzByPercentage(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const double *csrValA, const int *csrRowPtrA, const int *csrColIndA, double percentage, const hipsparseMatDescr_t descrC, int *csrRowPtrC, int *nnzTotalDevHostPtr, pruneInfo_t info, void *buffer)

  Convert and prune by percentage a sparse CSR matrix into a sparse CSR matrix.

  `hipsparseXpruneCsr2csrNnzByPercentage` computes the number of nonzero elements per row and the total number of nonzero elements in a sparse CSR matrix once elements less than the threshold are pruned from the matrix.

  Note

  The routine does support asynchronous execution if the pointer mode is set to device.

  Parameters:

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

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - nnzA – [in] number of non-zeros in the sparse CSR matrix A.

    - descrA – [in] descriptor of the sparse CSR matrix A. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValA – [in] array of `nnzA` elements containing the values of the sparse CSR matrix A.

    - csrRowPtrA – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csrColIndA – [in] array of `nnzA` elements containing the column indices of the sparse CSR matrix A.

    - percentage – [in] `percentage>=0` and `percentage<=100`.

    - descrC – [in] descriptor of the sparse CSR matrix C. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrRowPtrC – [out] array of `m+1` elements that point to the start of every row of the sparse CSR matrix C.

    - nnzTotalDevHostPtr – [out] total number of nonzero elements in device or host memory.

    - info – [in] prune info structure.

    - buffer – [out] buffer allocated by the user whose size is determined by calling hipsparseXpruneCsr2csrByPercentage_bufferSize().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnzA`, `percentage`, `descrA`, `descrC`, `info`, `csrValA`, `csrRowPtrA`, `csrColIndA`, `csrRowPtrC`, `nnzTotalDevHostPtr` or `buffer` pointer is invalid.

## hipsparseXpruneCsr2csrByPercentage()

hipsparseStatus_t hipsparseSpruneCsr2csrByPercentage(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const float *csrValA, const int *csrRowPtrA, const int *csrColIndA, float percentage, const hipsparseMatDescr_t descrC, float *csrValC, const int *csrRowPtrC, int *csrColIndC, pruneInfo_t info, void *buffer)

hipsparseStatus_t hipsparseDpruneCsr2csrByPercentage(hipsparseHandle_t handle, int m, int n, int nnzA, const hipsparseMatDescr_t descrA, const double *csrValA, const int *csrRowPtrA, const int *csrColIndA, double percentage, const hipsparseMatDescr_t descrC, double *csrValC, const int *csrRowPtrC, int *csrColIndC, pruneInfo_t info, void *buffer)

  Convert and prune by percentage a sparse CSR matrix into a sparse CSR matrix.

  This function converts the sparse CSR matrix A into a sparse CSR matrix C by pruning values in A that are less than the threshold. All the parameters are assumed to have been pre-allocated by the user. The user first calls hipsparseXpruneCsr2csr_bufferSize() to determine the size of the buffer used by hipsparseXpruneCsr2csrNnz() and `hipsparseXpruneCsr2csr()` which the user then allocates. The user then allocates `csrRowPtrC` to have `m+1` elements and then calls hipsparseXpruneCsr2csrNnz() which fills in the `csrRowPtrC` array stores then number of elements that are larger than the pruning `threshold` in `nnzTotalDevHostPtr`. The user then calls `hipsparseXpruneCsr2csr()` to complete the conversion. It is executed asynchronously with respect to the host and may return control to the application on the host before the entire result is ready.

  Parameters:

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

    - m – [in] number of rows in the sparse CSR matrix.

    - n – [in] number of columns in the sparse CSR matrix.

    - nnzA – [in] number of non-zeros in the sparse CSR matrix A.

    - descrA – [in] descriptor of the sparse CSR matrix A. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValA – [in] array of `nnzA` elements containing the values of the sparse CSR matrix A.

    - csrRowPtrA – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix A.

    - csrColIndA – [in] array of `nnzA` elements containing the column indices of the sparse CSR matrix A.

    - percentage – [in] `percentage>=0` and `percentage<=100`.

    - descrC – [in] descriptor of the sparse CSR matrix C. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrValC – [out] array of `nnz_C` elements containing the values of the sparse CSR matrix C.

    - csrRowPtrC – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix C.

    - csrColIndC – [out] array of `nnz_C` elements containing the column indices of the sparse CSR matrix C.

    - info – [in] prune info structure.

    - buffer – [in] buffer allocated by the user whose size is determined by calling hipsparseXpruneCsr2csrByPercentage_bufferSize().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnzA`, `percentage`, `descrA`, `descrC`, `info`, `csrValA`, `csrRowPtrA`, `csrColIndA`, `csrValC`, `csrRowPtrC`, `csrColIndC` or `buffer` pointer is invalid.

## hipsparseXhyb2csr()

hipsparseStatus_t hipsparseShyb2csr(hipsparseHandle_t handle, const hipsparseMatDescr_t descrA, const hipsparseHybMat_t hybA, float *csrSortedValA, int *csrSortedRowPtrA, int *csrSortedColIndA)

hipsparseStatus_t hipsparseDhyb2csr(hipsparseHandle_t handle, const hipsparseMatDescr_t descrA, const hipsparseHybMat_t hybA, double *csrSortedValA, int *csrSortedRowPtrA, int *csrSortedColIndA)

hipsparseStatus_t hipsparseChyb2csr(hipsparseHandle_t handle, const hipsparseMatDescr_t descrA, const hipsparseHybMat_t hybA, hipComplex *csrSortedValA, int *csrSortedRowPtrA, int *csrSortedColIndA)

hipsparseStatus_t hipsparseZhyb2csr(hipsparseHandle_t handle, const hipsparseMatDescr_t descrA, const hipsparseHybMat_t hybA, hipDoubleComplex *csrSortedValA, int *csrSortedRowPtrA, int *csrSortedColIndA)

  Convert a sparse HYB matrix into a sparse CSR matrix.

  `hipsparseXhyb2csr` converts a HYB matrix into a CSR matrix.

  Note

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

  Parameters:

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

    - descrA – [in] descriptor of the sparse HYB matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - hybA – [in] sparse matrix in HYB format.

    - csrSortedValA – [out] array containing the values of the sparse CSR matrix.

    - csrSortedRowPtrA – [out] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csrSortedColIndA – [out] array containing the column indices of the sparse CSR matrix.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `descrA`, `hybA`, `csrSortedValA`, `csrSortedRowPtrA` or `csrSortedColIndA` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

    - HIPSPARSE_STATUS_NOT_SUPPORTED – hipsparseMatrixType_t != HIPSPARSE_MATRIX_TYPE_GENERAL.

## hipsparseXcoo2csr()

hipsparseStatus_t hipsparseXcoo2csr(hipsparseHandle_t handle, const int *cooRowInd, int nnz, int m, int *csrRowPtr, hipsparseIndexBase_t idxBase)

  Convert a sparse COO matrix into a sparse CSR matrix.

  `hipsparseXcoo2csr` converts the COO array containing the row indices into a CSR array of row offsets, that point to the start of every row. It is assumed that the COO row index array is sorted and that all arrays have been allocated prior to calling hipsparseXcoo2csr.

  For example, given the COO row indices array:

  \[ \begin{align} \text{cooRowInd} &= \begin{bmatrix} 0 & 0 & 1 & 2 & 2 & 4 & 4 & 4 \end{bmatrix} \end{align} \]

  the resulting CSR row pointer array after calling `hipsparseXcoo2csr` is:

  \[ \begin{align} \text{csrRowPtr} &= \begin{bmatrix} 0 & 2 & 3 & 5 & 8 \end{bmatrix} \end{align} \]

  Example

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

        // Sparse matrix in COO format
        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        int hcooRowInd[8] = {0, 0, 0, 1, 1, 2, 2, 2};
        int hcooColInd[8] = {0, 1, 3, 1, 2, 0, 3, 4};
        float hcooVal[8]   = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f};

        int m         = 3;
        int n         = 5;
        int nnz       = 8;
        hipsparseIndexBase_t base = HIPSPARSE_INDEX_BASE_ZERO;

        int* dcooRowInd = nullptr;
        int* dcooColInd = nullptr;
        hipMalloc((void**)&dcooRowInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcooColInd, sizeof(int) * nnz);

        hipMemcpy(dcooRowInd, hcooRowInd, sizeof(int) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dcooColInd, hcooColInd, sizeof(int) * nnz, hipMemcpyHostToDevice);

        int* dcsrRowPtr = nullptr;
        hipMalloc((void**)&dcsrRowPtr, sizeof(int) * (m + 1));

        hipsparseXcoo2csr(handle, dcooRowInd, nnz, m, dcsrRowPtr, base);

        hipFree(dcooRowInd);
        hipFree(dcooColInd);

        hipFree(dcsrRowPtr);

        hipsparseDestroy(handle);

  Note

  It can also be used, to convert a COO array containing the column indices into a CSC array of column offsets, that point to the start of every column. Then, it is assumed that the COO column index array is sorted, instead.

  Note

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

  Parameters:

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

    - cooRowInd – [in] array of `nnz` elements containing the row indices of the sparse COO matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - m – [in] number of rows of the sparse CSR matrix.

    - csrRowPtr – [out] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - idxBase – [in] HIPSPARSE_INDEX_BASE_ZERO or HIPSPARSE_INDEX_BASE_ONE.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `nnz`, `cooRowInd` or `csrRowPtr` pointer is invalid.

## hipsparseCreateIdentityPermutation()

hipsparseStatus_t hipsparseCreateIdentityPermutation(hipsparseHandle_t handle, int n, int *p)

  Create the identity map.

  `hipsparseCreateIdentityPermutation` stores the identity map in `p`, such that \(p = 0:1:(n-1)\).

      for(i = 0; i < n; ++i)
      {
          p[i] = i;
      }

  Example

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

        int n = 10;

        int* dperm = nullptr;
        hipMalloc((void**)&dperm, sizeof(int) * n);

        hipsparseCreateIdentityPermutation(handle, n, dperm);

        hipsparseDestroy(handle);

  Note

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

  Parameters:

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

    - n – [in] size of the map `p`.

    - p – [out] array of `n` integers containing the map.

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `n` or `p` pointer is invalid.

## hipsparseXcsrsort_bufferSizeExt()

hipsparseStatus_t hipsparseXcsrsort_bufferSizeExt(hipsparseHandle_t handle, int m, int n, int nnz, const int *csrRowPtr, const int *csrColInd, size_t *pBufferSizeInBytes)

  Sort a sparse CSR matrix.

  `hipsparseXcsrsort_bufferSizeExt` returns the size of the temporary storage buffer in bytes required by hipsparseXcsrsort(). The temporary storage buffer must be allocated by the user.

  Parameters:

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

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - csrRowPtr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csrColInd – [in] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseXcsrsort().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnz`, `csrRowPtr`, `csrColInd` or `pBufferSizeInBytes` pointer is invalid.

## hipsparseXcsrsort()

hipsparseStatus_t hipsparseXcsrsort(hipsparseHandle_t handle, int m, int n, int nnz, const hipsparseMatDescr_t descrA, const int *csrRowPtr, int *csrColInd, int *P, void *pBuffer)

  Sort a sparse CSR matrix.

  `hipsparseXcsrsort` sorts a matrix in CSR format. The sorted permutation vector `P` can be used to obtain sorted `csrVal` array. In this case, `P` must be initialized as the identity permutation, see hipsparseCreateIdentityPermutation(). To apply the permutation vector to the CSR values, see hipsparse hipsparseXgthr().

  `hipsparseXcsrsort` requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by hipsparseXcsrsort_bufferSizeExt().

  Example

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

        hipsparseMatDescr_t descr;
        hipsparseCreateMatDescr(&descr);

        // Sparse matrix in CSR format (columns unsorted)
        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        int hcsrRowPtr[4] = {0, 3, 5, 8};
        int hcsrColInd[8] = {3, 1, 0, 2, 1, 0, 4, 3};
        float hcsrVal[8]  = {3.0f, 2.0f, 1.0f, 5.0f, 4.0f, 6.0f, 8.0f, 7.0f};

        int m         = 3;
        int n         = 5;
        int nnz       = 8;

        int* dcsrRowPtr = nullptr;
        int* dcsrColInd = nullptr;
        float* dcsrVal = nullptr;
        hipMalloc((void**)&dcsrRowPtr, sizeof(int) * (m + 1));
        hipMalloc((void**)&dcsrColInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcsrVal, sizeof(float) * nnz);

        hipMemcpy(dcsrRowPtr, hcsrRowPtr, sizeof(int) * (m + 1), hipMemcpyHostToDevice);
        hipMemcpy(dcsrColInd, hcsrColInd, sizeof(int) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dcsrVal, hcsrVal, sizeof(float) * nnz, hipMemcpyHostToDevice);

        size_t bufferSize;
        hipsparseXcsrsort_bufferSizeExt(handle,
                                        m,
                                        n,
                                        nnz,
                                        dcsrRowPtr,
                                        dcsrColInd,
                                        &bufferSize);

        void* dbuffer = nullptr;
        hipMalloc((void**)&dbuffer, bufferSize);

        int* dperm = nullptr;
        hipMalloc((void**)&dperm, sizeof(int) * nnz);
        hipsparseCreateIdentityPermutation(handle, nnz, dperm);

        hipsparseXcsrsort(handle,
                          m,
                          n,
                          nnz,
                          descr,
                          dcsrRowPtr,
                          dcsrColInd,
                          dperm,
                          dbuffer);

        float* dcsrValSorted = nullptr;
        hipMalloc((void**)&dcsrValSorted, sizeof(float) * nnz);
        hipsparseSgthr(handle, nnz, dcsrVal, dcsrValSorted, dperm, HIPSPARSE_INDEX_BASE_ZERO);

        hipFree(dcsrRowPtr);
        hipFree(dcsrColInd);
        hipFree(dcsrVal);
        hipFree(dcsrValSorted);

        hipFree(dbuffer);
        hipFree(dperm);

        hipsparseDestroyMatDescr(descr);
        hipsparseDestroy(handle);

  Note

  `P` can be `NULL` if a sorted permutation vector is not required.

  Note

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

  Parameters:

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

    - m – [in] number of rows of the sparse CSR matrix.

    - n – [in] number of columns of the sparse CSR matrix.

    - nnz – [in] number of non-zero entries of the sparse CSR matrix.

    - descrA – [in] descriptor of the sparse CSR matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - csrRowPtr – [in] array of `m+1` elements that point to the start of every row of the sparse CSR matrix.

    - csrColInd – [inout] array of `nnz` elements containing the column indices of the sparse CSR matrix.

    - P – [inout] array of `nnz` integers containing the unsorted map indices, can be `NULL`.

    - pBuffer – [in] temporary storage buffer allocated by the user, size is returned by hipsparseXcsrsort_bufferSizeExt().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnz`, `descrA`, `csrRowPtr`, `csrColInd` or `pBuffer` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

    - HIPSPARSE_STATUS_NOT_SUPPORTED – hipsparseMatrixType_t != HIPSPARSE_MATRIX_TYPE_GENERAL.

## hipsparseXcscsort_bufferSizeExt()

hipsparseStatus_t hipsparseXcscsort_bufferSizeExt(hipsparseHandle_t handle, int m, int n, int nnz, const int *cscColPtr, const int *cscRowInd, size_t *pBufferSizeInBytes)

  Sort a sparse CSC matrix.

  `hipsparseXcscsort_bufferSizeExt` returns the size of the temporary storage buffer in bytes required by hipsparseXcscsort(). The temporary storage buffer must be allocated by the user.

  Parameters:

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

    - m – [in] number of rows of the sparse CSC matrix.

    - n – [in] number of columns of the sparse CSC matrix.

    - nnz – [in] number of non-zero entries of the sparse CSC matrix.

    - cscColPtr – [in] array of `n+1` elements that point to the start of every column of the sparse CSC matrix.

    - cscRowInd – [in] array of `nnz` elements containing the row indices of the sparse CSC matrix.

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseXcscsort().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnz`, `cscColPtr`, `cscRowInd` or `pBufferSizeInBytes` pointer is invalid.

## hipsparseXcscsort()

hipsparseStatus_t hipsparseXcscsort(hipsparseHandle_t handle, int m, int n, int nnz, const hipsparseMatDescr_t descrA, const int *cscColPtr, int *cscRowInd, int *P, void *pBuffer)

  Sort a sparse CSC matrix.

  `hipsparseXcscsort` sorts a matrix in CSC format. The sorted permutation vector `P` can be used to obtain sorted `cscVal` array. In this case, `P` must be initialized as the identity permutation, see hipsparseCreateIdentityPermutation(). To apply the permutation vector to the CSC values, see hipsparse hipsparseXgthr().

  `hipsparseXcscsort` requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by hipsparseXcscsort_bufferSizeExt().

  Example

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

        hipsparseMatDescr_t descr;
        hipsparseCreateMatDescr(&descr);

        // Sparse matrix in CSC format (unsorted row indices)
        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        int hcscRowInd[8] = {2, 0, 1, 0, 1, 2, 0, 2};
        int hcscColPtr[6] = {0, 2, 4, 5, 7, 8};
        float hcscVal[8]  = {6.0f, 1.0f, 4.0f, 2.0f, 5.0f, 7.0f, 3.0f, 8.0f};

        int m         = 3;
        int n         = 5;
        int nnz       = 8;

        int* dcscRowInd = nullptr;
        int* dcscColPtr = nullptr;
        float* dcscVal = nullptr;
        hipMalloc((void**)&dcscRowInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcscColPtr, sizeof(int) * (n + 1));
        hipMalloc((void**)&dcscVal, sizeof(float) * nnz);

        hipMemcpy(dcscRowInd, hcscRowInd, sizeof(int) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dcscColPtr, hcscColPtr, sizeof(int) * (n + 1), hipMemcpyHostToDevice);
        hipMemcpy(dcscVal, hcscVal, sizeof(float) * nnz, hipMemcpyHostToDevice);

        size_t bufferSize;
        hipsparseXcscsort_bufferSizeExt(handle,
                                        m,
                                        n,
                                        nnz,
                                        dcscColPtr,
                                        dcscRowInd,
                                        &bufferSize);

        void* dbuffer = nullptr;
        hipMalloc((void**)&dbuffer, bufferSize);

        int* dperm = nullptr;
        hipMalloc((void**)&dperm, sizeof(int) * nnz);
        hipsparseCreateIdentityPermutation(handle, nnz, dperm);

        hipsparseXcscsort(handle,
                          m,
                          n,
                          nnz,
                          descr,
                          dcscColPtr,
                          dcscRowInd,
                          dperm,
                          dbuffer);

        float* dcscValSorted = nullptr;
        hipMalloc((void**)&dcscValSorted, sizeof(float) * nnz);
        hipsparseSgthr(handle, nnz, dcscVal, dcscValSorted, dperm, HIPSPARSE_INDEX_BASE_ZERO);

        hipFree(dcscRowInd);
        hipFree(dcscColPtr);
        hipFree(dcscVal);
        hipFree(dcscValSorted);

        hipFree(dbuffer);
        hipFree(dperm);

        hipsparseDestroyMatDescr(descr);
        hipsparseDestroy(handle);

  Note

  `P` can be `NULL` if a sorted permutation vector is not required.

  Note

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

  Parameters:

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

    - m – [in] number of rows of the sparse CSC matrix.

    - n – [in] number of columns of the sparse CSC matrix.

    - nnz – [in] number of non-zero entries of the sparse CSC matrix.

    - descrA – [in] descriptor of the sparse CSC matrix. Currently, only HIPSPARSE_MATRIX_TYPE_GENERAL is supported.

    - cscColPtr – [in] array of `n+1` elements that point to the start of every column of the sparse CSC matrix.

    - cscRowInd – [inout] array of `nnz` elements containing the row indices of the sparse CSC matrix.

    - P – [inout] array of `nnz` integers containing the unsorted map indices, can be `NULL`.

    - pBuffer – [in] temporary storage buffer allocated by the user, size is returned by hipsparseXcscsort_bufferSizeExt().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnz`, `descrA`, `cscColPtr`, `cscRowInd` or `pBuffer` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

    - HIPSPARSE_STATUS_NOT_SUPPORTED – hipsparseMatrixType_t != HIPSPARSE_MATRIX_TYPE_GENERAL.

## hipsparseXcoosort_bufferSizeExt()

hipsparseStatus_t hipsparseXcoosort_bufferSizeExt(hipsparseHandle_t handle, int m, int n, int nnz, const int *cooRows, const int *cooCols, size_t *pBufferSizeInBytes)

  Sort a sparse COO matrix.

  `hipsparseXcoosort_bufferSizeExt` returns the size of the temporary storage buffer in bytes required by hipsparseXcoosortByRow() and hipsparseXcoosortByColumn(). The temporary storage buffer must be allocated by the user.

  Parameters:

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

    - m – [in] number of rows of the sparse COO matrix.

    - n – [in] number of columns of the sparse COO matrix.

    - nnz – [in] number of non-zero entries of the sparse COO matrix.

    - cooRows – [in] array of `nnz` elements containing the row indices of the sparse COO matrix.

    - cooCols – [in] array of `nnz` elements containing the column indices of the sparse COO matrix.

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseXcoosortByRow() and hipsparseXcoosortByColumn().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnz`, `cooRows`, `cooCols` or `pBufferSizeInBytes` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXcoosortByRow()

hipsparseStatus_t hipsparseXcoosortByRow(hipsparseHandle_t handle, int m, int n, int nnz, int *cooRows, int *cooCols, int *P, void *pBuffer)

  Sort a sparse COO matrix by row.

  `hipsparseXcoosortByRow` sorts a matrix in COO format by row. The sorted permutation vector `P` can be used to obtain sorted `cooVal` array. In this case, `P` must be initialized as the identity permutation, see hipsparseCreateIdentityPermutation(). To apply the permutation vector to the COO values, see hipsparse hipsparseXgthr().

  `hipsparseXcoosortByRow` requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by hipsparseXcoosort_bufferSizeExt().

  Example

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

        // Sparse matrix in COO format (with unsorted row indices)
        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        int hcooRowInd[8] = {0, 2, 0, 1, 1, 0, 2, 2};
        int hcooColInd[8] = {0, 0, 1, 1, 2, 3, 3, 4};
        float hcooVal[8]   = {1.0f, 6.0f, 2.0f, 4.0f, 5.0f, 3.0f, 7.0f, 8.0f};

        int m         = 3;
        int n         = 5;
        int nnz       = 8;
        hipsparseIndexBase_t base = HIPSPARSE_INDEX_BASE_ZERO;

        int* dcooRowInd = nullptr;
        int* dcooColInd = nullptr;
        float* dcooVal = nullptr;
        hipMalloc((void**)&dcooRowInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcooColInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcooVal, sizeof(float) * nnz);

        hipMemcpy(dcooRowInd, hcooRowInd, sizeof(int) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dcooColInd, hcooColInd, sizeof(int) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dcooVal, hcooVal, sizeof(float) * nnz, hipMemcpyHostToDevice);

        size_t bufferSize;
        hipsparseXcoosort_bufferSizeExt(handle, m, n, nnz, dcooRowInd, dcooColInd, &bufferSize);

        void* dbuffer = nullptr;
        hipMalloc((void**)&dbuffer, bufferSize);

        int* dperm = nullptr;
        hipMalloc((void**)&dperm, sizeof(int) * nnz);
        hipsparseCreateIdentityPermutation(handle, nnz, dperm);

        hipsparseXcoosortByRow(handle, m, n, nnz, dcooRowInd, dcooColInd, dperm, dbuffer);

        float* dcooValSorted = nullptr;
        hipMalloc((void**)&dcooValSorted, sizeof(float) * nnz);
        hipsparseSgthr(handle, nnz, dcooVal, dcooValSorted, dperm, base);

        hipFree(dcooRowInd);
        hipFree(dcooColInd);
        hipFree(dcooVal);
        hipFree(dcooValSorted);
        hipFree(dperm);

        hipFree(dbuffer);

        hipsparseDestroy(handle);

  Note

  `P` can be `NULL` if a sorted permutation vector is not required.

  Note

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

  Parameters:

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

    - m – [in] number of rows of the sparse COO matrix.

    - n – [in] number of columns of the sparse COO matrix.

    - nnz – [in] number of non-zero entries of the sparse COO matrix.

    - cooRows – [inout] array of `nnz` elements containing the row indices of the sparse COO matrix.

    - cooCols – [inout] array of `nnz` elements containing the column indices of the sparse COO matrix.

    - P – [inout] array of `nnz` integers containing the unsorted map indices, can be `NULL`.

    - pBuffer – [in] temporary storage buffer allocated by the user, size is returned by hipsparseXcoosort_bufferSizeExt().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnz`, `cooRows`, `cooCols` or `pBuffer` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXcoosortByColumn()

hipsparseStatus_t hipsparseXcoosortByColumn(hipsparseHandle_t handle, int m, int n, int nnz, int *cooRows, int *cooCols, int *P, void *pBuffer)

  Sort a sparse COO matrix by column.

  `hipsparseXcoosortByColumn` sorts a matrix in COO format by column. The sorted permutation vector `P` can be used to obtain sorted `cooVal` array. In this case, `P` must be initialized as the identity permutation, see hipsparseCreateIdentityPermutation(). To apply the permutation vector to the COO values, see hipsparse hipsparseXgthr().

  `hipsparseXcoosortByColumn` requires extra temporary storage buffer that has to be allocated by the user. Storage buffer size can be determined by hipsparseXcoosort_bufferSizeExt().

  Example

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

        // Sparse matrix in COO format (with unsorted column indices)
        //     1 2 0 3 0
        // A = 0 4 5 0 0
        //     6 0 0 7 8
        int hcooRowInd[8] = {0, 0, 0, 1, 1, 2, 2, 2};
        int hcooColInd[8] = {0, 1, 3, 1, 2, 0, 3, 4};
        float hcooVal[8]   = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f};

        int m         = 3;
        int n         = 5;
        int nnz       = 8;
        hipsparseIndexBase_t base = HIPSPARSE_INDEX_BASE_ZERO;

        int* dcooRowInd = nullptr;
        int* dcooColInd = nullptr;
        float* dcooVal = nullptr;
        hipMalloc((void**)&dcooRowInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcooColInd, sizeof(int) * nnz);
        hipMalloc((void**)&dcooVal, sizeof(float) * nnz);

        hipMemcpy(dcooRowInd, hcooRowInd, sizeof(int) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dcooColInd, hcooColInd, sizeof(int) * nnz, hipMemcpyHostToDevice);
        hipMemcpy(dcooVal, hcooVal, sizeof(float) * nnz, hipMemcpyHostToDevice);

        size_t bufferSize;
        hipsparseXcoosort_bufferSizeExt(handle, m, n, nnz, dcooRowInd, dcooColInd, &bufferSize);

        void* dbuffer = nullptr;
        hipMalloc((void**)&dbuffer, bufferSize);

        int* dperm = nullptr;
        hipMalloc((void**)&dperm, sizeof(int) * nnz);
        hipsparseCreateIdentityPermutation(handle, nnz, dperm);

        hipsparseXcoosortByColumn(handle, m, n, nnz, dcooRowInd, dcooColInd, dperm, dbuffer);

        float* dcooValSorted = nullptr;
        hipMalloc((void**)&dcooValSorted, sizeof(float) * nnz);
        hipsparseSgthr(handle, nnz, dcooVal, dcooValSorted, dperm, base);

        hipFree(dcooRowInd);
        hipFree(dcooColInd);
        hipFree(dcooVal);
        hipFree(dcooValSorted);
        hipFree(dperm);

        hipFree(dbuffer);

        hipsparseDestroy(handle);

  Note

  `P` can be `NULL` if a sorted permutation vector is not required.

  Note

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

  Parameters:

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

    - m – [in] number of rows of the sparse COO matrix.

    - n – [in] number of columns of the sparse COO matrix.

    - nnz – [in] number of non-zero entries of the sparse COO matrix.

    - cooRows – [inout] array of `nnz` elements containing the row indices of the sparse COO matrix.

    - cooCols – [inout] array of `nnz` elements containing the column indices of the sparse COO matrix.

    - P – [inout] array of `nnz` integers containing the unsorted map indices, can be `NULL`.

    - pBuffer – [in] temporary storage buffer allocated by the user, size is returned by hipsparseXcoosort_bufferSizeExt().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `m`, `n`, `nnz`, `cooRows`, `cooCols` or `pBuffer` pointer is invalid.

    - HIPSPARSE_STATUS_INTERNAL_ERROR – an internal error occurred.

## hipsparseXgebsr2gebsr_bufferSize()

hipsparseStatus_t hipsparseSgebsr2gebsr_bufferSize(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, int nnzb, const hipsparseMatDescr_t descrA, const float *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int rowBlockDimA, int colBlockDimA, int rowBlockDimC, int colBlockDimC, int *pBufferSizeInBytes)

hipsparseStatus_t hipsparseDgebsr2gebsr_bufferSize(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, int nnzb, const hipsparseMatDescr_t descrA, const double *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int rowBlockDimA, int colBlockDimA, int rowBlockDimC, int colBlockDimC, int *pBufferSizeInBytes)

hipsparseStatus_t hipsparseCgebsr2gebsr_bufferSize(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, int nnzb, const hipsparseMatDescr_t descrA, const hipComplex *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int rowBlockDimA, int colBlockDimA, int rowBlockDimC, int colBlockDimC, int *pBufferSizeInBytes)

hipsparseStatus_t hipsparseZgebsr2gebsr_bufferSize(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, int nnzb, const hipsparseMatDescr_t descrA, const hipDoubleComplex *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int rowBlockDimA, int colBlockDimA, int rowBlockDimC, int colBlockDimC, int *pBufferSizeInBytes)

  This function computes the the size of the user allocated temporary storage buffer used when converting a sparse GEBSR matrix to another sparse GEBSR matrix.

  `hipsparseXgebsr2gebsr_bufferSize` returns the size of the temporary storage buffer that is required by hipsparseXgebsr2gebsrNnz() and hipsparseXgebsr2gebsr(). The temporary storage buffer must be allocated by the user.

  Parameters:

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

    - dirA – [in] the storage format of the blocks, HIPSPARSE_DIRECTION_ROW or HIPSPARSE_DIRECTION_COLUMN

    - mb – [in] number of block rows of the general BSR sparse matrix \(A\).

    - nb – [in] number of block columns of the general BSR sparse matrix \(A\).

    - nnzb – [in] number of blocks in the general BSR sparse matrix \(A\).

    - descrA – [in] the descriptor of the general BSR sparse matrix \(A\), the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - bsrValA – [in] array of `nnzb*rowBlockDimA*colBlockDimA` containing the values of the sparse general BSR matrix \(A\).

    - bsrRowPtrA – [in] array of `mb+1` elements that point to the start of every block row of the sparse general BSR matrix \(A\).

    - bsrColIndA – [in] array of `nnzb` elements containing the block column indices of the sparse general BSR matrix \(A\).

    - rowBlockDimA – [in] row size of the blocks in the sparse general BSR matrix \(A\).

    - colBlockDimA – [in] column size of the blocks in the sparse general BSR matrix \(A\).

    - rowBlockDimC – [in] row size of the blocks in the sparse general BSR matrix \(C\).

    - colBlockDimC – [in] column size of the blocks in the sparse general BSR matrix \(C\).

    - pBufferSizeInBytes – [out] number of bytes of the temporary storage buffer required by hipsparseXgebsr2gebsrNnz(), hipsparseSgebsr2gebsr(), hipsparseDgebsr2gebsr(), hipsparseCgebsr2gebsr(), and hipsparseZgebsr2gebsr().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `mb`, `nb`, `nnzb`, `rowBlockDimA`, `colBlockDimA`, `rowBlockDimC`, `colBlockDimC`, `bsrRowPtrA`, `bsrColIndA`, `descrA` or `pBufferSizeInBytes` pointer is invalid.

## hipsparseXgebsr2gebsrNnz()

hipsparseStatus_t hipsparseXgebsr2gebsrNnz(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, int nnzb, const hipsparseMatDescr_t descrA, const int *bsrRowPtrA, const int *bsrColIndA, int rowBlockDimA, int colBlockDimA, const hipsparseMatDescr_t descrC, int *bsrRowPtrC, int rowBlockDimC, int colBlockDimC, int *nnzTotalDevHostPtr, void *buffer)

  This function is used when converting a GEBSR sparse matrix \(A\) to another GEBSR sparse matrix \(C\). Specifically, this function determines the number of non-zero blocks that will exist in \(C\) (stored using either a host or device pointer), and computes the row pointer array for \(C\).

  The routine does support asynchronous execution.

  Parameters:

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

    - dirA – [in] the storage format of the blocks, HIPSPARSE_DIRECTION_ROW or HIPSPARSE_DIRECTION_COLUMN

    - mb – [in] number of block rows of the general BSR sparse matrix \(A\).

    - nb – [in] number of block columns of the general BSR sparse matrix \(A\).

    - nnzb – [in] number of blocks in the general BSR sparse matrix \(A\).

    - descrA – [in] the descriptor of the general BSR sparse matrix \(A\), the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - bsrRowPtrA – [in] array of `mb+1` elements that point to the start of every block row of the sparse general BSR matrix \(A\).

    - bsrColIndA – [in] array of `nnzb` elements containing the block column indices of the sparse general BSR matrix `A`.

    - rowBlockDimA – [in] row size of the blocks in the sparse general BSR matrix \(A\).

    - colBlockDimA – [in] column size of the blocks in the sparse general BSR matrix \(A\).

    - descrC – [in] the descriptor of the general BSR sparse matrix \(C\), the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - bsrRowPtrC – [in] array of `mbC+1` elements that point to the start of every block row of the sparse general BSR matrix \(C\) where `mbC` = ( `m+rowBlockDimC-1` ) / `rowBlockDimC`.

    - rowBlockDimC – [in] row size of the blocks in the sparse general BSR matrix \(C\).

    - colBlockDimC – [in] column size of the blocks in the sparse general BSR matrix \(C\).

    - nnzTotalDevHostPtr – [out] total number of nonzero blocks in general BSR sparse matrix \(C\) stored using device or host memory.

    - buffer – [out] buffer allocated by the user whose size is determined by calling hipsparseXgebsr2gebsr_bufferSize().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `mb`, `nb`, `nnzb`, `rowBlockDimA`, `colBlockDimA`, `rowBlockDimC`, `colBlockDimC`, `bsrRowPtrA`, `bsrColIndA`, `bsrRowPtrC`, `descrA`, `descrC`, `buffer` pointer is invalid.

## hipsparseXgebsr2gebsr()

hipsparseStatus_t hipsparseSgebsr2gebsr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, int nnzb, const hipsparseMatDescr_t descrA, const float *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int rowBlockDimA, int colBlockDimA, const hipsparseMatDescr_t descrC, float *bsrValC, int *bsrRowPtrC, int *bsrColIndC, int rowBlockDimC, int colBlockDimC, void *buffer)

hipsparseStatus_t hipsparseDgebsr2gebsr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, int nnzb, const hipsparseMatDescr_t descrA, const double *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int rowBlockDimA, int colBlockDimA, const hipsparseMatDescr_t descrC, double *bsrValC, int *bsrRowPtrC, int *bsrColIndC, int rowBlockDimC, int colBlockDimC, void *buffer)

hipsparseStatus_t hipsparseCgebsr2gebsr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, int nnzb, const hipsparseMatDescr_t descrA, const hipComplex *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int rowBlockDimA, int colBlockDimA, const hipsparseMatDescr_t descrC, hipComplex *bsrValC, int *bsrRowPtrC, int *bsrColIndC, int rowBlockDimC, int colBlockDimC, void *buffer)

hipsparseStatus_t hipsparseZgebsr2gebsr(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nb, int nnzb, const hipsparseMatDescr_t descrA, const hipDoubleComplex *bsrValA, const int *bsrRowPtrA, const int *bsrColIndA, int rowBlockDimA, int colBlockDimA, const hipsparseMatDescr_t descrC, hipDoubleComplex *bsrValC, int *bsrRowPtrC, int *bsrColIndC, int rowBlockDimC, int colBlockDimC, void *buffer)

  This function converts the GEBSR sparse matrix \(A\) to another GEBSR sparse matrix \(C\).

  The conversion uses three steps. First, the user calls hipsparseXgebsr2gebsr_bufferSize() to determine the size of the required temporary storage buffer. The user then allocates this buffer. Secondly, the user then allocates `mbC+1` integers for the row pointer array for \(C\) where:

  \[\begin{split} \begin{align} \text{mbC} &= \text{(m - 1) / rowBlockDimC + 1} \\ \text{nbC} &= \text{(n - 1) / colBlockDimC + 1} \end{align} \end{split}\]
  The user then calls hipsparseXgebsr2gebsrNnz() to fill in the row pointer array for \(C\) ( `bsrRowPtrC` ) and determine the number of non-zero blocks that will exist in \(C\). Finally, the user allocates space for the column indices array of \(C\) to have `nnzbC` elements and space for the values array of \(C\) to have `nnzbC*rowBlockDimC*colBlockDimC` and then calls `hipsparseXgebsr2gebsr` to complete the conversion.

  It may be the case that `rowBlockDimC` does not divide evenly into `m` and/or `colBlockDim` does not divide evenly into `n`. In these cases, the GEBSR matrix is expanded in size in order to fit full GEBSR blocks. For example, if the original GEBSR matrix A (using `rowBlockDimA=2`, `colBlockDimA=3`) looks like:

  \[\begin{split} \left[ \begin{array}{c | c} \begin{array}{c c c} 1 & 0 & 0 \\ 3 & 4 & 0 \end{array} & \begin{array}{c c c} 2 & 0 & 0 \\ 4 & 5 & 6 \end{array} \\ \hline \begin{array}{c c c} 1 & 2 & 3 \\ 1 & 2 & 0 \end{array} & \begin{array}{c c c} 4 & 0 & 0 \\ 3 & 0 & 1 \end{array} \\ \end{array} \right] \end{split}\]

  then if we specify `rowBlockDimC=3` and `colBlockDimC=2`, our output GEBSR matrix C would be:

  \[\begin{split} \left[ \begin{array}{c | c | c} \begin{array}{c c} 1 & 0 \\ 3 & 4 \\ 1 & 2 \end{array} & \begin{array}{c c} 0 & 2 \\ 0 & 4 \\ 3 & 4 \end{array} & \begin{array}{c c} 0 & 0 \\ 5 & 6 \\ 0 & 0 \end{array} \\ \hline \begin{array}{c c} 1 & 2 \\ 0 & 0 \\ 0 & 0 \end{array} & \begin{array}{c c} 0 & 3 \\ 0 & 0 \\ 0 & 0 \end{array} & \begin{array}{c c} 0 & 1 \\ 0 & 0 \\ 0 & 0 \end{array} \\ \end{array} \right] \end{split}\]

  Example

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

        hipsparseMatDescr_t descrA;
        hipsparseCreateMatDescr(&descrA);

        hipsparseMatDescr_t descrC;
        hipsparseCreateMatDescr(&descrC);

        // Sparse matrix in BSR format
        //     1 2 | 0 3 | 0 0
        //     0 4 | 5 0 | 0 1
        // A = 6 0 | 0 7 | 8 0
        //     ---------------
        //     0 0 | 3 0 | 2 2
        //     1 0 | 0 0 | 4 3
        //     7 2 | 0 0 | 1 4
        int hbsrRowPtrA[3] = {0, 3, 6};
        int hbsrColIndA[6] = {0, 1, 2, 0, 1, 2};
        float hbsrValA[36]  = {1.0f, 2.0f, 0.0f, 4.0f, 6.0f, 0.0f,
                               0.0f, 3.0f, 5.0f, 0.0f, 0.0f, 7.0f,
                               0.0f, 0.0f, 0.0f, 1.0f, 8.0f, 0.0f,
                               0.0f, 0.0f, 1.0f, 0.0f, 7.0f, 2.0f,
                               3.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f,
                               2.0f, 2.0f, 4.0f, 3.0f, 1.0f, 4.0f};

        int m           = 6;
        int n           = 6;
        int rowBlockDimA = 3;
        int colBlockDimA = 2;
        int rowBlockDimC = 2;
        int colBlockDimC = 2;
        hipsparseDirection_t dirA = HIPSPARSE_DIRECTION_ROW;

        int mbA   = (m + rowBlockDimA - 1) / rowBlockDimA;
        int nbA   = (n + colBlockDimA - 1) / colBlockDimA;
        int nnzbA = 6;

        int mbC   = (m + rowBlockDimC - 1) / rowBlockDimC;
        int nbC   = (n + colBlockDimC - 1) / colBlockDimC;

        int* dbsrRowPtrA = nullptr;
        int* dbsrColIndA = nullptr;
        float* dbsrValA = nullptr;
        hipMalloc((void**)&dbsrRowPtrA, sizeof(int) * (mbA + 1));
        hipMalloc((void**)&dbsrColIndA, sizeof(int) * nnzbA);
        hipMalloc((void**)&dbsrValA, sizeof(float) * rowBlockDimA * colBlockDimA * nnzbA);

        hipMemcpy(dbsrRowPtrA, hbsrRowPtrA, sizeof(int) * (mbA + 1), hipMemcpyHostToDevice);
        hipMemcpy(dbsrColIndA, hbsrColIndA, sizeof(int) * nnzbA, hipMemcpyHostToDevice);
        hipMemcpy(dbsrValA, hbsrValA, sizeof(float) * rowBlockDimA * colBlockDimA * nnzbA, hipMemcpyHostToDevice);

        int* dbsrRowPtrC = nullptr;
        hipMalloc((void**)&dbsrRowPtrC, sizeof(int) * (mbC + 1));

        size_t bufferSize;
        hipsparseSgebsr2gebsr_bufferSize(handle,
                                         dirA,
                                         mbA,
                                         nbA,
                                         nnzbA,
                                         descrA,
                                         dbsrValA,
                                         dbsrRowPtrA,
                                         dbsrColIndA,
                                         rowBlockDimA,
                                         colBlockDimA,
                                         rowBlockDimC,
                                         colBlockDimC,
                                         &bufferSize);

        void* dbuffer = nullptr;
        hipMalloc((void**)&dbuffer, bufferSize);

        int nnzbC;
        hipsparseXgebsr2gebsrNnz(handle,
                                 dirA,
                                 mbA,
                                 nbA,
                                 nnzbA,
                                 descrA,
                                 dbsrRowPtrA,
                                 dbsrColIndA,
                                 rowBlockDimA,
                                 colBlockDimA,
                                 descrC,
                                 dbsrRowPtrC,
                                 rowBlockDimC,
                                 colBlockDimC,
                                 &nnzbC,
                                 dbuffer);

        hipDeviceSynchronize();

        int* dbsrColIndC = nullptr;
        float* dbsrValC = nullptr;
        hipMalloc((void**)&dbsrColIndC, sizeof(int) * nnzbC);
        hipMalloc((void**)&dbsrValC, sizeof(float) * rowBlockDimC * colBlockDimC * nnzbC);

        hipsparseSgebsr2gebsr(handle,
                              dirA,
                              mbA,
                              nbA,
                              nnzbA,
                              descrA,
                              dbsrValA,
                              dbsrRowPtrA,
                              dbsrColIndA,
                              rowBlockDimA,
                              colBlockDimA,
                              descrC,
                              dbsrValC,
                              dbsrRowPtrC,
                              dbsrColIndC,
                              rowBlockDimC,
                              colBlockDimC,
                              dbuffer);

        hipFree(dbsrRowPtrA);
        hipFree(dbsrColIndA);
        hipFree(dbsrValA);

        hipFree(dbsrRowPtrC);
        hipFree(dbsrColIndC);
        hipFree(dbsrValC);

        hipFree(dbuffer);

        hipsparseDestroyMatDescr(descrA);
        hipsparseDestroyMatDescr(descrC);
        hipsparseDestroy(handle);

  Parameters:

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

    - dirA – [in] the storage format of the blocks, HIPSPARSE_DIRECTION_ROW or HIPSPARSE_DIRECTION_COLUMN

    - mb – [in] number of block rows of the general BSR sparse matrix \(A\).

    - nb – [in] number of block columns of the general BSR sparse matrix \(A\).

    - nnzb – [in] number of blocks in the general BSR sparse matrix \(A\).

    - descrA – [in] the descriptor of the general BSR sparse matrix \(A\), the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - bsrValA – [in] array of `nnzb*rowBlockDimA*colBlockDimA` containing the values of the sparse general BSR matrix \(A\).

    - bsrRowPtrA – [in] array of `mb+1` elements that point to the start of every block row of the sparse general BSR matrix \(A\).

    - bsrColIndA – [in] array of `nnzb` elements containing the block column indices of the sparse general BSR matrix \(A\).

    - rowBlockDimA – [in] row size of the blocks in the sparse general BSR matrix \(A\).

    - colBlockDimA – [in] column size of the blocks in the sparse general BSR matrix \(A\).

    - descrC – [in] the descriptor of the general BSR sparse matrix \(C\), the supported matrix type is HIPSPARSE_MATRIX_TYPE_GENERAL and also any valid value of the hipsparseIndexBase_t.

    - bsrValC – [in] array of `nnzbC*rowBlockDimC*colBlockDimC` containing the values of the sparse general BSR matrix \(C\).

    - bsrRowPtrC – [in] array of `mbC+1` elements that point to the start of every block row of the sparse general BSR matrix \(C\).

    - bsrColIndC – [in] array of `nnzbC` elements containing the block column indices of the sparse general BSR matrix \(C\).

    - rowBlockDimC – [in] row size of the blocks in the sparse general BSR matrix \(C\).

    - colBlockDimC – [in] column size of the blocks in the sparse general BSR matrix \(C\).

    - buffer – [out] buffer allocated by the user whose size is determined by calling hipsparseXgebsr2gebsr_bufferSize().

  Return values:

    - HIPSPARSE_STATUS_SUCCESS – the operation completed successfully.

    - HIPSPARSE_STATUS_INVALID_VALUE – `handle`, `mb`, `nb`, `nnzb`, `rowBlockDimA`, `colBlockDimA`, `rowBlockDimC`, `colBlockDimC`, `bsrRowPtrA`, `bsrColIndA`, `bsrValA`, `bsrRowPtrC`, `bsrColIndC`, `bsrValC`, `descrA`, `descrC` or `buffer` pointer is invalid.

## hipsparseXcsru2csr_bufferSizeExt()

hipsparseStatus_t hipsparseScsru2csr_bufferSizeExt(hipsparseHandle_t handle, int m, int n, int nnz, float *csrVal, const int *csrRowPtr, int *csrColInd, csru2csrInfo_t info, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseDcsru2csr_bufferSizeExt(hipsparseHandle_t handle, int m, int n, int nnz, double *csrVal, const int *csrRowPtr, int *csrColInd, csru2csrInfo_t info, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseCcsru2csr_bufferSizeExt(hipsparseHandle_t handle, int m, int n, int nnz, hipComplex *csrVal, const int *csrRowPtr, int *csrColInd, csru2csrInfo_t info, size_t *pBufferSizeInBytes)

hipsparseStatus_t hipsparseZcsru2csr_bufferSizeExt(hipsparseHandle_t handle, int m, int n, int nnz, hipDoubleComplex *csrVal, const int *csrRowPtr, int *csrColInd, csru2csrInfo_t info, size_t *pBufferSizeInBytes)

  This function calculates the amount of temporary storage in bytes required for hipsparseXcsru2csr() and hipsparseXcsr2csru().

## hipsparseXcsru2csr()

hipsparseStatus_t hipsparseScsru2csr(hipsparseHandle_t handle, int m, int n, int nnz, const hipsparseMatDescr_t descrA, float *csrVal, const int *csrRowPtr, int *csrColInd, csru2csrInfo_t info, void *pBuffer)

hipsparseStatus_t hipsparseDcsru2csr(hipsparseHandle_t handle, int m, int n, int nnz, const hipsparseMatDescr_t descrA, double *csrVal, const int *csrRowPtr, int *csrColInd, csru2csrInfo_t info, void *pBuffer)

hipsparseStatus_t hipsparseCcsru2csr(hipsparseHandle_t handle, int m, int n, int nnz, const hipsparseMatDescr_t descrA, hipComplex *csrVal, const int *csrRowPtr, int *csrColInd, csru2csrInfo_t info, void *pBuffer)

hipsparseStatus_t hipsparseZcsru2csr(hipsparseHandle_t handle, int m, int n, int nnz, const hipsparseMatDescr_t descrA, hipDoubleComplex *csrVal, const int *csrRowPtr, int *csrColInd, csru2csrInfo_t info, void *pBuffer)

  This function converts unsorted CSR format to sorted CSR format. The required temporary storage has to be allocated by the user.

## hipsparseXcsr2csru()

hipsparseStatus_t hipsparseScsr2csru(hipsparseHandle_t handle, int m, int n, int nnz, const hipsparseMatDescr_t descrA, float *csrVal, const int *csrRowPtr, int *csrColInd, csru2csrInfo_t info, void *pBuffer)

hipsparseStatus_t hipsparseDcsr2csru(hipsparseHandle_t handle, int m, int n, int nnz, const hipsparseMatDescr_t descrA, double *csrVal, const int *csrRowPtr, int *csrColInd, csru2csrInfo_t info, void *pBuffer)

hipsparseStatus_t hipsparseCcsr2csru(hipsparseHandle_t handle, int m, int n, int nnz, const hipsparseMatDescr_t descrA, hipComplex *csrVal, const int *csrRowPtr, int *csrColInd, csru2csrInfo_t info, void *pBuffer)

hipsparseStatus_t hipsparseZcsr2csru(hipsparseHandle_t handle, int m, int n, int nnz, const hipsparseMatDescr_t descrA, hipDoubleComplex *csrVal, const int *csrRowPtr, int *csrColInd, csru2csrInfo_t info, void *pBuffer)

  This function converts sorted CSR format to unsorted CSR format. The required temporary storage has to be allocated by the user.