Sparse Conversion Functions

This module holds all sparse conversion routines.

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

rocsparse_csr2coo()

rocsparse_status rocsparse_csr2coo(rocsparse_handle handle, const rocsparse_int *csr_row_ptr, rocsparse_int nnz, rocsparse_int m, rocsparse_int *coo_row_ind, rocsparse_index_base idx_base)

Convert a sparse CSR matrix into a sparse COO matrix.

rocsparse_csr2coo converts the CSR array containing the row offsets, that point to the start of every row, into a COO array of row indices.

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

Example

This example converts a CSR matrix into a COO matrix.

//     1 2 0 3 0
// A = 0 4 5 0 0
//     6 0 0 7 8

rocsparse_int m   = 3;
rocsparse_int n   = 5;
rocsparse_int nnz = 8;

csr_row_ptr[m+1] = {0, 3, 5, 8};             // device memory
csr_col_ind[nnz] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory
csr_val[nnz]     = {1, 2, 3, 4, 5, 6, 7, 8}; // device memory

// Allocate COO matrix arrays
rocsparse_int* coo_row_ind;
rocsparse_int* coo_col_ind;
float* coo_val;

hipMalloc((void**)&coo_row_ind, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&coo_col_ind, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&coo_val, sizeof(float) * nnz);

// Convert the csr row offsets into coo row indices
rocsparse_csr2coo(handle,
                  csr_row_ptr,
                  nnz,
                  m,
                  coo_row_ind,
                  rocsparse_index_base_zero);

// Copy the column and value arrays
hipMemcpy(coo_col_ind,
          csr_col_ind,
          sizeof(rocsparse_int) * nnz,
          hipMemcpyDeviceToDevice);

hipMemcpy(coo_val,
          csr_val,
          sizeof(float) * nnz,
          hipMemcpyDeviceToDevice);

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• csr_row_ptr – [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.

• coo_row_ind – [out] array of nnz elements containing the row indices of the sparse COO matrix.

• idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or nnz is invalid.

• rocsparse_status_invalid_pointer – csr_row_ptr or coo_row_ind pointer is invalid.

• rocsparse_status_arch_mismatch – the device is not supported.

rocsparse_coo2csr()

rocsparse_status rocsparse_coo2csr(rocsparse_handle handle, const rocsparse_int *coo_row_ind, rocsparse_int nnz, rocsparse_int m, rocsparse_int *csr_row_ptr, rocsparse_index_base idx_base)

Convert a sparse COO matrix into a sparse CSR matrix.

rocsparse_coo2csr 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.

rocsparse_coo2csr 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. In this case it is assumed that the COO column index array is sorted instead.

Example

This example converts a COO matrix into a CSR matrix.

//     1 2 0 3 0
// A = 0 4 5 0 0
//     6 0 0 7 8

rocsparse_int m   = 3;
rocsparse_int n   = 5;
rocsparse_int nnz = 8;

coo_row_ind[nnz] = {0, 0, 0, 1, 1, 2, 2, 2}; // device memory
coo_col_ind[nnz] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory
coo_val[nnz]     = {1, 2, 3, 4, 5, 6, 7, 8}; // device memory

// Allocate CSR matrix arrays
rocsparse_int* csr_row_ptr;
rocsparse_int* csr_col_ind;
float* csr_val;

hipMalloc((void**)&csr_row_ptr, sizeof(rocsparse_int) * (m + 1));
hipMalloc((void**)&csr_col_ind, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&csr_val, sizeof(float) * nnz);

// Convert the coo row indices into csr row offsets
rocsparse_coo2csr(handle,
                  coo_row_ind,
                  nnz,
                  m,
                  csr_row_ptr,
                  rocsparse_index_base_zero);

// Copy the column and value arrays
hipMemcpy(csr_col_ind,
          coo_col_ind,
          sizeof(rocsparse_int) * nnz,
          hipMemcpyDeviceToDevice);

hipMemcpy(csr_val,
          coo_val,
          sizeof(float) * nnz,
          hipMemcpyDeviceToDevice);

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• coo_row_ind – [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.

• csr_row_ptr – [out] array of m+1 elements that point to the start of every row of the sparse CSR matrix.

• idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or nnz is invalid.

• rocsparse_status_invalid_pointer – coo_row_ind or csr_row_ptr pointer is invalid.

rocsparse_csr2csc_buffer_size()

rocsparse_status rocsparse_csr2csc_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_action copy_values, size_t *buffer_size)

rocsparse_csr2csc_buffer_size returns the size of the temporary storage buffer required by rocsparse_Xcsr2csc().

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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.

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

• csr_col_ind – [in] array of nnz elements containing the column indices of the sparse CSR matrix.

• copy_values – [in] rocsparse_action_symbolic or rocsparse_action_numeric.

• buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_Xcsr2csc().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m, n or nnz is invalid.

• rocsparse_status_invalid_pointer – csr_row_ptr, csr_col_ind or buffer_size pointer is invalid.

• rocsparse_status_internal_error – an internal error occurred.

rocsparse_csr2csc()

rocsparse_status rocsparse_scsr2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, float *csc_val, rocsparse_int *csc_row_ind, rocsparse_int *csc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_dcsr2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, double *csc_val, rocsparse_int *csc_row_ind, rocsparse_int *csc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_ccsr2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_float_complex *csc_val, rocsparse_int *csc_row_ind, rocsparse_int *csc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_zcsr2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_double_complex *csc_val, rocsparse_int *csc_row_ind, rocsparse_int *csc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

Convert a sparse CSR matrix into a sparse CSC matrix.

rocsparse_csr2csc converts a CSR matrix into a CSC matrix. The resulting matrix can also be seen as the transpose of the input matrix. rocsparse_csr2csc can also be used to convert a CSC matrix into a CSR matrix.

The conversion of a sparse matrix from CSR to CSC format involves two steps. First, the user calls rocsparse_csr2csc_buffer_size in order to determine the size of the required tempory storage buffer. The user then allocates this buffer. Secondly, the user calls rocsparse_csr2csc to complete the conversion. Once the conversion is complete, the user must free the temporary buffer.

Both rocsparse_csr2csc_buffer_size and rocsparse_csr2csc take a rocsparse_action parameter as input. This copy_values parameter decides whether csc_row_ind and csc_val are filled during conversion (rocsparse_action_numeric) or whether only csc_row_ind is filled (rocsparse_action_symbolic). Using rocsparse_action_symbolic is useful for example if only the sparsity pattern is required.

Example

This example computes the transpose of a CSR matrix.

//     1 2 0 3 0
// A = 0 4 5 0 0
//     6 0 0 7 8

rocsparse_int m_A   = 3;
rocsparse_int n_A   = 5;
rocsparse_int nnz_A = 8;

csr_row_ptr_A[m_A + 1] = {0, 3, 5, 8};             // device memory
csr_col_ind_A[nnz_A] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory
csr_val_A[nnz_A]     = {1, 2, 3, 4, 5, 6, 7, 8}; // device memory

// Allocate memory for transposed CSR matrix
rocsparse_int m_T   = n_A;
rocsparse_int n_T   = m_A;
rocsparse_int nnz_T = nnz_A;

rocsparse_int* csr_row_ptr_T;
rocsparse_int* csr_col_ind_T;
float* csr_val_T;

hipMalloc((void**)&csr_row_ptr_T, sizeof(rocsparse_int) * (m_T + 1));
hipMalloc((void**)&csr_col_ind_T, sizeof(rocsparse_int) * nnz_T);
hipMalloc((void**)&csr_val_T, sizeof(float) * nnz_T);

// Obtain the temporary buffer size
size_t buffer_size;
rocsparse_csr2csc_buffer_size(handle,
                              m_A,
                              n_A,
                              nnz_A,
                              csr_row_ptr_A,
                              csr_col_ind_A,
                              rocsparse_action_numeric,
                              &buffer_size);

// Allocate temporary buffer
void* temp_buffer;
hipMalloc(&temp_buffer, buffer_size);

rocsparse_scsr2csc(handle,
                   m_A,
                   n_A,
                   nnz_A,
                   csr_val_A,
                   csr_row_ptr_A,
                   csr_col_ind_A,
                   csr_val_T,
                   csr_col_ind_T,
                   csr_row_ptr_T,
                   rocsparse_action_numeric,
                   rocsparse_index_base_zero,
                   temp_buffer);

Example

This example computes the symbolic transpose of A

//     1 2 0 3 0
// A = 0 4 5 0 0
//     6 0 0 7 8

rocsparse_int m_A   = 3;
rocsparse_int n_A   = 5;
rocsparse_int nnz_A = 8;

csr_row_ptr_A[m_A + 1] = {0, 3, 5, 8};           // device memory
csr_col_ind_A[nnz_A] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory

// Allocate memory for transposed CSR matrix
rocsparse_int m_T   = n_A;
rocsparse_int n_T   = m_A;
rocsparse_int nnz_T = nnz_A;

rocsparse_int* csr_row_ptr_T;
rocsparse_int* csr_col_ind_T;

hipMalloc((void**)&csr_row_ptr_T, sizeof(rocsparse_int) * (m_T + 1));
hipMalloc((void**)&csr_col_ind_T, sizeof(rocsparse_int) * nnz_T);

// Obtain the temporary buffer size
size_t buffer_size;
rocsparse_csr2csc_buffer_size(handle,
                              m_A,
                              n_A,
                              nnz_A,
                              csr_row_ptr_A,
                              csr_col_ind_A,
                              rocsparse_action_symbolic,
                              &buffer_size);

// Allocate temporary buffer
void* temp_buffer;
hipMalloc(&temp_buffer, buffer_size);

rocsparse_scsr2csc(handle,
                   m_A,
                   n_A,
                   nnz_A,
                   nullptr,
                   csr_row_ptr_A,
                   csr_col_ind_A,
                   nullptr,
                   csr_col_ind_T,
                   csr_row_ptr_T,
                   rocsparse_action_symbolic,
                   rocsparse_index_base_zero,
                   temp_buffer);

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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.

• csr_val – [in] array of nnz elements of the sparse CSR matrix.

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

• csr_col_ind – [in] array of nnz elements containing the column indices of the sparse CSR matrix.

• csc_val – [out] array of nnz elements of the sparse CSC matrix.

• csc_row_ind – [out] array of nnz elements containing the row indices of the sparse CSC matrix.

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

• copy_values – [in] rocsparse_action_symbolic or rocsparse_action_numeric.

• idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

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

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m, n or nnz is invalid.

• rocsparse_status_invalid_pointer – csr_val, csr_row_ptr, csr_col_ind, csc_val, csc_row_ind, csc_col_ptr or temp_buffer pointer is invalid.

• rocsparse_status_arch_mismatch – the device is not supported.

• rocsparse_status_internal_error – an internal error occurred.

rocsparse_gebsr2gebsc_buffer_size()

rocsparse_status rocsparse_sgebsr2gebsc_buffer_size(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *p_buffer_size)

rocsparse_status rocsparse_dgebsr2gebsc_buffer_size(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *p_buffer_size)

rocsparse_status rocsparse_cgebsr2gebsc_buffer_size(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *p_buffer_size)

rocsparse_status rocsparse_zgebsr2gebsc_buffer_size(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *p_buffer_size)

rocsparse_gebsr2gebsc_buffer_size returns the size of the temporary storage buffer required by rocsparse_Xgebsr2gebsc(). The temporary storage buffer must be allocated by the user.

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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.

• bsr_val – [in] array of nnzb*row_block_dim*col_block_dim containing the values of the sparse GEneral BSR matrix.

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

• bsr_col_ind – [in] array of nnzb elements containing the column indices of the sparse GEneral BSR matrix.

• row_block_dim – [in] row size of the blocks in the sparse general BSR matrix.

• col_block_dim – [in] col size of the blocks in the sparse general BSR matrix.

• p_buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_sgebsr2gebsc(), rocsparse_dgebsr2gebsc(), rocsparse_cgebsr2gebsc() and rocsparse_zgebsr2gebsc().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – mb, nb or nnzb is invalid.

• rocsparse_status_invalid_pointer – bsr_row_ptr, bsr_col_ind or p_buffer_size pointer is invalid.

• rocsparse_status_internal_error – an internal error occurred.

rocsparse_gebsr2gebsc()

rocsparse_status rocsparse_sgebsr2gebsc(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, float *bsc_val, rocsparse_int *bsc_row_ind, rocsparse_int *bsc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_dgebsr2gebsc(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, double *bsc_val, rocsparse_int *bsc_row_ind, rocsparse_int *bsc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_cgebsr2gebsc(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, rocsparse_float_complex *bsc_val, rocsparse_int *bsc_row_ind, rocsparse_int *bsc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

rocsparse_status rocsparse_zgebsr2gebsc(rocsparse_handle handle, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, rocsparse_double_complex *bsc_val, rocsparse_int *bsc_row_ind, rocsparse_int *bsc_col_ptr, rocsparse_action copy_values, rocsparse_index_base idx_base, void *temp_buffer)

Convert a sparse GEneral BSR matrix into a sparse GEneral BSC matrix.

rocsparse_gebsr2gebsc converts a GEneral BSR matrix into a GEneral BSC matrix. The resulting matrix can also be seen as the transpose of the input matrix. rocsparse_gebsr2gebsc can also be used to convert a GEneral BSC matrix into a GEneral BSR matrix.

The conversion of a sparse matrix from GEneral BSR to GEneral BSC format involves two steps. First, the user calls rocsparse_Xgebsr2gebsc_buffer_size() in order to determine the size of the required tempory storage buffer. The user then allocates this buffer. Secondly, the user calls rocsparse_gebsr2gebsc to complete the conversion. Once the conversion is complete, the user must free the temporary buffer.

rocsparse_gebsr2gebsc takes a rocsparse_action parameter as input. This copy_values parameter decides whether bsc_row_ind and bsc_val are filled during conversion (rocsparse_action_numeric) or whether only bsc_row_ind is filled (rocsparse_action_symbolic). Using rocsparse_action_symbolic is useful for example if only the sparsity pattern is required.

Example

This example computes the transpose of a GEneral BSR matrix.

//     1 2 0 3
// A = 0 4 5 0
//     6 0 0 7
//     1 2 3 4

rocsparse_int mb_A   = 2;
rocsparse_int nb_A   = 2;
rocsparse_int nnzb_A = 4;
rocsparse_int row_block_dim = 2;
rocsparse_int col_block_dim = 2;

std::vector<rocsparse_int> hbsr_row_ptr_A = {0, 2, 4}; 
std::vector<rocsparse_int> hbsr_col_ind_A = {0, 1, 0, 1}; 
std::vector<float> hbsr_val_A     = {1, 2, 0, 4, 0, 3, 5, 0, 6, 0, 1, 2, 0, 7, 3, 4};

rocsparse_int* dbsr_row_ptr_A = nullptr;
rocsparse_int* dbsr_col_ind_A = nullptr;
float* dbsr_val_A = nullptr;
hipMalloc((void**)&dbsr_row_ptr_A, sizeof(rocsparse_int) * (mb_A + 1));
hipMalloc((void**)&dbsr_col_ind_A, sizeof(rocsparse_int) * nnzb_A);
hipMalloc((void**)&dbsr_val_A, sizeof(float) * nnzb_A * row_block_dim * col_block_dim);

hipMemcpy(dbsr_row_ptr_A, hbsr_row_ptr_A.data(), sizeof(rocsparse_int) * (mb_A + 1), hipMemcpyHostToDevice);
hipMemcpy(dbsr_col_ind_A, hbsr_col_ind_A.data(), sizeof(rocsparse_int) * nnzb_A, hipMemcpyHostToDevice);
hipMemcpy(dbsr_val_A, hbsr_val_A.data(), sizeof(float) * nnzb_A * row_block_dim * col_block_dim, hipMemcpyHostToDevice);

// Allocate memory for transposed BSR matrix
rocsparse_int mb_T   = nb_A;
rocsparse_int nb_T   = mb_A;
rocsparse_int nnzb_T = nnzb_A;

rocsparse_int* dbsr_row_ptr_T = nullptr;
rocsparse_int* dbsr_col_ind_T = nullptr;
float* dbsr_val_T = nullptr;
hipMalloc((void**)&dbsr_row_ptr_T, sizeof(rocsparse_int) * (mb_T + 1));
hipMalloc((void**)&dbsr_col_ind_T, sizeof(rocsparse_int) * nnzb_T);
hipMalloc((void**)&dbsr_val_T, sizeof(float) * nnzb_A * row_block_dim * col_block_dim);

rocsparse_handle handle;
rocsparse_create_handle(&handle);

// Obtain the temporary buffer size
size_t buffer_size;
rocsparse_sgebsr2gebsc_buffer_size(handle,
                                 mb_A,
                                 nb_A,
                                 nnzb_A,
                                 dbsr_val_A,
                                 dbsr_row_ptr_A,
                                 dbsr_col_ind_A,
                                 row_block_dim,
                                 col_block_dim,
                                 &buffer_size);

// Allocate temporary buffer
void* temp_buffer;
hipMalloc(&temp_buffer, buffer_size);

rocsparse_sgebsr2gebsc(handle,
                     mb_A,
                     nb_A,
                     nnzb_A,
                     dbsr_val_A,
                     dbsr_row_ptr_A,
                     dbsr_col_ind_A,
                     row_block_dim,
                     col_block_dim,
                     dbsr_val_T,
                     dbsr_col_ind_T,
                     dbsr_row_ptr_T,
                     rocsparse_action_numeric,
                     rocsparse_index_base_zero,
                     temp_buffer);

rocsparse_destroy_handle(handle);

hipFree(temp_buffer);

hipFree(dbsr_row_ptr_A);
hipFree(dbsr_col_ind_A);
hipFree(dbsr_val_A);

hipFree(dbsr_row_ptr_T);
hipFree(dbsr_col_ind_T);
hipFree(dbsr_val_T);

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.

Note

This routine supports execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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.

• bsr_val – [in] array of nnzb * row_block_dim * col_block_dim elements of the sparse GEneral BSR matrix.

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

• bsr_col_ind – [in] array of nnz elements containing the column indices of the sparse GEneral BSR matrix.

• row_block_dim – [in] row size of the blocks in the sparse general BSR matrix.

• col_block_dim – [in] col size of the blocks in the sparse general BSR matrix.

• bsc_val – [out] array of nnz elements of the sparse BSC matrix.

• bsc_row_ind – [out] array of nnz elements containing the row indices of the sparse BSC matrix.

• bsc_col_ptr – [out] array of nb+1 elements that point to the start of every column of the sparse BSC matrix.

• copy_values – [in] rocsparse_action_symbolic or rocsparse_action_numeric.

• idx_base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

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

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – mb, nb or nnzb is invalid.

• rocsparse_status_invalid_pointer – bsr_val, bsr_row_ptr, bsr_col_ind, bsc_val, bsc_row_ind, bsc_col_ptr or temp_buffer pointer is invalid.

• rocsparse_status_arch_mismatch – the device is not supported.

• rocsparse_status_internal_error – an internal error occurred.

rocsparse_csr2ell_width()

rocsparse_status rocsparse_csr2ell_width(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr csr_descr, const rocsparse_int *csr_row_ptr, const rocsparse_mat_descr ell_descr, rocsparse_int *ell_width)

rocsparse_csr2ell_width computes the maximum of the per row non-zero elements over all rows, the ell_width, for a given 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.

Note

This routine supports execution in a hipGraph context.

Parameters:

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

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

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

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

• ell_descr – [in] descriptor of the sparse ELL matrix. Currently, only rocsparse_matrix_type_general is supported.

• ell_width – [out] pointer to the number of non-zero elements per row in ELL storage format.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m is invalid.

• rocsparse_status_invalid_pointer – csr_descr, csr_row_ptr, or ell_width pointer is invalid.

• rocsparse_status_internal_error – an internal error occurred.

• rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

rocsparse_csr2ell()

rocsparse_status rocsparse_scsr2ell(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr csr_descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, float *ell_val, rocsparse_int *ell_col_ind)

rocsparse_status rocsparse_dcsr2ell(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr csr_descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, double *ell_val, rocsparse_int *ell_col_ind)

rocsparse_status rocsparse_ccsr2ell(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr csr_descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, rocsparse_float_complex *ell_val, rocsparse_int *ell_col_ind)

rocsparse_status rocsparse_zcsr2ell(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr csr_descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, rocsparse_double_complex *ell_val, rocsparse_int *ell_col_ind)

Convert a sparse CSR matrix into a sparse ELL matrix.

rocsparse_csr2ell converts a CSR matrix into an ELL matrix. It is assumed, that ell_val and ell_col_ind are allocated. Allocation size is computed by the number of rows times the number of ELL non-zero elements per row, such that \(\text{nnz}_{\text{ELL}} = m \cdot \text{ell_width}\). The number of ELL non-zero elements per row is obtained by rocsparse_csr2ell_width().

Example

This example converts a CSR matrix into an ELL matrix.

//     1 2 0 3 0
// A = 0 4 5 0 0
//     6 0 0 7 8

rocsparse_int m   = 3;
rocsparse_int n   = 5;
rocsparse_int nnz = 8;

csr_row_ptr[m+1] = {0, 3, 5, 8};             // device memory
csr_col_ind[nnz] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory
csr_val[nnz]     = {1, 2, 3, 4, 5, 6, 7, 8}; // device memory

// Create ELL matrix descriptor
rocsparse_mat_descr ell_descr;
rocsparse_create_mat_descr(&ell_descr);

// Obtain the ELL width
rocsparse_int ell_width;
rocsparse_csr2ell_width(handle,
                        m,
                        csr_descr,
                        csr_row_ptr,
                        ell_descr,
                        &ell_width);

// Compute ELL non-zero entries
rocsparse_int ell_nnz = m * ell_width;

// Allocate ELL column and value arrays
rocsparse_int* ell_col_ind;
hipMalloc((void**)&ell_col_ind, sizeof(rocsparse_int) * ell_nnz);

float* ell_val;
hipMalloc((void**)&ell_val, sizeof(float) * ell_nnz);

// Format conversion
rocsparse_scsr2ell(handle,
                   m,
                   csr_descr,
                   csr_val,
                   csr_row_ptr,
                   csr_col_ind,
                   ell_descr,
                   ell_width,
                   ell_val,
                   ell_col_ind);

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

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

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

• csr_val – [in] array containing the values of the sparse CSR matrix.

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

• csr_col_ind – [in] array containing the column indices of the sparse CSR matrix.

• ell_descr – [in] descriptor of the sparse ELL matrix. Currently, only rocsparse_matrix_type_general is supported.

• ell_width – [in] number of non-zero elements per row in ELL storage format.

• ell_val – [out] array of m times ell_width elements of the sparse ELL matrix.

• ell_col_ind – [out] array of m times ell_width elements containing the column indices of the sparse ELL matrix.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or ell_width is invalid.

• rocsparse_status_invalid_pointer – csr_descr, csr_val, csr_row_ptr, csr_col_ind, ell_descr, ell_val or ell_col_ind pointer is invalid.

• rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

rocsparse_ell2csr_nnz()

rocsparse_status rocsparse_ell2csr_nnz(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, const rocsparse_int *ell_col_ind, const rocsparse_mat_descr csr_descr, rocsparse_int *csr_row_ptr, rocsparse_int *csr_nnz)

This function takes a sparse ELL matrix as input and computes the row offset array, csr_row_ptr, and the total number of nonzeros, csr_nnz, that will result from converting the ELL format input matrix to a CSR format output matrix. This function is the first step in the conversion and is used in conjunction with rocsparse_Xell2csr(). It is assumed that csr_row_ptr has been allocated with size m+1.

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

• m – [in] number of rows of the sparse ELL matrix.

• n – [in] number of columns of the sparse ELL matrix.

• ell_descr – [in] descriptor of the sparse ELL matrix. Currently, only rocsparse_matrix_type_general is supported.

• ell_width – [in] number of non-zero elements per row in ELL storage format.

• ell_col_ind – [in] array of m times ell_width elements containing the column indices of the sparse ELL matrix.

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

• csr_row_ptr – [out] array of m+1 elements that point to the start of every row of the sparse CSR matrix.

• csr_nnz – [out] pointer to the total number of non-zero elements in CSR storage format.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m, n or ell_width is invalid.

• rocsparse_status_invalid_pointer – ell_descr, ell_col_ind, csr_descr, csr_row_ptr or csr_nnz pointer is invalid.

• rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

rocsparse_ell2csr()

rocsparse_status rocsparse_sell2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, const float *ell_val, const rocsparse_int *ell_col_ind, const rocsparse_mat_descr csr_descr, float *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_dell2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, const double *ell_val, const rocsparse_int *ell_col_ind, const rocsparse_mat_descr csr_descr, double *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_cell2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, const rocsparse_float_complex *ell_val, const rocsparse_int *ell_col_ind, const rocsparse_mat_descr csr_descr, rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_zell2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr ell_descr, rocsparse_int ell_width, const rocsparse_double_complex *ell_val, const rocsparse_int *ell_col_ind, const rocsparse_mat_descr csr_descr, rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

Convert a sparse ELL matrix into a sparse CSR matrix.

rocsparse_ell2csr converts a ELL matrix into a CSR matrix. It is assumed that csr_row_ptr has already been filled and that csr_val and csr_col_ind are allocated by the user. Allocation size for csr_row_ptr is computed as m+1. Allocation size for csr_val and csr_col_ind is computed using rocsparse_ell2csr_nnz() which also fills in csr_row_ptr.

Example

This example converts an ELL matrix into a CSR matrix.

//     1 2 0 3 0
// A = 0 4 5 0 0
//     6 0 0 7 8
rocsparse_int m         = 3;
rocsparse_int n         = 5;
rocsparse_int nnz       = 8;
rocsparse_int ell_width = 3;

std::vector<rocsparse_int> hell_col_ind = {0, 1, 0, 1, 2, 3, 3, -1, 4};
std::vector<float> hell_val = {1, 4, 6, 2, 5, 7, 3, 0, 8};

rocsparse_int* dell_col_ind = nullptr;
float* dell_val = nullptr;
hipMalloc((void**)&dell_col_ind, sizeof(rocsparse_int) * m * ell_width);
hipMalloc((void**)&dell_val, sizeof(float) * m * ell_width);

hipMemcpy(dell_col_ind, hell_col_ind.data(), sizeof(rocsparse_int) * m * ell_width, hipMemcpyHostToDevice);
hipMemcpy(dell_val, hell_val.data(), sizeof(float) * m * ell_width, hipMemcpyHostToDevice);

rocsparse_handle handle;
rocsparse_create_handle(&handle);

// Create ELL matrix descriptor
rocsparse_mat_descr ell_descr;
rocsparse_create_mat_descr(&ell_descr);

// Create CSR matrix descriptor
rocsparse_mat_descr csr_descr;
rocsparse_create_mat_descr(&csr_descr);

// Allocate csr_row_ptr array for row offsets
rocsparse_int* dcsr_row_ptr;
hipMalloc((void**)&dcsr_row_ptr, sizeof(rocsparse_int) * (m + 1));

// Obtain the number of CSR non-zero entries
// and fill csr_row_ptr array with row offsets
rocsparse_int csr_nnz;
rocsparse_ell2csr_nnz(handle,
                      m,
                      n,
                      ell_descr,
                      ell_width,
                      dell_col_ind,
                      csr_descr,
                      dcsr_row_ptr,
                      &csr_nnz);

// Allocate CSR column and value arrays
rocsparse_int* dcsr_col_ind = nullptr;
float* dcsr_val = nullptr;
hipMalloc((void**)&dcsr_col_ind, sizeof(rocsparse_int) * csr_nnz);
hipMalloc((void**)&dcsr_val, sizeof(float) * csr_nnz);

// Format conversion
rocsparse_sell2csr(handle,
                   m,
                   n,
                   ell_descr,
                   ell_width,
                   dell_val,
                   dell_col_ind,
                   csr_descr,
                   dcsr_val,
                   dcsr_row_ptr,
                   dcsr_col_ind);

hipFree(dell_col_ind);
hipFree(dell_val);

hipFree(dcsr_row_ptr);
hipFree(dcsr_col_ind);
hipFree(dcsr_val);

rocsparse_destroy_mat_descr(ell_descr);
rocsparse_destroy_mat_descr(csr_descr);

rocsparse_destroy_handle(handle);

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• m – [in] number of rows of the sparse ELL matrix.

• n – [in] number of columns of the sparse ELL matrix.

• ell_descr – [in] descriptor of the sparse ELL matrix. Currently, only rocsparse_matrix_type_general is supported.

• ell_width – [in] number of non-zero elements per row in ELL storage format.

• ell_val – [in] array of m times ell_width elements of the sparse ELL matrix.

• ell_col_ind – [in] array of m times ell_width elements containing the column indices of the sparse ELL matrix.

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

• csr_val – [out] array containing the values of the sparse CSR matrix.

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

• csr_col_ind – [out] array containing the column indices of the sparse CSR matrix.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m, n or ell_width is invalid.

• rocsparse_status_invalid_pointer – csr_descr, csr_val, csr_row_ptr, csr_col_ind, ell_descr, ell_val or ell_col_ind pointer is invalid.

• rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

rocsparse_csr2hyb()

rocsparse_status rocsparse_scsr2hyb(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_hyb_mat hyb, rocsparse_int user_ell_width, rocsparse_hyb_partition partition_type)

rocsparse_status rocsparse_dcsr2hyb(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_hyb_mat hyb, rocsparse_int user_ell_width, rocsparse_hyb_partition partition_type)

rocsparse_status rocsparse_ccsr2hyb(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_hyb_mat hyb, rocsparse_int user_ell_width, rocsparse_hyb_partition partition_type)

rocsparse_status rocsparse_zcsr2hyb(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_hyb_mat hyb, rocsparse_int user_ell_width, rocsparse_hyb_partition partition_type)

Convert a sparse CSR matrix into a sparse HYB matrix.

rocsparse_csr2hyb converts a CSR matrix into a HYB matrix. It is assumed that hyb has been initialized with rocsparse_create_hyb_mat().

Example

This example converts a CSR matrix into a HYB matrix using user defined partitioning.

//     1 2 3 4 0 0
// A = 3 4 0 0 0 0
//     6 5 3 4 0 0
//     1 2 0 0 0 0
rocsparse_int m   = 4;
rocsparse_int n   = 6;
rocsparse_int nnz = 12;

std::vector<rocsparse_int> hcsr_row_ptr = {0, 4, 6, 10, 12}; 
std::vector<rocsparse_int> hcsr_col_ind = {0, 1, 2, 3, 0, 1, 0, 1, 2, 3, 0, 1}; 
std::vector<float> hcsr_val     = {1, 2, 3, 4, 3, 4, 6, 5, 3, 4, 1, 2};

rocsparse_int* dcsr_row_ptr = nullptr;
rocsparse_int* dcsr_col_ind = nullptr;
float* dcsr_val = nullptr;
hipMalloc((void**)&dcsr_row_ptr, sizeof(rocsparse_int) * (m + 1));
hipMalloc((void**)&dcsr_col_ind, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&dcsr_val, sizeof(float) * nnz);

hipMemcpy(dcsr_row_ptr, hcsr_row_ptr.data(), sizeof(rocsparse_int) * (m + 1), hipMemcpyHostToDevice);
hipMemcpy(dcsr_col_ind, hcsr_col_ind.data(), sizeof(rocsparse_int) * nnz, hipMemcpyHostToDevice);
hipMemcpy(dcsr_val, hcsr_val.data(), sizeof(float) * nnz, hipMemcpyHostToDevice);

rocsparse_handle handle;
rocsparse_create_handle(&handle);

rocsparse_mat_descr descr;
rocsparse_create_mat_descr(&descr);

rocsparse_hyb_mat hyb;
rocsparse_create_hyb_mat(&hyb);

rocsparse_int user_ell_width = 3;
rocsparse_hyb_partition partition_type = rocsparse_hyb_partition_user;
rocsparse_scsr2hyb(handle,
                   m,
                   n,
                   descr,
                   dcsr_val,
                   dcsr_row_ptr,
                   dcsr_col_ind,
                   hyb,
                   user_ell_width,
                   partition_type);

rocsparse_int* dcsr_row_ptr2 = nullptr;
rocsparse_int* dcsr_col_ind2 = nullptr;
float* dcsr_val2 = nullptr;
hipMalloc((void**)&dcsr_row_ptr2, sizeof(rocsparse_int) * (m + 1));
hipMalloc((void**)&dcsr_col_ind2, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&dcsr_val2, sizeof(float) * nnz);

// Obtain the temporary buffer size
size_t buffer_size;
rocsparse_hyb2csr_buffer_size(handle,
                              descr,
                              hyb,
                              dcsr_row_ptr2,
                              &buffer_size);

// Allocate temporary buffer
void* temp_buffer;
hipMalloc(&temp_buffer, buffer_size);

rocsparse_shyb2csr(handle,
                   descr,
                   hyb,
                   dcsr_val2,
                   dcsr_row_ptr2,
                   dcsr_col_ind2,
                   temp_buffer);

rocsparse_destroy_handle(handle);
rocsparse_destroy_mat_descr(descr);
rocsparse_destroy_hyb_mat(hyb);

hipFree(temp_buffer);

hipFree(dcsr_row_ptr);
hipFree(dcsr_col_ind);
hipFree(dcsr_val);

hipFree(dcsr_row_ptr2);
hipFree(dcsr_col_ind2);
hipFree(dcsr_val2);

Note

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

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

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

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

• descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

• csr_val – [in] array containing the values of the sparse CSR matrix.

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

• csr_col_ind – [in] array containing the column indices of the sparse CSR matrix.

• hyb – [out] sparse matrix in HYB format.

• user_ell_width – [in] width of the ELL part of the HYB matrix (only required if partition_type == rocsparse_hyb_partition_user).

• partition_type – [in] rocsparse_hyb_partition_auto (recommended), rocsparse_hyb_partition_user or rocsparse_hyb_partition_max.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m, n or user_ell_width is invalid.

• rocsparse_status_invalid_value – partition_type is invalid.

• rocsparse_status_invalid_pointer – descr, hyb, csr_val, csr_row_ptr or csr_col_ind pointer is invalid.

• rocsparse_status_memory_error – the buffer for the HYB matrix could not be allocated.

• rocsparse_status_internal_error – an internal error occurred.

• rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

rocsparse_hyb2csr_buffer_size()

rocsparse_status rocsparse_hyb2csr_buffer_size(rocsparse_handle handle, const rocsparse_mat_descr descr, const rocsparse_hyb_mat hyb, const rocsparse_int *csr_row_ptr, size_t *buffer_size)

rocsparse_hyb2csr_buffer_size returns the size of the temporary storage buffer required by rocsparse_Xhyb2csr(). The temporary storage buffer must be allocated by the user.

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• descr – [in] descriptor of the sparse HYB matrix. Currently, only rocsparse_matrix_type_general is supported.

• hyb – [in] sparse matrix in HYB format.

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

• buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_Xhyb2csr().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_pointer – descr, hyb, csr_row_ptr or buffer_size pointer is invalid.

• rocsparse_status_internal_error – an internal error occurred.

• rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

rocsparse_hyb2csr()

rocsparse_status rocsparse_shyb2csr(rocsparse_handle handle, const rocsparse_mat_descr descr, const rocsparse_hyb_mat hyb, float *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, void *temp_buffer)

rocsparse_status rocsparse_dhyb2csr(rocsparse_handle handle, const rocsparse_mat_descr descr, const rocsparse_hyb_mat hyb, double *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, void *temp_buffer)

rocsparse_status rocsparse_chyb2csr(rocsparse_handle handle, const rocsparse_mat_descr descr, const rocsparse_hyb_mat hyb, rocsparse_float_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, void *temp_buffer)

rocsparse_status rocsparse_zhyb2csr(rocsparse_handle handle, const rocsparse_mat_descr descr, const rocsparse_hyb_mat hyb, rocsparse_double_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, void *temp_buffer)

Convert a sparse HYB matrix into a sparse CSR matrix.

rocsparse_hyb2csr converts a HYB matrix into a CSR matrix. This requires a HYB input structure, rocsparse_hyb_mat, which is created using rocsparse_create_hyb_mat and is filled with data using the conversion routine rocsparse_Xcsr2hyb().

Converting back to a sparse CSR matrix from a sparse HYB matrix requires two steps. First, the user calls rocsparse_hyb2csr_buffer_size in order to determine the size of the required temporary storage buffer. Once this is determined, the user allocates this buffer. Finally, the user calls rocsparse_Xhyb2csr() to complete the conversion.

Example

This example converts a HYB matrix into a CSR matrix.

//     1 2 3 4 0 0
// A = 3 4 0 0 0 0
//     6 5 3 4 0 0
//     1 2 0 0 0 0
rocsparse_int m   = 4;
rocsparse_int n   = 6;
rocsparse_int nnz = 12;

std::vector<rocsparse_int> hcsr_row_ptr = {0, 4, 6, 10, 12}; 
std::vector<rocsparse_int> hcsr_col_ind = {0, 1, 2, 3, 0, 1, 0, 1, 2, 3, 0, 1}; 
std::vector<float> hcsr_val     = {1, 2, 3, 4, 3, 4, 6, 5, 3, 4, 1, 2};

rocsparse_int* dcsr_row_ptr = nullptr;
rocsparse_int* dcsr_col_ind = nullptr;
float* dcsr_val = nullptr;
hipMalloc((void**)&dcsr_row_ptr, sizeof(rocsparse_int) * (m + 1));
hipMalloc((void**)&dcsr_col_ind, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&dcsr_val, sizeof(float) * nnz);

hipMemcpy(dcsr_row_ptr, hcsr_row_ptr.data(), sizeof(rocsparse_int) * (m + 1), hipMemcpyHostToDevice);
hipMemcpy(dcsr_col_ind, hcsr_col_ind.data(), sizeof(rocsparse_int) * nnz, hipMemcpyHostToDevice);
hipMemcpy(dcsr_val, hcsr_val.data(), sizeof(float) * nnz, hipMemcpyHostToDevice);

rocsparse_handle handle;
rocsparse_create_handle(&handle);

rocsparse_mat_descr descr;
rocsparse_create_mat_descr(&descr);

rocsparse_hyb_mat hyb;
rocsparse_create_hyb_mat(&hyb);

rocsparse_int user_ell_width = 3;
rocsparse_hyb_partition partition_type = rocsparse_hyb_partition_user;
rocsparse_scsr2hyb(handle,
                   m,
                   n,
                   descr,
                   dcsr_val,
                   dcsr_row_ptr,
                   dcsr_col_ind,
                   hyb,
                   user_ell_width,
                   partition_type);

rocsparse_int* dcsr_row_ptr2 = nullptr;
rocsparse_int* dcsr_col_ind2 = nullptr;
float* dcsr_val2 = nullptr;
hipMalloc((void**)&dcsr_row_ptr2, sizeof(rocsparse_int) * (m + 1));
hipMalloc((void**)&dcsr_col_ind2, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&dcsr_val2, sizeof(float) * nnz);

// Obtain the temporary buffer size
size_t buffer_size;
rocsparse_hyb2csr_buffer_size(handle,
                              descr,
                              hyb,
                              dcsr_row_ptr2,
                              &buffer_size);

// Allocate temporary buffer
void* temp_buffer;
hipMalloc(&temp_buffer, buffer_size);

rocsparse_shyb2csr(handle,
                   descr,
                   hyb,
                   dcsr_val2,
                   dcsr_row_ptr2,
                   dcsr_col_ind2,
                   temp_buffer);

rocsparse_destroy_handle(handle);
rocsparse_destroy_mat_descr(descr);
rocsparse_destroy_hyb_mat(hyb);

hipFree(temp_buffer);

hipFree(dcsr_row_ptr);
hipFree(dcsr_col_ind);
hipFree(dcsr_val);

hipFree(dcsr_row_ptr2);
hipFree(dcsr_col_ind2);
hipFree(dcsr_val2);

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• descr – [in] descriptor of the sparse HYB matrix. Currently, only rocsparse_matrix_type_general is supported.

• hyb – [in] sparse matrix in HYB format.

• csr_val – [out] array containing the values of the sparse CSR matrix.

• csr_row_ptr – [out] array of m+1 elements that point to the start of every row of the sparse CSR matrix.

• csr_col_ind – [out] array containing the column indices of the sparse CSR matrix.

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

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_pointer – descr, hyb, csr_val, csr_row_ptr, csr_col_ind or temp_buffer pointer is invalid.

• rocsparse_status_internal_error – an internal error occurred.

• rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

rocsparse_bsr2csr()

rocsparse_status rocsparse_sbsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr csr_descr, float *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_dbsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr csr_descr, double *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_cbsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr csr_descr, rocsparse_float_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_zbsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr csr_descr, rocsparse_double_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

Convert a sparse BSR matrix into a sparse CSR matrix.

rocsparse_bsr2csr converts a BSR matrix into a CSR matrix. It is assumed, that csr_val, csr_col_ind and csr_row_ptr are allocated. Allocation size for csr_row_ptr is m+1 where:

\[\begin{split} m = mb * block\_dim \\ n = nb * block\_dim \end{split}\]

Allocation for csr_val and csr_col_ind is computed by the the number of blocks in the BSR matrix multiplied by the block dimension squared:

\[ nnz = nnzb * block\_dim * block\_dim \]

Example

This example converts a BSR matrix into an CSR matrix.

//     1 4 2 1 0 0
// A = 0 2 3 5 0 0
//     5 2 2 7 8 6
//     9 3 9 1 6 1
rocsparse_int mb = 2;
rocsparse_int nb = 3;
rocsparse_int block_dim = 2;
rocsparse_int m = mb * block_dim;
rocsparse_int n = nb * block_dim;
rocsparse_int nnzb = 5;
rocsparse_int nnz = nnzb * block_dim * block_dim;

std::vector<rocsparse_int> hbsr_row_ptr = {0, 2, 5};
std::vector<rocsparse_int> hbsr_col_ind = {0, 1, 0, 1, 2};
std::vector<float> hbsr_val = {1.0f, 0.0f, 4.0f, 2.0f, 
                               2.0f, 3.0f, 1.0f, 5.0f, 
                               5.0f, 9.0f, 2.0f, 3.0f,
                               2.0f, 9.0f, 7.0f, 1.0f,
                               8.0f, 6.0f, 6.0f, 1.0f};

rocsparse_int* dbsr_row_ptr = nullptr;
rocsparse_int* dbsr_col_ind = nullptr;
float* dbsr_val = nullptr;
hipMalloc((void**)&dbsr_row_ptr, sizeof(rocsparse_int) * (mb + 1));
hipMalloc((void**)&dbsr_col_ind, sizeof(rocsparse_int) * nnzb);
hipMalloc((void**)&dbsr_val, sizeof(float) * nnzb * block_dim * block_dim);

hipMemcpy(dbsr_row_ptr, hbsr_row_ptr.data(), sizeof(rocsparse_int) * (mb + 1), hipMemcpyHostToDevice);
hipMemcpy(dbsr_col_ind, hbsr_col_ind.data(), sizeof(rocsparse_int) * nnzb, hipMemcpyHostToDevice);
hipMemcpy(dbsr_val, hbsr_val.data(), sizeof(float) * nnzb * block_dim * block_dim, hipMemcpyHostToDevice);

// Create CSR arrays on device
rocsparse_int* dcsr_row_ptr = nullptr;
rocsparse_int* dcsr_col_ind = nullptr;
float* dcsr_val = nullptr;
hipMalloc((void**)&dcsr_row_ptr, sizeof(rocsparse_int) * (m + 1));
hipMalloc((void**)&dcsr_col_ind, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&dcsr_val, sizeof(float) * nnz);

// Create rocsparse handle
rocsparse_handle handle;
rocsparse_create_handle(&handle);

rocsparse_mat_descr bsr_descr = nullptr;
rocsparse_create_mat_descr(&bsr_descr);

rocsparse_mat_descr csr_descr = nullptr;
rocsparse_create_mat_descr(&csr_descr);

rocsparse_set_mat_index_base(bsr_descr, rocsparse_index_base_zero);
rocsparse_set_mat_index_base(csr_descr, rocsparse_index_base_zero);

// Format conversion
rocsparse_sbsr2csr(handle,
                    rocsparse_direction_column,
                    mb,
                    nb,
                    bsr_descr,
                    dbsr_val,
                    dbsr_row_ptr,
                    dbsr_col_ind,
                    block_dim,
                    csr_descr,
                    dcsr_val,
                    dcsr_row_ptr,
                    dcsr_col_ind);

rocsparse_destroy_handle(handle);
rocsparse_destroy_mat_descr(csr_descr);
rocsparse_destroy_mat_descr(bsr_descr);

hipFree(dbsr_row_ptr);
hipFree(dbsr_col_ind);
hipFree(dbsr_val);

hipFree(dcsr_row_ptr);
hipFree(dcsr_col_ind);
hipFree(dcsr_val);

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• dir – [in] the storage format of the blocks, rocsparse_direction_row or rocsparse_direction_column

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

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

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

• bsr_val – [in] array of nnzb*block_dim*block_dim containing the values of the sparse BSR matrix.

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

• bsr_col_ind – [in] array of nnzb elements containing the block column indices of the sparse BSR matrix.

• block_dim – [in] size of the blocks in the sparse BSR matrix.

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

• csr_val – [out] array of nnzb*block_dim*block_dim elements containing the values of the sparse CSR matrix.

• csr_row_ptr – [out] array of m+1 where m=mb*block_dim elements that point to the start of every row of the sparse CSR matrix.

• csr_col_ind – [out] array of nnzb*block_dim*block_dim elements containing the column indices of the sparse CSR matrix.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – mb or nb or block_dim is invalid.

• rocsparse_status_invalid_pointer – bsr_val, bsr_row_ptr, bsr_col_ind, csr_val, csr_row_ptr or csr_col_ind pointer is invalid.

rocsparse_gebsr2csr()

rocsparse_status rocsparse_sgebsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_mat_descr csr_descr, float *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_dgebsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_mat_descr csr_descr, double *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_cgebsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_mat_descr csr_descr, rocsparse_float_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_zgebsr2csr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, const rocsparse_mat_descr bsr_descr, const rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, const rocsparse_mat_descr csr_descr, rocsparse_double_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

Convert a sparse general BSR matrix into a sparse CSR matrix.

rocsparse_gebsr2csr converts a BSR matrix into a CSR matrix. The input matrix is assumed to be allocated such that array bsr_row_ptr has length mb+1, bsr_col_ind has length nnzb, and bsr_val has length nnzb*row_block_dim*col_block_dim. The output matrix is assumed to be allocated such that array csr_row_ptr has length m+1, csr_col_ind has length nnz, and csr_val has length nnz where:

\[\begin{split} m = mb * row\_block\_dim \\ n = nb * col\_block\_dim \\ nnz = nnzb * row\_block\_dim * col\_block\_dim \end{split}\]

Example

This example converts a general BSR matrix into an CSR matrix.

//     1 4 0 0 0 0
// A = 0 2 3 0 0 0
//     5 0 0 7 8 0
//     0 0 9 0 6 0

rocsparse_int mb   = 2;
rocsparse_int nb   = 2;
rocsparse_int row_block_dim = 2;
rocsparse_int col_block_dim = 3;
rocsparse_int m = Mb * row_block_dim;
rocsparse_int n = Nb * col_block_dim;

bsr_row_ptr[mb+1]                 = {0, 1, 3};                                              // device memory
bsr_col_ind[nnzb]                 = {0, 0, 1};                                              // device memory
bsr_val[nnzb*block_dim*block_dim] = {1, 0, 4, 2, 0, 3, 5, 0, 0, 0, 0, 9, 7, 0, 8, 6, 0, 0}; // device memory

rocsparse_int nnzb = bsr_row_ptr[mb] - bsr_row_ptr[0];

// Create CSR arrays on device
rocsparse_int* csr_row_ptr;
rocsparse_int* csr_col_ind;
float* csr_val;
hipMalloc((void**)&csr_row_ptr, sizeof(rocsparse_int) * (m + 1));
hipMalloc((void**)&csr_col_ind, sizeof(rocsparse_int) * nnzb * row_block_dim * col_block_dim);
hipMalloc((void**)&csr_val, sizeof(float) * nnzb * row_block_dim * col_block_dim);

// Create rocsparse handle
rocsparse_handle handle;
rocsparse_create_handle(&handle);

rocsparse_mat_descr bsr_descr = nullptr;
rocsparse_create_mat_descr(&bsr_descr);

rocsparse_mat_descr csr_descr = nullptr;
rocsparse_create_mat_descr(&csr_descr);

rocsparse_set_mat_index_base(bsr_descr, rocsparse_index_base_zero);
rocsparse_set_mat_index_base(csr_descr, rocsparse_index_base_zero);

// Format conversion
rocsparse_sgebsr2csr(handle,
                   rocsparse_direction_column,
                   mb,
                   nb,
                   bsr_descr,
                   bsr_val,
                   bsr_row_ptr,
                   bsr_col_ind,
                   row_block_dim,
                   col_block_dim,
                   csr_descr,
                   csr_val,
                   csr_row_ptr,
                   csr_col_ind);

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• dir – [in] the storage format of the blocks, rocsparse_direction_row or rocsparse_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.

• bsr_descr – [in] descriptor of the sparse general BSR matrix. Currently, only rocsparse_matrix_type_general is supported.

• bsr_val – [in] array of nnzb*row_block_dim*col_block_dim containing the values of the sparse BSR matrix.

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

• bsr_col_ind – [in] array of nnzb elements containing the block column indices of the sparse BSR matrix.

• row_block_dim – [in] row size of the blocks in the sparse general BSR matrix.

• col_block_dim – [in] column size of the blocks in the sparse general BSR matrix.

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

• csr_val – [out] array of nnzb*row_block_dim*col_block_dim elements containing the values of the sparse CSR matrix.

• csr_row_ptr – [out] array of m+1 where m=mb*row_block_dim elements that point to the start of every row of the sparse CSR matrix.

• csr_col_ind – [out] array of nnzb*block_dim*block_dim elements containing the column indices of the sparse CSR matrix.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – mb or nb or block_dim is invalid.

• rocsparse_status_invalid_pointer – bsr_val, bsr_row_ptr, bsr_col_ind, csr_val, csr_row_ptr or csr_col_ind pointer is invalid.

rocsparse_gebsr2gebsr_buffer_size()

rocsparse_status rocsparse_sgebsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const float *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, size_t *buffer_size)

rocsparse_status rocsparse_dgebsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const double *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, size_t *buffer_size)

rocsparse_status rocsparse_cgebsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const rocsparse_float_complex *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, size_t *buffer_size)

rocsparse_status rocsparse_zgebsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const rocsparse_double_complex *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, size_t *buffer_size)

rocsparse_gebsr2gebsr_buffer_size returns the size of the temporary storage buffer that is required by rocsparse_gebsr2gebsr_nnz() and rocsparse_Xgebsr2gebsr(). The temporary storage buffer must be allocated by the user.

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• dir – [in] the storage format of the blocks, rocsparse_direction_row or rocsparse_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\).

• descr_A – [in] the descriptor of the general BSR sparse matrix \(A\), the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• bsr_val_A – [in] array of nnzb*row_block_dim_A*col_block_dim_A containing the values of the sparse general BSR matrix \(A\).

• bsr_row_ptr_A – [in] array of mb+1 elements that point to the start of every block row of the sparse general BSR matrix \(A\).

• bsr_col_ind_A – [in] array of nnzb elements containing the block column indices of the sparse general BSR matrix \(A\).

• row_block_dim_A – [in] row size of the blocks in the sparse general BSR matrix \(A\).

• col_block_dim_A – [in] column size of the blocks in the sparse general BSR matrix \(A\).

• row_block_dim_C – [in] row size of the blocks in the sparse general BSR matrix \(C\).

• col_block_dim_C – [in] column size of the blocks in the sparse general BSR matrix \(C\).

• buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_gebsr2gebsr_nnz() and rocsparse_Xgebsr2gebsr().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – mb or nb or nnzb or row_block_dim_A or col_block_dim_A or row_block_dim_C or col_block_dim_C is invalid.

• rocsparse_status_invalid_pointer – bsr_row_ptr_A or bsr_col_ind_A or descr_A or buffer_size pointer is invalid.

rocsparse_gebsr2gebsr_nnz()

rocsparse_status rocsparse_gebsr2gebsr_nnz(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, const rocsparse_mat_descr descr_C, rocsparse_int *bsr_row_ptr_C, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, rocsparse_int *nnz_total_dev_host_ptr, void *temp_buffer)

This function takes a sparse GEneral BSR matrix as input and computes the block row offset array, bsr_row_ptr_C, and the total number of nonzero blocks, nnz_total_dev_host_ptr, that will result from converting the GEneral BSR format input matrix to a GEneral BSR format output matrix. The input and output matrices can have different row and column block dimensions. rocsparse_gebsr2gebsr_nnz is the second step in the conversion and is used in conjunction with rocsparse_Xgebsr2gebsr_buffer_size() and rocsparse_Xgebsr2gebsr().

rocsparse_gebsr2gebsr_nnz accepts both host and device pointers for nnz_total_dev_host_ptr which can be set by calling rocsparse_set_pointer_mode prior to calling rocsparse_gebsr2gebsr_nnz.

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

• dir – [in] the storage format of the blocks, rocsparse_direction_row or rocsparse_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\).

• descr_A – [in] the descriptor of the general BSR sparse matrix \(A\), the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• bsr_row_ptr_A – [in] array of mb+1 elements that point to the start of every block row of the sparse general BSR matrix \(A\).

• bsr_col_ind_A – [in] array of nnzb elements containing the block column indices of the sparse general BSR matrix \(A\).

• row_block_dim_A – [in] row size of the blocks in the sparse general BSR matrix \(A\).

• col_block_dim_A – [in] column size of the blocks in the sparse general BSR matrix \(A\).

• descr_C – [in] the descriptor of the general BSR sparse matrix \(C\), the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• bsr_row_ptr_C – [in] array of mb_C+1 elements that point to the start of every block row of the sparse general BSR matrix \(C\) where mb_C=(m+row_block_dim_C-1)/row_block_dim_C.

• row_block_dim_C – [in] row size of the blocks in the sparse general BSR matrix \(C\).

• col_block_dim_C – [in] column size of the blocks in the sparse general BSR matrix \(C\).

• nnz_total_dev_host_ptr – [out] total number of nonzero blocks in general BSR sparse matrix \(C\) stored using device or host memory.

• temp_buffer – [out] buffer allocated by the user whose size is determined by calling rocsparse_Xgebsr2gebsr_buffer_size().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – mb or nb or nnzb or row_block_dim_A or col_block_dim_A or row_block_dim_C or col_block_dim_C is invalid.

• rocsparse_status_invalid_pointer – bsr_row_ptr_A or bsr_col_ind_A or bsr_row_ptr_C or descr_A or descr_C or temp_buffer pointer is invalid.

rocsparse_gebsr2gebsr()

rocsparse_status rocsparse_sgebsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const float *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, const rocsparse_mat_descr descr_C, float *bsr_val_C, rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, void *temp_buffer)

rocsparse_status rocsparse_dgebsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const double *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, const rocsparse_mat_descr descr_C, double *bsr_val_C, rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, void *temp_buffer)

rocsparse_status rocsparse_cgebsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const rocsparse_float_complex *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, const rocsparse_mat_descr descr_C, rocsparse_float_complex *bsr_val_C, rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, void *temp_buffer)

rocsparse_status rocsparse_zgebsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int mb, rocsparse_int nb, rocsparse_int nnzb, const rocsparse_mat_descr descr_A, const rocsparse_double_complex *bsr_val_A, const rocsparse_int *bsr_row_ptr_A, const rocsparse_int *bsr_col_ind_A, rocsparse_int row_block_dim_A, rocsparse_int col_block_dim_A, const rocsparse_mat_descr descr_C, rocsparse_double_complex *bsr_val_C, rocsparse_int *bsr_row_ptr_C, rocsparse_int *bsr_col_ind_C, rocsparse_int row_block_dim_C, rocsparse_int col_block_dim_C, void *temp_buffer)

This function converts the general BSR sparse matrix \(A\) to another general BSR sparse matrix \(C\).

rocsparse_gebsr2gebsr converts a GEneral BSR matrix \(A\) into a GEneral BSR matrix \(C\). The input and output matrices can have different row and column block dimensions. The input matrix \(A\) is assumed to be allocated such that array bsr_row_ptr_A has length mb+1, bsr_col_ind_A has length nnzb, and bsr_val_A has length nnzb*row_block_dim_A*col_block_dim_A. The output matrix \(C\) is assumed to be allocated such that array bsr_row_ptr_C has length mb_C+1, bsr_col_ind_C has length nnzb_C, and bsr_val_C has length nnzb_C*row_block_dim_C*col_block_dim_C where:

\[\begin{split} m = mb * row\_block\_dim\_A \\ n = nb * col\_block\_dim\_A \end{split}\]

and

\[\begin{split} mb\_C = (m + row\_block\_dim\_C - 1) / row\_block\_dim\_C \\ nb\_C = (n + col\_block\_dim\_C - 1) / col\_block\_dim\_C \end{split}\]

The number of non-zero blocks in the output sparse \(C\) matrix (i.e. nnzb_C) is computed using rocsparse_gebsr2gebsr_nnz() which also fills in bsr_row_ptr_C array.

Converting from a sparse GEneral BSR matrix to a sparse GEneral BSR matrix requires three steps. First, the user calls rocsparse_Xgebsr2gebsr_buffer_size() in order to determine the size of the required temporary storage buffer. Once this has been determined, the user allocates this buffer. The user also now allocates the bsr_row_ptr_C array to have length mb_C+1 and passes this to the function rocsparse_gebsr2gebsr_nnz. This will fill the bsr_row_ptr_C array and also compute the total number of nonzero blocks in the GEneral BSR output \(C\) matrix. Now that the total number of nonzero blocks is known, the user can allocate the bsr_col_ind_C and bsr_val_C arrays. Finally, the user calls rocsparse_gebsr2gebsr to complete the conversion. Once the conversion is complete, the temporary storage buffer can be deallocated. See example below.

Example

This example converts a GEneral BSR matrix into an GEneral BSR matrix.

//     1 2 0 0 5 6
// A = 3 4 0 0 7 8
//     6 5 3 4 0 0
//     1 2 5 4 0 0

rocsparse_int mb_A   = 2;
rocsparse_int nb_A   = 2;
rocsparse_int nnzb_A = 4;
rocsparse_int row_block_dim_A = 2;
rocsparse_int col_block_dim_A = 2;

rocsparse_int m = mb_A * row_block_dim_A;
rocsparse_int n = nb_A * col_block_dim_A;

rocsparse_direction dir = rocsparse_direction_row;

std::vector<rocsparse_int> hbsr_row_ptr_A = {0, 2, 4}; 
std::vector<rocsparse_int> hbsr_col_ind_A = {0, 2, 0, 1}; 
std::vector<float> hbsr_val_A     = {1, 2, 3, 4, 5, 6, 7, 8, 6, 5, 1, 2, 3, 4, 5, 4};

rocsparse_int* dbsr_row_ptr_A = nullptr;
rocsparse_int* dbsr_col_ind_A = nullptr;
float* dbsr_val_A = nullptr;
hipMalloc((void**)&dbsr_row_ptr_A, sizeof(rocsparse_int) * (mb_A + 1));
hipMalloc((void**)&dbsr_col_ind_A, sizeof(rocsparse_int) * nnzb_A);
hipMalloc((void**)&dbsr_val_A, sizeof(float) * nnzb_A * row_block_dim_A * col_block_dim_A);

hipMemcpy(dbsr_row_ptr_A, hbsr_row_ptr_A.data(), sizeof(rocsparse_int) * (mb_A + 1), hipMemcpyHostToDevice);
hipMemcpy(dbsr_col_ind_A, hbsr_col_ind_A.data(), sizeof(rocsparse_int) * nnzb_A, hipMemcpyHostToDevice);
hipMemcpy(dbsr_val_A, hbsr_val_A.data(), sizeof(float) * nnzb_A * row_block_dim_A * col_block_dim_A, hipMemcpyHostToDevice);

rocsparse_int row_block_dim_C = 2;
rocsparse_int col_block_dim_C = 3;
rocsparse_int mb_C   = (m + row_block_dim_C - 1) / row_block_dim_C;
rocsparse_int nb_C   = (m + row_block_dim_C - 1) / row_block_dim_C;

rocsparse_int* dbsr_row_ptr_C = nullptr;
hipMalloc((void**)&dbsr_row_ptr_C, sizeof(rocsparse_int) * (mb_C + 1));

rocsparse_handle handle;
rocsparse_create_handle(&handle);

rocsparse_mat_descr descr_A;
rocsparse_create_mat_descr(&descr_A);

rocsparse_mat_descr descr_C;
rocsparse_create_mat_descr(&descr_C);

// Obtain the temporary buffer size
size_t buffer_size;
rocsparse_sgebsr2gebsr_buffer_size(handle,
                                   dir,
                                   mb_A,
                                   nb_A,
                                   nnzb_A,
                                   descr_A,
                                   dbsr_val_A,
                                   dbsr_row_ptr_A,
                                   dbsr_col_ind_A,
                                   row_block_dim_A,
                                   col_block_dim_A,
                                   row_block_dim_C,
                                   col_block_dim_C,
                                   &buffer_size);

// Allocate temporary buffer
void* temp_buffer;
hipMalloc(&temp_buffer, buffer_size);

rocsparse_int nnzb_C;
rocsparse_gebsr2gebsr_nnz(handle,
                        dir,
                        mb_A,
                        nb_A,
                        nnzb_A,
                        descr_A,
                        dbsr_row_ptr_A,
                        dbsr_col_ind_A,
                        row_block_dim_A,
                        col_block_dim_A,
                        descr_C,
                        dbsr_row_ptr_C,
                        row_block_dim_C,
                        col_block_dim_C,
                        &nnzb_C,
                        temp_buffer);

rocsparse_int* dbsr_col_ind_C = nullptr;
float* dbsr_val_C = nullptr;
hipMalloc((void**)&dbsr_col_ind_C, sizeof(rocsparse_int) * nnzb_C);
hipMalloc((void**)&dbsr_val_C, sizeof(float) * nnzb_C * row_block_dim_C * col_block_dim_C);

rocsparse_sgebsr2gebsr(handle,
                       dir,
                       mb_A,
                       nb_A,
                       nnzb_A,
                       descr_A,
                       dbsr_val_A,
                       dbsr_row_ptr_A,
                       dbsr_col_ind_A,
                       row_block_dim_A,
                       col_block_dim_A,
                       descr_C,
                       dbsr_val_C,
                       dbsr_row_ptr_C,
                       dbsr_col_ind_C,
                       row_block_dim_C,
                       col_block_dim_C,
                       temp_buffer);

rocsparse_destroy_handle(handle);
rocsparse_destroy_mat_descr(descr_A);
rocsparse_destroy_mat_descr(descr_C);

hipFree(temp_buffer);

hipFree(dbsr_row_ptr_A);
hipFree(dbsr_col_ind_A);
hipFree(dbsr_val_A);

hipFree(dbsr_row_ptr_C);
hipFree(dbsr_col_ind_C);
hipFree(dbsr_val_C);

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

• dir – [in] the storage format of the blocks, rocsparse_direction_row or rocsparse_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\).

• descr_A – [in] the descriptor of the general BSR sparse matrix \(A\), the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• bsr_val_A – [in] array of nnzb*row_block_dim_A*col_block_dim_A containing the values of the sparse general BSR matrix \(A\).

• bsr_row_ptr_A – [in] array of mb+1 elements that point to the start of every block row of the sparse general BSR matrix \(A\).

• bsr_col_ind_A – [in] array of nnzb elements containing the block column indices of the sparse general BSR matrix \(A\).

• row_block_dim_A – [in] row size of the blocks in the sparse general BSR matrix \(A\).

• col_block_dim_A – [in] column size of the blocks in the sparse general BSR matrix \(A\).

• descr_C – [in] the descriptor of the general BSR sparse matrix \(C\), the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• bsr_val_C – [in] array of nnzb_C*row_block_dim_C*col_block_dim_C containing the values of the sparse general BSR matrix \(C\).

• bsr_row_ptr_C – [in] array of mb_C+1 elements that point to the start of every block row of the sparse general BSR matrix \(C\).

• bsr_col_ind_C – [in] array of nnzb_C elements containing the block column indices of the sparse general BSR matrix \(C\).

• row_block_dim_C – [in] row size of the blocks in the sparse general BSR matrix \(C\).

• col_block_dim_C – [in] column size of the blocks in the sparse general BSR matrix \(C\).

• temp_buffer – [out] buffer allocated by the user whose size is determined by calling rocsparse_Xgebsr2gebsr_buffer_size().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – mb or nb or nnzb or row_block_dim_A or col_block_dim_A or row_block_dim_C or col_block_dim_C is invalid.

• rocsparse_status_invalid_pointer – bsr_row_ptr_A or bsr_col_ind_A or bsr_val_A or bsr_row_ptr_C or bsr_col_ind_C or bsr_val_C or descr_A or descr_C or temp_buffer pointer is invalid.

rocsparse_csr2bsr_nnz()

rocsparse_status rocsparse_csr2bsr_nnz(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr bsr_descr, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_nnz)

This function takes a sparse CSR matrix as input and computes the block row offset array, bsr_row_ptr, and the total number of nonzero blocks, bsr_nnz, that will result from converting the CSR format input matrix to a BSR format output matrix. This function is the first step in the conversion and is used in conjunction with rocsparse_Xcsr2bsr().

Note

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

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

• dir – [in] direction that specified whether to count nonzero elements by rocsparse_direction_row or by rocsparse_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 rocsparse_matrix_type_general is supported.

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

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

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

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

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

• bsr_nnz – [out] total number of nonzero elements in device or host memory.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or block_dim is invalid.

• rocsparse_status_invalid_pointer – csr_row_ptr or csr_col_ind or bsr_row_ptr or bsr_nnz pointer is invalid.

rocsparse_csr2bsr()

rocsparse_status rocsparse_scsr2bsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr bsr_descr, float *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind)

rocsparse_status rocsparse_dcsr2bsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr bsr_descr, double *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind)

rocsparse_status rocsparse_ccsr2bsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr bsr_descr, rocsparse_float_complex *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind)

rocsparse_status rocsparse_zcsr2bsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int block_dim, const rocsparse_mat_descr bsr_descr, rocsparse_double_complex *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind)

Convert a sparse CSR matrix into a sparse BSR matrix.

rocsparse_csr2bsr converts a CSR matrix into a BSR matrix. It is assumed, that bsr_val, bsr_col_ind and bsr_row_ptr are allocated. Allocation size for bsr_row_ptr is computed as mb+1 where mb is the number of block rows and nb is the number of block columns in the BSR matrix:

\[\begin{split} mb = (m + block\_dim - 1) / block\_dim \\ nb = (n + block\_dim - 1) / block\_dim \end{split}\]

Allocation size for bsr_val and bsr_col_ind is computed using rocsparse_csr2bsr_nnz() which also fills in bsr_row_ptr.

Converting from a sparse CSR matrix to a sparse BSR matrix requires two steps. First, the user allocates the bsr_row_ptr array to have length mb+1 and passes this to the function rocsparse_csr2bsr_nnz. This will fill the bsr_row_ptr array and also compute the total number of nonzero blocks in the BSR matrix. Now that the total number of nonzero blocks is known, the user can allocate the bsr_col_ind and bsr_val arrays. Finally, the user calls rocsparse_csr2bsr to complete the conversion. See example below.

rocsparse_csr2bsr requires extra temporary storage that is allocated internally if block_dim>16

Example

This example converts a CSR matrix into an BSR matrix.

//     1 4 0 0 0 0
// A = 0 2 3 0 0 0
//     5 0 0 7 8 0
//     0 0 9 0 6 0

rocsparse_int m   = 4;
rocsparse_int n   = 6;
rocsparse_int block_dim = 2;
rocsparse_int nnz = 9;
rocsparse_int mb = (m + block_dim - 1) / block_dim;
rocsparse_int nb = (n + block_dim - 1) / block_dim;

csr_row_ptr[m+1]  = {0, 2, 4, 7, 9};             // device memory
csr_col_ind[nnz]  = {0, 1, 1, 2, 0, 3, 4, 2, 4}; // device memory
csr_val[nnz]      = {1, 4, 2, 3, 5, 7, 8, 9, 6}; // device memory

hipMalloc(&bsr_row_ptr, sizeof(rocsparse_int) *(mb + 1));
rocsparse_int nnzb;
rocsparse_int* nnzTotalHostPtr = &nnzb;
csr2bsr_nnz(handle,
            rocsparse_direction_row,
            m,
            n,
            csr_descr,
            csr_row_ptr,
            csr_col_ind,
            block_dim,
            bsr_descr,
            bsr_row_ptr,
            nnzTotalHostPtr);
nnzb = *nnzTotalDevHostPtr;
hipMalloc(&bsr_col_ind, sizeof(int)*nnzb);
hipMalloc(&bsr_val, sizeof(float)*(block_dim * block_dim) * nnzb);
scsr2bsr(handle,
         rocsparse_direction_row,
         m,
         n,
         csr_descr,
         csr_val,
         csr_row_ptr,
         csr_col_ind,
         block_dim,
         bsr_descr,
         bsr_val,
         bsr_row_ptr,
         bsr_col_ind);

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

• dir – [in] the storage format of the blocks, rocsparse_direction_row or rocsparse_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 rocsparse_matrix_type_general is supported.

• csr_val – [in] array of nnz elements containing the values of the sparse CSR matrix.

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

• csr_col_ind – [in] array of nnz elements containing the column indices of the sparse CSR matrix.

• block_dim – [in] size of the blocks in the sparse BSR matrix.

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

• bsr_val – [out] array of nnzb*block_dim*block_dim containing the values of the sparse BSR matrix.

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

• bsr_col_ind – [out] array of nnzb elements containing the block column indices of the sparse BSR matrix.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or block_dim is invalid.

• rocsparse_status_invalid_pointer – bsr_val, bsr_row_ptr, bsr_col_ind, csr_val, csr_row_ptr or csr_col_ind pointer is invalid.

rocsparse_csr2gebsr_nnz()

rocsparse_status rocsparse_csr2gebsr_nnz(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr bsr_descr, rocsparse_int *bsr_row_ptr, rocsparse_int row_block_dim, rocsparse_int col_block_dim, rocsparse_int *bsr_nnz_devhost, void *temp_buffer)

This function takes a sparse CSR matrix as input and computes the block row offset array, bsr_row_ptr, and the total number of nonzero blocks, bsr_nnz_devhost, that will result from converting the CSR format input matrix to a GEneral BSR format output matrix. This function is the second step in the conversion and is used in conjunction with rocsparse_Xcsr2gebsr_buffer_size() and rocsparse_Xcsr2gebsr().

rocsparse_csr2gebsr_nnz accepts both host and device pointers for bsr_nnz_devhost which can be set by calling rocsparse_set_pointer_mode prior to calling rocsparse_csr2gebsr_nnz.

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

• dir – [in] direction that specified whether to count nonzero elements by rocsparse_direction_row or by rocsparse_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 rocsparse_matrix_type_general is supported.

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

• csr_col_ind – [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 rocsparse_matrix_type_general is supported.

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

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

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

• bsr_nnz_devhost – [out] total number of nonzero elements in device or host memory.

• temp_buffer – [in] buffer allocated by the user whose size is determined by calling rocsparse_Xcsr2gebsr_buffer_size().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or row_block_dim col_block_dim is invalid.

• rocsparse_status_invalid_pointer – csr_row_ptr or csr_col_ind or bsr_row_ptr or bsr_nnz_devhost pointer is invalid.

rocsparse_csr2gebsr_buffer_size()

rocsparse_status rocsparse_scsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *buffer_size)

rocsparse_status rocsparse_dcsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *buffer_size)

rocsparse_status rocsparse_ccsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *buffer_size)

rocsparse_status rocsparse_zcsr2gebsr_buffer_size(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, size_t *buffer_size)

rocsparse_csr2gebsr_buffer_size returns the size of the temporary buffer that is required by rocsparse_csr2gebsr_nnz and rocsparse_Xcsr2gebsr(). The temporary storage buffer must be allocated by the user.

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• dir – [in] direction that specified whether to count nonzero elements by rocsparse_direction_row or by rocsparse_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 rocsparse_matrix_type_general is supported.

• csr_val – [in] array of nnz elements containing the values of the sparse CSR matrix.

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

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

• row_block_dim – [in] the row block dimension of the GEneral BSR matrix. Between 1 and m

• col_block_dim – [in] the col block dimension of the GEneral BSR matrix. Between 1 and n

• buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_csr2gebsr_nnz and rocsparse_Xcsr2gebsr().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or row_block_dim col_block_dim is invalid.

• rocsparse_status_invalid_pointer – csr_val or csr_row_ptr or csr_col_ind or buffer_size pointer is invalid.

rocsparse_csr2gebsr()

rocsparse_status rocsparse_scsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr bsr_descr, float *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, void *temp_buffer)

rocsparse_status rocsparse_dcsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr bsr_descr, double *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, void *temp_buffer)

rocsparse_status rocsparse_ccsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr bsr_descr, rocsparse_float_complex *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, void *temp_buffer)

rocsparse_status rocsparse_zcsr2gebsr(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr csr_descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, const rocsparse_mat_descr bsr_descr, rocsparse_double_complex *bsr_val, rocsparse_int *bsr_row_ptr, rocsparse_int *bsr_col_ind, rocsparse_int row_block_dim, rocsparse_int col_block_dim, void *temp_buffer)

Convert a sparse CSR matrix into a sparse GEneral BSR matrix.

rocsparse_csr2gebsr converts a CSR matrix into a GEneral BSR matrix. It is assumed, that bsr_val, bsr_col_ind and bsr_row_ptr are allocated. Allocation size for bsr_row_ptr is computed as mb+1 where mb is the number of block rows and nb is the number of block columns in the GEneral BSR matrix:

\[\begin{split} mb = (m + row\_block\_dim - 1) / row\_block\_dim \\ nb = (n + col\_block\_dim - 1) / col\_block\_dim \end{split}\]

Allocation size for bsr_val and bsr_col_ind is computed using rocsparse_csr2bsr_nnz() which also fills in bsr_row_ptr.

Converting from a sparse CSR matrix to a sparse GEneral BSR matrix requires three steps. First, the user calls rocsparse_Xcsr2gebsr_buffer_size() in order to determine the size of the required temporary storage buffer. Once this has been determined, the user allocates this buffer. The user also now allocates the bsr_row_ptr array to have length mb+1 and passes this to the function rocsparse_csr2gebsr_nnz. This will fill the bsr_row_ptr array and also compute the total number of nonzero blocks in the GEneral BSR matrix. Now that the total number of nonzero blocks is known, the user can allocate the bsr_col_ind and bsr_val arrays. Finally, the user calls rocsparse_csr2gebsr to complete the conversion. See example below.

Example

This example converts a CSR matrix into an BSR matrix.

//     1 4 0 0 0 0
// A = 0 2 3 0 0 0
//     5 0 0 7 8 0
//     0 0 9 0 6 0

rocsparse_int m   = 4;
rocsparse_int n   = 6;
rocsparse_int row_block_dim = 2;
rocsparse_int col_block_dim = 3;
rocsparse_int nnz = 9;
rocsparse_int mb = (m + row_block_dim - 1) / row_block_dim;
rocsparse_int nb = (n + col_block_dim - 1) / col_block_dim;

rocsparse_direction dir = rocsparse_direction_row;

std::vector<rocsparse_int> hcsr_row_ptr = {0, 2, 4, 7, 9};
std::vector<rocsparse_int> hcsr_col_ind = {0, 1, 1, 2, 0, 3, 4, 2, 4};
std::vector<float> hcsr_val = {1, 4, 2, 3, 5, 7, 8, 9, 6};

rocsparse_int* dcsr_row_ptr = nullptr;
rocsparse_int* dcsr_col_ind = nullptr;
float* dcsr_val = nullptr;

hipMalloc((void**)&dcsr_row_ptr, sizeof(rocsparse_int) * (m + 1));
hipMalloc((void**)&dcsr_col_ind, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&dcsr_val, sizeof(float) * nnz);

hipMemcpy(dcsr_row_ptr, hcsr_row_ptr.data(), sizeof(rocsparse_int) * (m + 1), hipMemcpyHostToDevice);
hipMemcpy(dcsr_col_ind, hcsr_col_ind.data(), sizeof(rocsparse_int) * nnz, hipMemcpyHostToDevice);
hipMemcpy(dcsr_val, hcsr_val.data(), sizeof(float) * nnz, hipMemcpyHostToDevice);

rocsparse_handle handle;
rocsparse_create_handle(&handle);

rocsparse_mat_descr csr_descr;
rocsparse_create_mat_descr(&csr_descr);

rocsparse_mat_descr bsr_descr;
rocsparse_create_mat_descr(&bsr_descr);

size_t buffer_size;
rocsparse_scsr2gebsr_buffer_size(handle,
                                 dir,
                                 m,
                                 n,
                                 csr_descr,
                                 dcsr_val,
                                 dcsr_row_ptr,
                                 dcsr_col_ind,
                                 row_block_dim,
                                 col_block_dim,
                                 &buffer_size);

void* buffer = nullptr;
hipMalloc((void**)&buffer, buffer_size);

rocsparse_int* dbsr_row_ptr = nullptr;
hipMalloc(&dbsr_row_ptr, sizeof(rocsparse_int) *(mb + 1));

rocsparse_int nnzb;
rocsparse_csr2gebsr_nnz(handle,
                        dir,
                        m,
                        n,
                        csr_descr,
                        dcsr_row_ptr,
                        dcsr_col_ind,
                        bsr_descr,
                        dbsr_row_ptr,
                        row_block_dim,
                        col_block_dim,
                        &nnzb,
                        buffer);
         
rocsparse_int* dbsr_col_ind = nullptr;
float* dbsr_val = nullptr;
hipMalloc((void**)&dbsr_col_ind, sizeof(rocsparse_int) * nnzb);
hipMalloc((void**)&dbsr_val, sizeof(float) * nnzb * row_block_dim * col_block_dim);

rocsparse_scsr2gebsr(handle,
                     dir,
                     m,
                     n,
                     csr_descr,
                     dcsr_val,
                     dcsr_row_ptr,
                     dcsr_col_ind,
                     bsr_descr,
                     dbsr_val,
                     dbsr_row_ptr,
                     dbsr_col_ind,
                     row_block_dim,
                     col_block_dim,
                     buffer);

hipFree(buffer);

hipFree(dcsr_row_ptr);
hipFree(dcsr_col_ind);
hipFree(dcsr_val);

hipFree(dbsr_row_ptr);
hipFree(dbsr_col_ind);
hipFree(dbsr_val);

rocsparse_destroy_mat_descr(csr_descr);
rocsparse_destroy_mat_descr(bsr_descr);

rocsparse_destroy_handle(handle);

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

• dir – [in] the storage format of the blocks, rocsparse_direction_row or rocsparse_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 rocsparse_matrix_type_general is supported.

• csr_val – [in] array of nnz elements containing the values of the sparse CSR matrix.

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

• csr_col_ind – [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 rocsparse_matrix_type_general is supported.

• bsr_val – [out] array of nnzb* row_block_dim* col_block_dim containing the values of the sparse BSR matrix.

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

• bsr_col_ind – [out] array of nnzb elements containing the block column indices of the sparse BSR matrix.

• row_block_dim – [in] row size of the blocks in the sparse GEneral BSR matrix.

• col_block_dim – [in] col size of the blocks in the sparse GEneral BSR matrix.

• temp_buffer – [in] buffer allocated by the user whose size is determined by calling rocsparse_Xcsr2gebsr_buffer_size().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or row_block_dim or col_block_dim is invalid.

• rocsparse_status_invalid_pointer – bsr_val, bsr_row_ptr, bsr_col_ind, csr_val, csr_row_ptr or csr_col_ind pointer is invalid.

rocsparse_csr2csr_compress()

rocsparse_status rocsparse_scsr2csr_compress(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, rocsparse_int nnz_A, const rocsparse_int *nnz_per_row, float *csr_val_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, float tol)

rocsparse_status rocsparse_dcsr2csr_compress(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, rocsparse_int nnz_A, const rocsparse_int *nnz_per_row, double *csr_val_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, double tol)

rocsparse_status rocsparse_ccsr2csr_compress(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr_A, const rocsparse_float_complex *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, rocsparse_int nnz_A, const rocsparse_int *nnz_per_row, rocsparse_float_complex *csr_val_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, rocsparse_float_complex tol)

rocsparse_status rocsparse_zcsr2csr_compress(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr_A, const rocsparse_double_complex *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, rocsparse_int nnz_A, const rocsparse_int *nnz_per_row, rocsparse_double_complex *csr_val_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, rocsparse_double_complex tol)

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

rocsparse_csr2csr_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

Compressing a CSR matrix involves two steps. First we use rocsparse_Xnnz_compress() to determine how many entries will be in the final compressed CSR matrix. Then we call rocsparse_csr2csr_compress to finish the compression and fill in the column indices and values arrays of the compressed CSR matrix.

Example

This example demonstrates how to compress a CSR matrix.

//     1 2 0 3 0
// A = 0 4 5 0 0
//     6 0 0 7 8

float tol = 0.0f;

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

csr_row_ptr_A[m+1]   = {0, 3, 5, 8};             // device memory
csr_col_ind_A[nnz_A] = {0, 1, 3, 1, 2, 0, 3, 4}; // device memory
csr_val_A[nnz_A]     = {1, 0, 3, 4, 0, 6, 7, 0}; // device memory

// Allocate memory for the row pointer array of the compressed CSR matrix
rocsparse_int* csr_row_ptr_C;
hipMalloc(csr_row_ptr_C, sizeof(rocsparse_int) * (m + 1));

// Allocate memory for the nnz_per_row array
rocsparse_int* nnz_per_row;
hipMalloc(nnz_per_row, sizeof(rocsparse_int) * m);

// Call nnz_compress() which fills in nnz_per_row array and finds the number
// of entries that will be in the compressed CSR matrix
rocsparse_int nnz_C;
nnz_compress(handle,
             m,
             descr_A,
             csr_val_A,
             csr_row_ptr_A,
             nnz_per_row,
             &nnz_C,
             tol);

// Allocate column indices and values array for the compressed CSR matrix
rocsparse_int* csr_col_ind_C;
rocsparse_int* csr_val_C;
hipMalloc(csr_col_ind_C, sizeof(rocsparse_int) * nnz_C;
hipMalloc(csr_val_C, sizeof(rocsparse_int) * nnz_C;

// Finish compression by calling csr2csr_compress()
csr2csr_compress(handle,
                 m,
                 n,
                 descr_A,
                 csr_val_A,
                 csr_row_ptr_A,
                 csr_col_ind_A,
                 nnz_A,
                 nnz_per_row,
                 csr_val_C,
                 csr_row_ptr_C,
                 csr_col_ind_C,
                 tol);

Note

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

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

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

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

• descr_A – [in] matrix descriptor for the CSR matrix

• csr_val_A – [in] array of nnz_A elements of the sparse CSR matrix.

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

• csr_col_ind_A – [in] array of nnz_A elements containing the column indices of the uncompressed sparse CSR matrix.

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

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

• csr_val_C – [out] array of nnz_C elements of the compressed sparse CSC matrix.

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

• csr_col_ind_C – [out] array of nnz_C 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:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m, n or nnz_A is invalid.

• rocsparse_status_invalid_value – tol is invalid.

• rocsparse_status_invalid_pointer – csr_val_A, csr_row_ptr_A, csr_col_ind_A, csr_val_C, csr_row_ptr_C, csr_col_ind_C or nnz_per_row pointer is invalid.

rocsparse_inverse_permutation()

rocsparse_status rocsparse_inverse_permutation(rocsparse_handle handle, rocsparse_int n, const rocsparse_int *p, rocsparse_int *q, rocsparse_index_base base)

Inverse a permutation vector.

rocsparse_inverse_permutation computes

for(i = 0; i < n; ++i)
{
    q[p[i]- base] = i + base;
}

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• n – [in] size of the permutation vector p.

• p – [in] array of n integers containing the permutation vector to inverse.

• q – [out] array of n integers containing the invsrse of the permutation vector.

• base – [in] rocsparse_index_base_zero or rocsparse_index_base_one.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – n is invalid.

• rocsparse_status_invalid_pointer – p pointer is invalid or q pointer is invalid.

• rocsparse_status_invalid_value – base is invalid.

rocsparse_create_identity_permutation()

rocsparse_status rocsparse_create_identity_permutation(rocsparse_handle handle, rocsparse_int n, rocsparse_int *p)

Create the identity map.

rocsparse_create_identity_permutation stores the identity map in p, such that \(p = 0:1:(n-1)\).

for(i = 0; i < n; ++i)
{
    p[i] = i;
}

Example

The following example creates an identity permutation.

rocsparse_int size = 200;

// Allocate memory to hold the identity map
rocsparse_int* perm;
hipMalloc((void**)&perm, sizeof(rocsparse_int) * size);

// Fill perm with the identity permutation
rocsparse_create_identity_permutation(handle, size, perm);

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• n – [in] size of the map p.

• p – [out] array of n integers containing the map.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – n is invalid.

• rocsparse_status_invalid_pointer – p pointer is invalid.

rocsparse_csrsort_buffer_size()

rocsparse_status rocsparse_csrsort_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, size_t *buffer_size)

rocsparse_csrsort_buffer_size returns the size of the temporary storage buffer required by rocsparse_csrsort(). The temporary storage buffer must be allocated by the user.

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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.

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

• csr_col_ind – [in] array of nnz elements containing the column indices of the sparse CSR matrix.

• buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_csrsort().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m, n or nnz is invalid.

• rocsparse_status_invalid_pointer – csr_row_ptr, csr_col_ind or buffer_size pointer is invalid.

rocsparse_csrsort()

rocsparse_status rocsparse_csrsort(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, rocsparse_int *perm, void *temp_buffer)

Sort a sparse CSR matrix.

rocsparse_csrsort sorts a matrix in CSR format. The sorted permutation vector perm can be used to obtain sorted csr_val array. In this case, perm must be initialized as the identity permutation, see rocsparse_create_identity_permutation().

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

Example

The following example sorts a \(3 \times 3\) CSR matrix.

//     1 2 3
// A = 4 5 6
//     7 8 9
rocsparse_int m   = 3;
rocsparse_int n   = 3;
rocsparse_int nnz = 9;

csr_row_ptr[m + 1] = {0, 3, 6, 9};                // device memory
csr_col_ind[nnz]   = {2, 0, 1, 0, 1, 2, 0, 2, 1}; // device memory
csr_val[nnz]       = {3, 1, 2, 4, 5, 6, 7, 9, 8}; // device memory

// Create permutation vector perm as the identity map
rocsparse_int* perm;
hipMalloc((void**)&perm, sizeof(rocsparse_int) * nnz);
rocsparse_create_identity_permutation(handle, nnz, perm);

// Allocate temporary buffer
size_t buffer_size;
void* temp_buffer;
rocsparse_csrsort_buffer_size(handle, m, n, nnz, csr_row_ptr, csr_col_ind, &buffer_size);
hipMalloc(&temp_buffer, buffer_size);

// Sort the CSR matrix
rocsparse_csrsort(handle, m, n, nnz, descr, csr_row_ptr, csr_col_ind, perm, temp_buffer);

// Gather sorted csr_val array
float* csr_val_sorted;
hipMalloc((void**)&csr_val_sorted, sizeof(float) * nnz);
rocsparse_sgthr(handle, nnz, csr_val, csr_val_sorted, perm, rocsparse_index_base_zero);

// Clean up
hipFree(temp_buffer);
hipFree(perm);
hipFree(csr_val);

Note

perm 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.

Note

This routine does not support execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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.

• descr – [in] descriptor of the sparse CSR matrix. Currently, only rocsparse_matrix_type_general is supported.

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

• csr_col_ind – [inout] array of nnz elements containing the column indices of the sparse CSR matrix.

• perm – [inout] array of nnz integers containing the unsorted map indices, can be NULL.

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

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m, n or nnz is invalid.

• rocsparse_status_invalid_pointer – descr, csr_row_ptr, csr_col_ind or temp_buffer pointer is invalid.

• rocsparse_status_internal_error – an internal error occurred.

• rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

rocsparse_cscsort_buffer_size()

rocsparse_status rocsparse_cscsort_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, size_t *buffer_size)

rocsparse_cscsort_buffer_size returns the size of the temporary storage buffer required by rocsparse_cscsort(). The temporary storage buffer must be allocated by the user.

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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.

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

• csc_row_ind – [in] array of nnz elements containing the row indices of the sparse CSC matrix.

• buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_cscsort().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m, n or nnz is invalid.

• rocsparse_status_invalid_pointer – csc_col_ptr, csc_row_ind or buffer_size pointer is invalid.

rocsparse_cscsort()

rocsparse_status rocsparse_cscsort(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_int *csc_col_ptr, rocsparse_int *csc_row_ind, rocsparse_int *perm, void *temp_buffer)

Sort a sparse CSC matrix.

rocsparse_cscsort sorts a matrix in CSC format. The sorted permutation vector perm can be used to obtain sorted csc_val array. In this case, perm must be initialized as the identity permutation, see rocsparse_create_identity_permutation().

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

Example

The following example sorts a \(3 \times 3\) CSC matrix.

//     1 2 3
// A = 4 5 6
//     7 8 9
rocsparse_int m   = 3;
rocsparse_int n   = 3;
rocsparse_int nnz = 9;

csc_col_ptr[m + 1] = {0, 3, 6, 9};                // device memory
csc_row_ind[nnz]   = {2, 0, 1, 0, 1, 2, 0, 2, 1}; // device memory
csc_val[nnz]       = {7, 1, 4, 2, 5, 8, 3, 9, 6}; // device memory

// Create permutation vector perm as the identity map
rocsparse_int* perm;
hipMalloc((void**)&perm, sizeof(rocsparse_int) * nnz);
rocsparse_create_identity_permutation(handle, nnz, perm);

// Allocate temporary buffer
size_t buffer_size;
void* temp_buffer;
rocsparse_cscsort_buffer_size(handle, m, n, nnz, csc_col_ptr, csc_row_ind, &buffer_size);
hipMalloc(&temp_buffer, buffer_size);

// Sort the CSC matrix
rocsparse_cscsort(handle, m, n, nnz, descr, csc_col_ptr, csc_row_ind, perm, temp_buffer);

// Gather sorted csc_val array
float* csc_val_sorted;
hipMalloc((void**)&csc_val_sorted, sizeof(float) * nnz);
rocsparse_sgthr(handle, nnz, csc_val, csc_val_sorted, perm, rocsparse_index_base_zero);

// Clean up
hipFree(temp_buffer);
hipFree(perm);
hipFree(csc_val);

Note

perm 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.

Note

This routine does not support execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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.

• descr – [in] descriptor of the sparse CSC matrix. Currently, only rocsparse_matrix_type_general is supported.

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

• csc_row_ind – [inout] array of nnz elements containing the row indices of the sparse CSC matrix.

• perm – [inout] array of nnz integers containing the unsorted map indices, can be NULL.

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

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m, n or nnz is invalid.

• rocsparse_status_invalid_pointer – descr, csc_col_ptr, csc_row_ind or temp_buffer pointer is invalid.

• rocsparse_status_internal_error – an internal error occurred.

• rocsparse_status_not_implemented – rocsparse_matrix_type != rocsparse_matrix_type_general.

rocsparse_coosort_buffer_size()

rocsparse_status rocsparse_coosort_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, size_t *buffer_size)

rocsparse_coosort_buffer_size returns the size of the temporary storage buffer that is required by rocsparse_coosort_by_row() and rocsparse_coosort_by_column(). The temporary storage buffer has to be allocated by the user.

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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.

• coo_row_ind – [in] array of nnz elements containing the row indices of the sparse COO matrix.

• coo_col_ind – [in] array of nnz elements containing the column indices of the sparse COO matrix.

• buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_coosort_by_row() and rocsparse_coosort_by_column().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m, n or nnz is invalid.

• rocsparse_status_invalid_pointer – coo_row_ind, coo_col_ind or buffer_size pointer is invalid.

• rocsparse_status_internal_error – an internal error occurred.

rocsparse_coosort_by_row()

rocsparse_status rocsparse_coosort_by_row(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, rocsparse_int *coo_row_ind, rocsparse_int *coo_col_ind, rocsparse_int *perm, void *temp_buffer)

Sort a sparse COO matrix by row.

rocsparse_coosort_by_row sorts a matrix in COO format by row. The sorted permutation vector perm can be used to obtain sorted coo_val array. In this case, perm must be initialized as the identity permutation, see rocsparse_create_identity_permutation().

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

Example

The following example sorts a \(3 \times 3\) COO matrix by row indices.

//     1 2 3
// A = 4 5 6
//     7 8 9
rocsparse_int m   = 3;
rocsparse_int n   = 3;
rocsparse_int nnz = 9;

coo_row_ind[nnz] = {0, 1, 2, 0, 1, 2, 0, 1, 2}; // device memory
coo_col_ind[nnz] = {0, 0, 0, 1, 1, 1, 2, 2, 2}; // device memory
coo_val[nnz]     = {1, 4, 7, 2, 5, 8, 3, 6, 9}; // device memory

// Create permutation vector perm as the identity map
rocsparse_int* perm;
hipMalloc((void**)&perm, sizeof(rocsparse_int) * nnz);
rocsparse_create_identity_permutation(handle, nnz, perm);

// Allocate temporary buffer
size_t buffer_size;
void* temp_buffer;
rocsparse_coosort_buffer_size(handle,
                              m,
                              n,
                              nnz,
                              coo_row_ind,
                              coo_col_ind,
                              &buffer_size);
hipMalloc(&temp_buffer, buffer_size);

// Sort the COO matrix
rocsparse_coosort_by_row(handle,
                         m,
                         n,
                         nnz,
                         coo_row_ind,
                         coo_col_ind,
                         perm,
                         temp_buffer);

// Gather sorted coo_val array
float* coo_val_sorted;
hipMalloc((void**)&coo_val_sorted, sizeof(float) * nnz);
rocsparse_sgthr(handle, nnz, coo_val, coo_val_sorted, perm, rocsparse_index_base_zero);

// Clean up
hipFree(temp_buffer);
hipFree(perm);
hipFree(coo_val);

Note

perm 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.

Note

This routine does not support execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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.

• coo_row_ind – [inout] array of nnz elements containing the row indices of the sparse COO matrix.

• coo_col_ind – [inout] array of nnz elements containing the column indices of the sparse COO matrix.

• perm – [inout] array of nnz integers containing the unsorted map indices, can be NULL.

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

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m, n or nnz is invalid.

• rocsparse_status_invalid_pointer – coo_row_ind, coo_col_ind or temp_buffer pointer is invalid.

• rocsparse_status_internal_error – an internal error occurred.

rocsparse_coosort_by_column()

rocsparse_status rocsparse_coosort_by_column(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, rocsparse_int *coo_row_ind, rocsparse_int *coo_col_ind, rocsparse_int *perm, void *temp_buffer)

Sort a sparse COO matrix by column.

rocsparse_coosort_by_column sorts a matrix in COO format by column. The sorted permutation vector perm can be used to obtain sorted coo_val array. In this case, perm must be initialized as the identity permutation, see rocsparse_create_identity_permutation().

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

Example

The following example sorts a \(3 \times 3\) COO matrix by column indices.

//     1 2 3
// A = 4 5 6
//     7 8 9
rocsparse_int m   = 3;
rocsparse_int n   = 3;
rocsparse_int nnz = 9;

coo_row_ind[nnz] = {0, 0, 0, 1, 1, 1, 2, 2, 2}; // device memory
coo_col_ind[nnz] = {0, 1, 2, 0, 1, 2, 0, 1, 2}; // device memory
coo_val[nnz]     = {1, 2, 3, 4, 5, 6, 7, 8, 9}; // device memory

// Create permutation vector perm as the identity map
rocsparse_int* perm;
hipMalloc((void**)&perm, sizeof(rocsparse_int) * nnz);
rocsparse_create_identity_permutation(handle, nnz, perm);

// Allocate temporary buffer
size_t buffer_size;
void* temp_buffer;
rocsparse_coosort_buffer_size(handle,
                              m,
                              n,
                              nnz,
                              coo_row_ind,
                              coo_col_ind,
                              &buffer_size);
hipMalloc(&temp_buffer, buffer_size);

// Sort the COO matrix
rocsparse_coosort_by_column(handle,
                            m,
                            n,
                            nnz,
                            coo_row_ind,
                            coo_col_ind,
                            perm,
                            temp_buffer);

// Gather sorted coo_val array
float* coo_val_sorted;
hipMalloc((void**)&coo_val_sorted, sizeof(float) * nnz);
rocsparse_sgthr(handle, nnz, coo_val, coo_val_sorted, perm, rocsparse_index_base_zero);

// Clean up
hipFree(temp_buffer);
hipFree(perm);
hipFree(coo_val);

Note

perm 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.

Note

This routine does not support execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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.

• coo_row_ind – [inout] array of nnz elements containing the row indices of the sparse COO matrix.

• coo_col_ind – [inout] array of nnz elements containing the column indices of the sparse COO matrix.

• perm – [inout] array of nnz integers containing the unsorted map indices, can be NULL.

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

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m, n or nnz is invalid.

• rocsparse_status_invalid_pointer – coo_row_ind, coo_col_ind or temp_buffer pointer is invalid.

• rocsparse_status_internal_error – an internal error occurred.

rocsparse_nnz_compress()

rocsparse_status rocsparse_snnz_compress(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, rocsparse_int *nnz_per_row, rocsparse_int *nnz_C, float tol)

rocsparse_status rocsparse_dnnz_compress(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, rocsparse_int *nnz_per_row, rocsparse_int *nnz_C, double tol)

rocsparse_status rocsparse_cnnz_compress(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr descr_A, const rocsparse_float_complex *csr_val_A, const rocsparse_int *csr_row_ptr_A, rocsparse_int *nnz_per_row, rocsparse_int *nnz_C, rocsparse_float_complex tol)

rocsparse_status rocsparse_znnz_compress(rocsparse_handle handle, rocsparse_int m, const rocsparse_mat_descr descr_A, const rocsparse_double_complex *csr_val_A, const rocsparse_int *csr_row_ptr_A, rocsparse_int *nnz_per_row, rocsparse_int *nnz_C, rocsparse_double_complex tol)

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.

Example

// rocSPARSE handle
rocsparse_handle handle;
rocsparse_create_handle(&handle);

// Matrix descriptor
rocsparse_mat_descr descr_A;
rocsparse_create_mat_descr(&descr_A);

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

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

rocsparse_int hcsr_row_ptr_A[4] = {0, 3, 5, 8};
float hcsr_val_A[8]   = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f};

rocsparse_int* dcsr_row_ptr_A = nullptr;
float* dcsr_val_A = nullptr;
hipMalloc((void**)&dcsr_row_ptr_A, sizeof(rocsparse_int) * (m + 1));
hipMalloc((void**)&dcsr_val_A, sizeof(float) * nnz_A);

hipMemcpy(dcsr_row_ptr_A, hcsr_row_ptr_A, sizeof(rocsparse_int) * (m + 1), hipMemcpyHostToDevice);
hipMemcpy(dcsr_val_A, hcsr_val_A, sizeof(float) * nnz_A, hipMemcpyHostToDevice);

// Allocate memory for the nnz_per_row array
rocsparse_int* dnnz_per_row;
hipMalloc((void**)&dnnz_per_row, sizeof(rocsparse_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
rocsparse_int nnz_C;
rocsparse_snnz_compress(handle, m, descr_A, dcsr_val_A, dcsr_row_ptr_A, dnnz_per_row, &nnz_C, tol);

// Copy result back to host
rocsparse_int hnnz_per_row[3];
hipMemcpy(hnnz_per_row, dnnz_per_row, sizeof(rocsparse_int) * m, hipMemcpyDeviceToHost);

hipFree(dcsr_row_ptr_A);
hipFree(dcsr_val_A);
hipFree(dnnz_per_row);

rocsparse_destroy_mat_descr(descr_A);
rocsparse_destroy_handle(handle);

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

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

• descr_A – [in] the descriptor of the sparse CSR matrix.

• csr_val_A – [in] array of nnz_A elements of the sparse CSR matrix.

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

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

• nnz_C – [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:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n is invalid.

• rocsparse_status_invalid_value – tol is invalid.

• rocsparse_status_invalid_pointer – csr_val_A or csr_row_ptr_A or nnz_per_row or nnz_C pointer is invalid.

rocsparse_nnz()

rocsparse_status rocsparse_snnz(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const float *A, rocsparse_int ld, rocsparse_int *nnz_per_row_columns, rocsparse_int *nnz_total_dev_host_ptr)

rocsparse_status rocsparse_dnnz(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const double *A, rocsparse_int ld, rocsparse_int *nnz_per_row_columns, rocsparse_int *nnz_total_dev_host_ptr)

rocsparse_status rocsparse_cnnz(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_float_complex *A, rocsparse_int ld, rocsparse_int *nnz_per_row_columns, rocsparse_int *nnz_total_dev_host_ptr)

rocsparse_status rocsparse_znnz(rocsparse_handle handle, rocsparse_direction dir, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_double_complex *A, rocsparse_int ld, rocsparse_int *nnz_per_row_columns, rocsparse_int *nnz_total_dev_host_ptr)

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

Example

// rocSPARSE handle
rocsparse_handle handle;
rocsparse_create_handle(&handle);

// Matrix descriptor
rocsparse_mat_descr descr;
rocsparse_create_mat_descr(&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};

rocsparse_int m         = 3;
rocsparse_int n         = 5;
rocsparse_direction dir = rocsparse_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
rocsparse_int* dnnz_per_row;
hipMalloc((void**)&dnnz_per_row, sizeof(rocsparse_int) * m);

rocsparse_int nnz_A;
rocsparse_snnz(handle, dir, m, n, descr, ddense_A, m, dnnz_per_row, &nnz_A);

// Copy result back to host
rocsparse_int hnnz_per_row[3];
hipMemcpy(hnnz_per_row, dnnz_per_row, sizeof(rocsparse_int) * m, hipMemcpyDeviceToHost);

hipFree(ddense_A);
hipFree(dnnz_per_row);

rocsparse_destroy_mat_descr(descr);
rocsparse_destroy_handle(handle);

Note

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

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

• dir – [in] direction that specified whether to count nonzero elements by rocsparse_direction_row or by rocsparse_direction_column.

• 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.

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

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

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

• nnz_total_dev_host_ptr – [out] total number of nonzero elements in device or host memory.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or ld is invalid.

• rocsparse_status_invalid_pointer – A or nnz_per_row_columns or nnz_total_dev_host_ptr pointer is invalid.

rocsparse_dense2csr()

rocsparse_status rocsparse_sdense2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const float *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, float *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_ddense2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const double *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, double *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_cdense2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_float_complex *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, rocsparse_float_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

rocsparse_status rocsparse_zdense2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_double_complex *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, rocsparse_double_complex *csr_val, rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind)

This function converts the matrix \(A\) in column-oriented dense format into a sparse matrix in CSR format. All the parameters are assumed to have been pre-allocated by the user and the arrays are filled in based on nnz_per_row, which can be pre-computed with rocsparse_Xnnz().

Example

// rocSPARSE handle
rocsparse_handle handle;
rocsparse_create_handle(&handle);

// Matrix descriptor
rocsparse_mat_descr descr;
rocsparse_create_mat_descr(&descr);

// Column-Oriented 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};

rocsparse_int m         = 3;
rocsparse_int n         = 5;
rocsparse_direction dir = rocsparse_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
rocsparse_int* dnnz_per_row;
hipMalloc((void**)&dnnz_per_row, sizeof(rocsparse_int) * m);

rocsparse_int nnz_A;
rocsparse_snnz(handle, dir, m, n, descr, ddense_A, m, dnnz_per_row, &nnz_A);

// Allocate sparse CSR matrix
rocsparse_int* dcsr_row_ptr = nullptr;
rocsparse_int* dcsr_col_ind = nullptr;
float* dcsr_val = nullptr;
hipMalloc((void**)&dcsr_row_ptr, sizeof(rocsparse_int) * (m + 1));
hipMalloc((void**)&dcsr_col_ind, sizeof(rocsparse_int) * nnz_A);
hipMalloc((void**)&dcsr_val, sizeof(float) * nnz_A);

rocsparse_sdense2csr(handle, m, n, descr, ddense_A, m, dnnz_per_row, dcsr_val, dcsr_row_ptr, dcsr_col_ind);

hipFree(dcsr_row_ptr);
hipFree(dcsr_col_ind);
hipFree(dcsr_val);
hipFree(dnnz_per_row);

rocsparse_destroy_mat_descr(descr);
rocsparse_destroy_handle(handle);

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

• m – [in] number of rows of the column-oriented dense matrix A.

• n – [in] number of columns of the column-oriented dense dense matrix A.

• descr – [in] the descriptor of the column-oriented dense matrix A, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• A – [in] column-oriented dense matrix of dimensions (ld, n)

• ld – [in] leading dimension of column-oriented dense matrix A.

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

• csr_val – [out] array of nnz ( = csr_row_ptr[m] - csr_row_ptr[0] ) nonzero elements of matrix A.

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

• csr_col_ind – [out] integer array of nnz ( = csr_row_ptr[m] - csr_row_ptr[0] ) column indices of the non-zero elements of matrix A.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or ld is invalid.

• rocsparse_status_invalid_pointer – A or nnz_per_rows or csr_val csr_row_ptr or csr_col_ind pointer is invalid.

rocsparse_dense2csc()

rocsparse_status rocsparse_sdense2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const float *A, rocsparse_int ld, const rocsparse_int *nnz_per_columns, float *csc_val, rocsparse_int *csc_col_ptr, rocsparse_int *csc_row_ind)

rocsparse_status rocsparse_ddense2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const double *A, rocsparse_int ld, const rocsparse_int *nnz_per_columns, double *csc_val, rocsparse_int *csc_col_ptr, rocsparse_int *csc_row_ind)

rocsparse_status rocsparse_cdense2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_float_complex *A, rocsparse_int ld, const rocsparse_int *nnz_per_columns, rocsparse_float_complex *csc_val, rocsparse_int *csc_col_ptr, rocsparse_int *csc_row_ind)

rocsparse_status rocsparse_zdense2csc(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_double_complex *A, rocsparse_int ld, const rocsparse_int *nnz_per_columns, rocsparse_double_complex *csc_val, rocsparse_int *csc_col_ptr, rocsparse_int *csc_row_ind)

This function converts the matrix \(A\) in column-oriented dense format into a sparse matrix in CSC format. All the parameters are assumed to have been pre-allocated by the user and the arrays are filled in based on nnz_per_columns, which can be pre-computed with rocsparse_Xnnz().

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

• m – [in] number of rows of the column-oriented dense matrix A.

• n – [in] number of columns of the column-oriented dense matrix A.

• descr – [in] the descriptor of the column-oriented dense matrix A, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• A – [in] column-oriented dense matrix of dimensions (ld, n)

• ld – [in] leading dimension of the column-oriented dense matrix A.

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

• csc_val – [out] array of nnz ( = csc_col_ptr[n] - csc_col_ptr[0] ) nonzero elements of matrix A.

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

• csc_row_ind – [out] integer array of nnz ( = csc_col_ptr[n] - csc_col_ptr[0] ) column indices of the non-zero elements of matrix A.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or ld is invalid.

• rocsparse_status_invalid_pointer – A or nnz_per_columns or csc_val csc_col_ptr or csc_row_ind pointer is invalid.

rocsparse_dense2coo()

rocsparse_status rocsparse_sdense2coo(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const float *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, float *coo_val, rocsparse_int *coo_row_ind, rocsparse_int *coo_col_ind)

rocsparse_status rocsparse_ddense2coo(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const double *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, double *coo_val, rocsparse_int *coo_row_ind, rocsparse_int *coo_col_ind)

rocsparse_status rocsparse_cdense2coo(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_float_complex *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, rocsparse_float_complex *coo_val, rocsparse_int *coo_row_ind, rocsparse_int *coo_col_ind)

rocsparse_status rocsparse_zdense2coo(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_double_complex *A, rocsparse_int ld, const rocsparse_int *nnz_per_rows, rocsparse_double_complex *coo_val, rocsparse_int *coo_row_ind, rocsparse_int *coo_col_ind)

This function converts the matrix \(A\) in column-oriented dense format into a sparse matrix in COO format. All the parameters are assumed to have been pre-allocated by the user and the arrays are filled in based on nnz_per_rows, which can be pre-computed with rocsparse_Xnnz().

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

• m – [in] number of rows of the column-oriented dense matrix A.

• n – [in] number of columns of the column-oriented dense matrix A.

• descr – [in] the descriptor of the column-oriented dense matrix A, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• A – [in] column-oriented dense matrix of dimensions (ld, n)

• ld – [in] leading dimension of column-oriented dense matrix A.

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

• coo_val – [out] array of nnz nonzero elements of matrix A.

• coo_row_ind – [out] integer array of nnz row indices of the non-zero elements of matrix A.

• coo_col_ind – [out] integer array of nnz column indices of the non-zero elements of matrix A.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or ld is invalid.

• rocsparse_status_invalid_pointer – A or nnz_per_rows or coo_val coo_col_ind or coo_row_ind pointer is invalid.

rocsparse_csr2dense()

rocsparse_status rocsparse_scsr2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, float *A, rocsparse_int ld)

rocsparse_status rocsparse_dcsr2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, double *A, rocsparse_int ld)

rocsparse_status rocsparse_ccsr2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_float_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_float_complex *A, rocsparse_int ld)

rocsparse_status rocsparse_zcsr2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_double_complex *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_double_complex *A, rocsparse_int ld)

This function converts the sparse matrix in CSR format into a column-oriented dense matrix.

Example

// 1 2 3 0
// 0 0 4 5
// 0 6 0 0
// 7 0 0 8
rocsparse_int m = 4;
rocsparse_int n = 4;
rocsparse_int nnz = 8;
rocsparse_int ld = m;

std::vector<rocsparse_int> hcsr_row_ptr = {0, 3, 5, 6, 8};
std::vector<rocsparse_int> hcsr_col_ind = {0, 1, 2, 2, 3, 1, 0, 3};
std::vector<float> hcsr_val = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f};

rocsparse_int* dcsr_row_ptr = nullptr;
rocsparse_int* dcsr_col_ind = nullptr;
float* dcsr_val = nullptr;
hipMalloc((void**)&dcsr_row_ptr, sizeof(rocsparse_int) * (m + 1));
hipMalloc((void**)&dcsr_col_ind, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&dcsr_val, sizeof(float) * nnz);

hipMemcpy(dcsr_row_ptr, hcsr_row_ptr.data(), sizeof(rocsparse_int) * (m + 1), hipMemcpyHostToDevice);
hipMemcpy(dcsr_col_ind, hcsr_col_ind.data(), sizeof(rocsparse_int) * nnz, hipMemcpyHostToDevice);
hipMemcpy(dcsr_val, hcsr_val.data(), sizeof(float) * nnz, hipMemcpyHostToDevice);

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

rocsparse_handle handle;
rocsparse_create_handle(&handle);

rocsparse_mat_descr descr;
rocsparse_create_mat_descr(&descr);

rocsparse_scsr2dense(handle,
                     m,
                     n,
                     descr,
                     dcsr_val,
                     dcsr_row_ptr,
                     dcsr_col_ind,
                     ddense,
                     ld);

rocsparse_destroy_handle(handle);
rocsparse_destroy_mat_descr(descr);

hipFree(dcsr_row_ptr);
hipFree(dcsr_col_ind);
hipFree(dcsr_val);

hipFree(ddense);

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• m – [in] number of rows of the column-oriented dense matrix A.

• n – [in] number of columns of the column-oriented dense matrix A.

• descr – [in] the descriptor of the column-oriented dense matrix A, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• csr_val – [in] array of nnz ( = csr_row_ptr[m] - csr_row_ptr[0] ) nonzero elements of matrix A.

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

• csr_col_ind – [in] integer array of nnz ( = csr_row_ptr[m] - csr_row_ptr[0] ) column indices of the non-zero elements of matrix A.

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

• ld – [out] leading dimension of column-oriented dense matrix A.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or ld is invalid.

• rocsparse_status_invalid_pointer – A or csr_val csr_row_ptr or csr_col_ind pointer is invalid.

rocsparse_csc2dense()

rocsparse_status rocsparse_scsc2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const float *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, float *A, rocsparse_int ld)

rocsparse_status rocsparse_dcsc2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const double *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, double *A, rocsparse_int ld)

rocsparse_status rocsparse_ccsc2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_float_complex *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, rocsparse_float_complex *A, rocsparse_int ld)

rocsparse_status rocsparse_zcsc2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const rocsparse_mat_descr descr, const rocsparse_double_complex *csc_val, const rocsparse_int *csc_col_ptr, const rocsparse_int *csc_row_ind, rocsparse_double_complex *A, rocsparse_int ld)

This function converts the sparse matrix in CSC format into a column-oriented dense matrix.

Example

// 1 2 3 0
// 0 0 4 5
// 0 6 0 0
// 7 0 0 8
rocsparse_int m = 4;
rocsparse_int n = 4;
rocsparse_int nnz = 8;
rocsparse_int ld = m;

std::vector<rocsparse_int> hcsc_col_ptr = {0, 2, 4, 6, 8};
std::vector<rocsparse_int> hcsc_row_ind = {0, 3, 0, 2, 0, 1, 1, 3};
std::vector<float> hcsc_val = {1.0f, 7.0f, 2.0f, 6.0f, 3.0f, 4.0f, 5.0f, 8.0f};

rocsparse_int* dcsc_col_ptr = nullptr;
rocsparse_int* dcsc_row_ind = nullptr;
float* dcsc_val = nullptr;
hipMalloc((void**)&dcsc_col_ptr, sizeof(rocsparse_int) * (n + 1));
hipMalloc((void**)&dcsc_row_ind, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&dcsc_val, sizeof(float) * nnz);

hipMemcpy(dcsc_col_ptr, hcsc_col_ptr.data(), sizeof(rocsparse_int) * (n + 1), hipMemcpyHostToDevice);
hipMemcpy(dcsc_row_ind, hcsc_row_ind.data(), sizeof(rocsparse_int) * nnz, hipMemcpyHostToDevice);
hipMemcpy(dcsc_val, hcsc_val.data(), sizeof(float) * nnz, hipMemcpyHostToDevice);

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

rocsparse_handle handle;
rocsparse_create_handle(&handle);

rocsparse_mat_descr descr;
rocsparse_create_mat_descr(&descr);

rocsparse_scsc2dense(handle,
                     m,
                     n,
                     descr,
                     dcsc_val,
                     dcsc_col_ptr,
                     dcsc_row_ind,
                     ddense,
                     ld);

rocsparse_destroy_handle(handle);
rocsparse_destroy_mat_descr(descr);

hipFree(dcsc_col_ptr);
hipFree(dcsc_row_ind);
hipFree(dcsc_val);

hipFree(ddense);

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• m – [in] number of rows of the column-oriented dense matrix A.

• n – [in] number of columns of the column-oriented dense matrix A.

• descr – [in] the descriptor of the column-oriented dense matrix A, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• csc_val – [in] array of nnz ( = csc_col_ptr[n] - csc_col_ptr[0] ) nonzero elements of matrix A.

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

• csc_row_ind – [in] integer array of nnz ( = csc_col_ptr[n] - csc_col_ptr[0] ) column indices of the non-zero elements of matrix A.

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

• ld – [out] leading dimension of column-oriented dense matrix A.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or ld is invalid.

• rocsparse_status_invalid_pointer – A or csc_val csc_col_ptr or csc_row_ind pointer is invalid.

rocsparse_coo2dense()

rocsparse_status rocsparse_scoo2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const float *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, float *A, rocsparse_int ld)

rocsparse_status rocsparse_dcoo2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const double *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, double *A, rocsparse_int ld)

rocsparse_status rocsparse_ccoo2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_float_complex *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, rocsparse_float_complex *A, rocsparse_int ld)

rocsparse_status rocsparse_zcoo2dense(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz, const rocsparse_mat_descr descr, const rocsparse_double_complex *coo_val, const rocsparse_int *coo_row_ind, const rocsparse_int *coo_col_ind, rocsparse_double_complex *A, rocsparse_int ld)

This function converts the sparse matrix in COO format into a column-oriented dense matrix.

Example

// 1 2 3 0
// 0 0 4 5
// 0 6 0 0
// 7 0 0 8
rocsparse_int m = 4;
rocsparse_int n = 4;
rocsparse_int nnz = 8;
rocsparse_int ld = m;

std::vector<rocsparse_int> hcoo_row_ind = {0, 0, 0, 1, 1, 2, 3, 3};
std::vector<rocsparse_int> hcoo_col_ind = {0, 1, 2, 2, 3, 1, 0, 3};
std::vector<float> hcoo_val = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f};

rocsparse_int* dcoo_row_ind = nullptr;
rocsparse_int* dcoo_col_ind = nullptr;
float* dcoo_val = nullptr;
hipMalloc((void**)&dcoo_row_ind, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&dcoo_col_ind, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&dcoo_val, sizeof(float) * nnz);

hipMemcpy(dcoo_row_ind, hcoo_row_ind.data(), sizeof(rocsparse_int) * nnz, hipMemcpyHostToDevice);
hipMemcpy(dcoo_col_ind, hcoo_col_ind.data(), sizeof(rocsparse_int) * nnz, hipMemcpyHostToDevice);
hipMemcpy(dcoo_val, hcoo_val.data(), sizeof(float) * nnz, hipMemcpyHostToDevice);

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

rocsparse_handle handle;
rocsparse_create_handle(&handle);

rocsparse_mat_descr descr;
rocsparse_create_mat_descr(&descr);

rocsparse_scoo2dense(handle,
                    m,
                    n,
                    nnz,
                    descr,
                    dcoo_val,
                    dcoo_row_ind,
                    dcoo_col_ind,
                    ddense,
                    ld);

rocsparse_destroy_handle(handle);
rocsparse_destroy_mat_descr(descr);

hipFree(dcoo_row_ind);
hipFree(dcoo_col_ind);
hipFree(dcoo_val);

hipFree(ddense);

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• m – [in] number of rows of the column-oriented dense matrix A.

• n – [in] number of columns of the column-oriented dense matrix A.

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

• descr – [in] the descriptor of the column-oriented dense matrix A, the supported matrix type is rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• coo_val – [in] array of nnz nonzero elements of matrix A.

• coo_row_ind – [in] integer array of nnz row indices of the non-zero elements of matrix A.

• coo_col_ind – [in] integer array of nnz column indices of the non-zero elements of matrix A.

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

• ld – [out] leading dimension of column-oriented dense matrix A.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or nnz or ld is invalid.

• rocsparse_status_invalid_pointer – A or coo_val coo_col_ind or coo_row_ind pointer is invalid.

rocsparse_prune_dense2csr_buffer_size()

rocsparse_status rocsparse_sprune_dense2csr_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *A, rocsparse_int lda, const float *threshold, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, size_t *buffer_size)

rocsparse_status rocsparse_dprune_dense2csr_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *A, rocsparse_int lda, const double *threshold, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, size_t *buffer_size)

rocsparse_prune_dense2csr_buffer_size returns the size of the temporary buffer that is required by rocsparse_Xprune_dense2csr_nnz() and rocsparse_Xprune_dense2csr(). The temporary storage buffer must be allocated by the user.

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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 rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• csr_val – [in] array of nnz ( = csr_row_ptr[m] - csr_row_ptr[0] ) nonzero elements of matrix A.

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

• csr_col_ind – [in] integer array of nnz ( = csr_row_ptr[m] - csr_row_ptr[0] ) column indices of the non-zero elements of matrix A.

• buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_Xprune_dense2csr_nnz() and rocsparse_Xprune_dense2csr().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_pointer – buffer_size pointer is invalid.

• rocsparse_status_internal_error – an internal error occurred.

rocsparse_prune_dense2csr_nnz()

rocsparse_status rocsparse_sprune_dense2csr_nnz(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *A, rocsparse_int lda, const float *threshold, const rocsparse_mat_descr descr, rocsparse_int *csr_row_ptr, rocsparse_int *nnz_total_dev_host_ptr, void *temp_buffer)

rocsparse_status rocsparse_dprune_dense2csr_nnz(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *A, rocsparse_int lda, const double *threshold, const rocsparse_mat_descr descr, rocsparse_int *csr_row_ptr, rocsparse_int *nnz_total_dev_host_ptr, void *temp_buffer)

rocsparse_prune_dense2csr_nnz 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.

Note

This routine does not support execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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.

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

• nnz_total_dev_host_ptr – [out] total number of nonzero elements in device or host memory.

• temp_buffer – [out] buffer allocated by the user whose size is determined by calling rocsparse_Xprune_dense2csr_buffer_size().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or lda is invalid.

• rocsparse_status_invalid_pointer – A or threshold or descr or csr_row_ptr or nnz_total_dev_host_ptr or temp_buffer pointer is invalid.

rocsparse_prune_dense2csr()

rocsparse_status rocsparse_sprune_dense2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *A, rocsparse_int lda, const float *threshold, const rocsparse_mat_descr descr, float *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, void *temp_buffer)

rocsparse_status rocsparse_dprune_dense2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *A, rocsparse_int lda, const double *threshold, const rocsparse_mat_descr descr, double *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, void *temp_buffer)

Convert and prune dense matrix \(A\) into a sparse CSR matrix \(C\).

This function converts the dense matrix \(A\) into a sparse CSR matrix \(C\) by pruning values in \(A\) that are less than a threshold.

The conversion involves three steps. The user first calls rocsparse_Xprune_dense2csr_buffer_size() to determine the size of the temporary storage buffer. The user allocates this buffer as well as the array csr_row_ptr to have m+1 elements. The user then calls rocsparse_Xprune_dense2csr_nnz() which fills in the csr_row_ptr array and stores the number of elements that are larger than the pruning threshold in nnz_total_dev_host_ptr. Now that the number of nonzeros larger than the pruning threshold is known, the user uses this information to allocate the csr_col_ind and csr_val arrays and then calls rocsparse_prune_dense2csr to complete the conversion. Once the conversion is complete, the temporary storage buffer can be freed.

Example

//     1 2 0 7
// A = 3 0 0 4
//     5 6 0 4
//     0 4 2 5
rocsparse_int m   = 4;
rocsparse_int n   = 4;
rocsparse_int lda = m;
float threshold = 3.0f;

std::vector<float> hdense = {1.0f, 3.0f, 5.0f, 0.0f, 2.0f, 0.0f, 6.0f, 4.0f, 0.0f, 0.0f, 0.0f, 2.0f, 7.0f, 4.0f, 4.0f, 5.0f};

rocsparse_handle handle;
rocsparse_create_handle(&handle);

rocsparse_mat_descr descr;
rocsparse_create_mat_descr(&descr);

rocsparse_mat_info info;
rocsparse_create_mat_info(&info);

float* ddense = nullptr;
hipMalloc((void**)&ddense, sizeof(float) * lda * n);
hipMemcpy(ddense, hdense.data(), sizeof(float) * lda * n, hipMemcpyHostToDevice);

rocsparse_int* dcsr_row_ptr = nullptr;
hipMalloc((void**)&dcsr_row_ptr, sizeof(rocsparse_int) * (m + 1));

// Obtain the temporary buffer size
size_t buffer_size;
rocsparse_sprune_dense2csr_buffer_size(handle,
                                       m,
                                       n,
                                       ddense,
                                       lda,
                                       &threshold,
                                       descr,
                                       nullptr,
                                       nullptr,
                                       nullptr,
                                       &buffer_size);

// Allocate temporary buffer
void* temp_buffer;
hipMalloc(&temp_buffer, buffer_size);

rocsparse_int nnz;
rocsparse_sprune_dense2csr_nnz(handle,
                               m,
                               n,
                               ddense,
                               lda,
                               &threshold,
                               descr,
                               dcsr_row_ptr,
                               &nnz,
                               temp_buffer);

rocsparse_int* dcsr_col_ind = nullptr;
float* dcsr_val = nullptr;
hipMalloc((void**)&dcsr_col_ind, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&dcsr_val, sizeof(float) * nnz);

rocsparse_sprune_dense2csr(handle,
                           m,
                           n,
                           ddense,
                           lda,
                           &threshold,
                           descr,
                           dcsr_val,
                           dcsr_row_ptr,
                           dcsr_col_ind,
                           temp_buffer);

rocsparse_destroy_handle(handle);
rocsparse_destroy_mat_descr(descr);
rocsparse_destroy_mat_info(info);

hipFree(temp_buffer);

hipFree(ddense);

hipFree(dcsr_row_ptr);
hipFree(dcsr_col_ind);
hipFree(dcsr_val);

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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 rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• csr_val – [out] array of nnz ( = csr_row_ptr[m] - csr_row_ptr[0] ) nonzero elements of matrix A.

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

• csr_col_ind – [out] integer array of nnz ( = csr_row_ptr[m] - csr_row_ptr[0] ) column indices of the non-zero elements of matrix A.

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

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or lda is invalid.

• rocsparse_status_invalid_pointer – A or descr or threshold or csr_val or csr_row_ptr or csr_col_ind or temp_buffer pointer is invalid.

rocsparse_prune_csr2csr_buffer_size()

rocsparse_status rocsparse_sprune_csr2csr_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const float *threshold, const rocsparse_mat_descr csr_descr_C, const float *csr_val_C, const rocsparse_int *csr_row_ptr_C, const rocsparse_int *csr_col_ind_C, size_t *buffer_size)

rocsparse_status rocsparse_dprune_csr2csr_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const double *threshold, const rocsparse_mat_descr csr_descr_C, const double *csr_val_C, const rocsparse_int *csr_row_ptr_C, const rocsparse_int *csr_col_ind_C, size_t *buffer_size)

rocsparse_prune_csr2csr_buffer_size returns the size of the temporary buffer that is required by rocsparse_Xprune_csr2csr_nnz() and rocsparse_Xprune_csr2csr(). The temporary storage buffer must be allocated by the user.

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

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

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

• nnz_A – [in] number of non-zeros in the sparse CSR matrix \(A\).

• csr_descr_A – [in] descriptor of the sparse CSR matrix \(A\). Currently, only rocsparse_matrix_type_general is supported.

• csr_val_A – [in] array of nnz_A elements containing the values of the sparse CSR matrix \(A\).

• csr_row_ptr_A – [in] array of m+1 elements that point to the start of every row of the sparse CSR matrix \(A\).

• csr_col_ind_A – [in] array of nnz_A 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.

• csr_descr_C – [in] descriptor of the sparse CSR matrix \(C\). Currently, only rocsparse_matrix_type_general is supported.

• csr_val_C – [in] array of nnz_C elements containing the values of the sparse CSR matrix \(C\).

• csr_row_ptr_C – [in] array of m+1 elements that point to the start of every row of the sparse CSR matrix \(C\).

• csr_col_ind_C – [in] array of nnz_C elements containing the column indices of the sparse CSR matrix \(C\).

• buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_Xprune_csr2csr_nnz() and rocsparse_Xprune_csr2csr().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_pointer – buffer_size pointer is invalid.

• rocsparse_status_internal_error – an internal error occurred.

rocsparse_prune_csr2csr_nnz()

rocsparse_status rocsparse_sprune_csr2csr_nnz(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const float *threshold, const rocsparse_mat_descr csr_descr_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *nnz_total_dev_host_ptr, void *temp_buffer)

rocsparse_status rocsparse_dprune_csr2csr_nnz(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const double *threshold, const rocsparse_mat_descr csr_descr_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *nnz_total_dev_host_ptr, void *temp_buffer)

rocsparse_prune_csr2csr_nnz 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.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

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

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

• nnz_A – [in] number of non-zeros in the sparse CSR matrix \(A\).

• csr_descr_A – [in] descriptor of the sparse CSR matrix \(A\). Currently, only rocsparse_matrix_type_general is supported.

• csr_val_A – [in] array of nnz_A elements containing the values of the sparse CSR matrix \(A\).

• csr_row_ptr_A – [in] array of m+1 elements that point to the start of every row of the sparse CSR matrix \(A\).

• csr_col_ind_A – [in] array of nnz_A 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.

• csr_descr_C – [in] descriptor of the sparse CSR matrix \(C\). Currently, only rocsparse_matrix_type_general is supported.

• csr_row_ptr_C – [out] array of m+1 elements that point to the start of every row of the sparse CSR matrix \(C\).

• nnz_total_dev_host_ptr – [out] total number of nonzero elements in device or host memory.

• temp_buffer – [out] buffer allocated by the user whose size is determined by calling rocsparse_Xprune_csr2csr_buffer_size().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or nnz_A is invalid.

• rocsparse_status_invalid_pointer – threshold or csr_descr_A or csr_descr_C or csr_val_A or csr_row_ptr_A or csr_col_ind_A or csr_row_ptr_C or nnz_total_dev_host_ptr or temp_buffer pointer is invalid.

rocsparse_prune_csr2csr()

rocsparse_status rocsparse_sprune_csr2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const float *threshold, const rocsparse_mat_descr csr_descr_C, float *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, void *temp_buffer)

rocsparse_status rocsparse_dprune_csr2csr(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, const double *threshold, const rocsparse_mat_descr csr_descr_C, double *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, void *temp_buffer)

Convert and prune sparse CSR matrix \(A\) into a sparse CSR matrix \(C\).

This function converts the sparse CSR matrix \(A\) into a sparse CSR matrix \(C\) by pruning values in \(A\) that are less than a threshold.

The conversion involves three steps. The user first calls rocsparse_Xprune_csr2csr_buffer_size() to determine the size of the temporary storage buffer. The user allocates this buffer as well as the array csr_row_ptr_C to have m+1 elements. The user then calls rocsparse_Xprune_csr2csr_nnz() which fills in the csr_row_ptr_C array and stores the number of elements that are larger than the pruning threshold in nnz_total_dev_host_ptr. Now that the number of nonzeros larger than the pruning threshold is known, the user uses this information to allocate the csr_col_ind_C and csr_val_C arrays and then calls rocsparse_prune_csr2csr to complete the conversion. Once the conversion is complete, the temporary storage buffer can be freed.

Example

//     1 2 0 0
// A = 3 0 0 4
//     5 6 0 4
//     7 4 2 5
rocsparse_int m   = 4;
rocsparse_int n   = 4;
rocsparse_int nnz_A = 11;
float threshold = 5.0f;

std::vector<rocsparse_int> hcsr_row_ptr_A = {0, 2, 4, 7, 11}; 
std::vector<rocsparse_int> hcsr_col_ind_A = {0, 1, 0, 3, 0, 1, 3, 0, 1, 2, 3}; 
std::vector<float> hcsr_val_A = {1, 2, 3, 4, 5, 6, 4, 7, 4, 2, 5};

rocsparse_int* dcsr_row_ptr_A = nullptr;
rocsparse_int* dcsr_col_ind_A = nullptr;
float* dcsr_val_A = nullptr;
hipMalloc((void**)&dcsr_row_ptr_A, sizeof(rocsparse_int) * (m + 1));
hipMalloc((void**)&dcsr_col_ind_A, sizeof(rocsparse_int) * nnz_A);
hipMalloc((void**)&dcsr_val_A, sizeof(float) * nnz_A);

hipMemcpy(dcsr_row_ptr_A, hcsr_row_ptr_A.data(), sizeof(rocsparse_int) * (m + 1), hipMemcpyHostToDevice);
hipMemcpy(dcsr_col_ind_A, hcsr_col_ind_A.data(), sizeof(rocsparse_int) * nnz_A, hipMemcpyHostToDevice);
hipMemcpy(dcsr_val_A, hcsr_val_A.data(), sizeof(float) * nnz_A, hipMemcpyHostToDevice);

rocsparse_handle handle;
rocsparse_create_handle(&handle);

rocsparse_mat_descr descr_A;
rocsparse_create_mat_descr(&descr_A);

rocsparse_mat_descr descr_C;
rocsparse_create_mat_descr(&descr_C);

rocsparse_mat_info info;
rocsparse_create_mat_info(&info);

rocsparse_int* dcsr_row_ptr_C = nullptr;
hipMalloc((void**)&dcsr_row_ptr_C, sizeof(rocsparse_int) * (m + 1));

// Obtain the temporary buffer size
size_t buffer_size;
rocsparse_sprune_csr2csr_buffer_size(handle,
                                     m,
                                     n,
                                     nnz_A,
                                     descr_A,
                                     dcsr_val_A,
                                     dcsr_row_ptr_A,
                                     dcsr_col_ind_A,
                                     &threshold,
                                     descr_C,
                                     nullptr,
                                     nullptr,
                                     nullptr,
                                     &buffer_size);

// Allocate temporary buffer
void* temp_buffer;
hipMalloc(&temp_buffer, buffer_size);

rocsparse_int nnz_C;
rocsparse_sprune_csr2csr_nnz(handle,
                             m,
                             n,
                             nnz_A,
                             descr_A,
                             dcsr_val_A,
                             dcsr_row_ptr_A,
                             dcsr_col_ind_A,
                             &threshold,
                             descr_C,
                             dcsr_row_ptr_C,
                             &nnz_C,
                             temp_buffer);

rocsparse_int* dcsr_col_ind_C = nullptr;
float* dcsr_val_C = nullptr;
hipMalloc((void**)&dcsr_col_ind_C, sizeof(rocsparse_int) * nnz_C);
hipMalloc((void**)&dcsr_val_C, sizeof(float) * nnz_C);

rocsparse_sprune_csr2csr(handle,
                         m,
                         n,
                         nnz_A,
                         descr_A,
                         dcsr_val_A,
                         dcsr_row_ptr_A,
                         dcsr_col_ind_A,
                         &threshold,
                         descr_C,
                         dcsr_val_C,
                         dcsr_row_ptr_C,
                         dcsr_col_ind_C,
                         temp_buffer);

rocsparse_destroy_handle(handle);
rocsparse_destroy_mat_descr(descr_A);
rocsparse_destroy_mat_descr(descr_C);

hipFree(temp_buffer);

hipFree(dcsr_row_ptr_A);
hipFree(dcsr_col_ind_A);
hipFree(dcsr_val_A);

hipFree(dcsr_row_ptr_C);
hipFree(dcsr_col_ind_C);
hipFree(dcsr_val_C);

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

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

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

• nnz_A – [in] number of non-zeros in the sparse CSR matrix \(A\).

• csr_descr_A – [in] descriptor of the sparse CSR matrix \(A\). Currently, only rocsparse_matrix_type_general is supported.

• csr_val_A – [in] array of nnz_A elements containing the values of the sparse CSR matrix \(A\).

• csr_row_ptr_A – [in] array of m+1 elements that point to the start of every row of the sparse CSR matrix \(A\).

• csr_col_ind_A – [in] array of nnz_A 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.

• csr_descr_C – [in] descriptor of the sparse CSR matrix \(C\). Currently, only rocsparse_matrix_type_general is supported.

• csr_val_C – [out] array of nnz_C elements containing the values of the sparse CSR matrix \(C\).

• csr_row_ptr_C – [in] array of m+1 elements that point to the start of every row of the sparse CSR matrix \(C\).

• csr_col_ind_C – [out] array of nnz_C elements containing the column indices of the sparse CSR matrix \(C\).

• temp_buffer – [in] buffer allocated by the user whose size is determined by calling rocsparse_Xprune_csr2csr_buffer_size().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or nnz_A is invalid.

• rocsparse_status_invalid_pointer – threshold or csr_descr_A or csr_descr_C or csr_val_A or csr_row_ptr_A or csr_col_ind_A or csr_val_C or csr_row_ptr_C or csr_col_ind_C or temp_buffer pointer is invalid.

rocsparse_prune_dense2csr_by_percentage_buffer_size()

rocsparse_status rocsparse_sprune_dense2csr_by_percentage_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *A, rocsparse_int lda, float percentage, const rocsparse_mat_descr descr, const float *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_dprune_dense2csr_by_percentage_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *A, rocsparse_int lda, double percentage, const rocsparse_mat_descr descr, const double *csr_val, const rocsparse_int *csr_row_ptr, const rocsparse_int *csr_col_ind, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_prune_dense2csr_by_percentage_buffer_size returns the size of the temporary buffer that is required by rocsparse_Xprune_dense2csr_nnz_by_percentage() and rocsparse_Xprune_dense2csr_by_percentage(). The temporary storage buffer must be allocated by the user.

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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 rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• csr_val – [in] array of nnz ( = csr_row_ptr[m] - csr_row_ptr[0] ) nonzero elements of matrix A.

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

• csr_col_ind – [in] integer array of nnz ( = csr_row_ptr[m] - csr_row_ptr[0] ) column indices of the non-zero elements of matrix A.

• info – [in] prune information structure

• buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_Xprune_dense2csr_nnz_by_percentage() and rocsparse_Xprune_dense2csr_by_percentage().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_pointer – buffer_size pointer is invalid.

• rocsparse_status_internal_error – an internal error occurred.

rocsparse_prune_dense2csr_nnz_by_percentage()

rocsparse_status rocsparse_sprune_dense2csr_nnz_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *A, rocsparse_int lda, float percentage, const rocsparse_mat_descr descr, rocsparse_int *csr_row_ptr, rocsparse_int *nnz_total_dev_host_ptr, rocsparse_mat_info info, void *temp_buffer)

rocsparse_status rocsparse_dprune_dense2csr_nnz_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *A, rocsparse_int lda, double percentage, const rocsparse_mat_descr descr, rocsparse_int *csr_row_ptr, rocsparse_int *nnz_total_dev_host_ptr, rocsparse_mat_info info, void *temp_buffer)

rocsparse_sprune_dense2csr_nnz_by_percentage computes the number of nonzero elements per row and the total number of nonzero elements in a sparse CSR matrix once a percentage of the smallest magnitude elements have been pruned from the dense input matrix. See rocsparse_sprune_dense2csr_by_percentage() for a more detailed description of how this pruning based on percentage works.

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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.

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

• nnz_total_dev_host_ptr – [out] total number of nonzero elements in device or host memory.

• info – [in] prune information structure

• temp_buffer – [out] buffer allocated by the user whose size is determined by calling rocsparse_Xprune_dense2csr_by_percentage_buffer_size()..

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or lda or percentage is invalid.

• rocsparse_status_invalid_pointer – A or descr or info or csr_row_ptr or nnz_total_dev_host_ptr or temp_buffer pointer is invalid.

rocsparse_prune_dense2csr_by_percentage()

rocsparse_status rocsparse_sprune_dense2csr_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const float *A, rocsparse_int lda, float percentage, const rocsparse_mat_descr descr, float *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, rocsparse_mat_info info, void *temp_buffer)

rocsparse_status rocsparse_dprune_dense2csr_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, const double *A, rocsparse_int lda, double percentage, const rocsparse_mat_descr descr, double *csr_val, const rocsparse_int *csr_row_ptr, rocsparse_int *csr_col_ind, rocsparse_mat_info info, void *temp_buffer)

This function converts the matrix \(A\) in dense format into a sparse matrix in CSR format while pruning values based on percentage.

This function converts the dense column oriented matrix \(A\) into a sparse CSR matrix \(C\) by pruning values in \(A\) that are less than a threshold. This threshold is determined by using a percentage and the following steps:

Step 1: First the A array is sorted in ascending order using the absolute value of each entry:

\[ A\_sorted = sort(abs(A)) \]

Step 2: Next we use the percentage parameter to determine the threshold:

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

Step 3: Finally, we use this threshold with the routine rocsparse_Xprune_dense2csr() to complete the conversion.

The conversion involves three steps. The user first calls rocsparse_Xprune_dense2csr_by_percentage_buffer_size() to determine the size of the temporary storage buffer. The user allocates this buffer as well as the array csr_row_ptr to have m+1 elements. The user then calls rocsparse_Xprune_dense2csr_nnz_by_percentage() which fills in the csr_row_ptr array and stores the number of elements that are larger than the pruning threshold in nnz_total_dev_host_ptr. Now that the number of nonzeros larger than the pruning threshold is known, the user uses this information to allocate the csr_col_ind and csr_val arrays and then calls rocsparse_prune_dense2csr_by_percentage to complete the conversion. Once the conversion is complete, the temporary storage buffer can be freed.

Example

//     1 2 0 7
// A = 3 0 0 4
//     5 6 0 4
//     0 4 2 5
rocsparse_int m   = 4;
rocsparse_int n   = 4;
rocsparse_int lda = m;
float percentage = 50.0f;

std::vector<float> hdense = {1.0f, 3.0f, 5.0f, 0.0f, 2.0f, 0.0f, 6.0f, 4.0f, 0.0f, 0.0f, 0.0f, 2.0f, 7.0f, 4.0f, 4.0f, 5.0f};

rocsparse_handle handle;
rocsparse_create_handle(&handle);

rocsparse_mat_descr descr;
rocsparse_create_mat_descr(&descr);

rocsparse_mat_info info;
rocsparse_create_mat_info(&info);

float* ddense = nullptr;
hipMalloc((void**)&ddense, sizeof(float) * lda * n);
hipMemcpy(ddense, hdense.data(), sizeof(float) * lda * n, hipMemcpyHostToDevice);

rocsparse_int* dcsr_row_ptr = nullptr;
hipMalloc((void**)&dcsr_row_ptr, sizeof(rocsparse_int) * (m + 1));

// Obtain the temporary buffer size
size_t buffer_size;
rocsparse_sprune_dense2csr_by_percentage_buffer_size(handle,
                                                     m,
                                                     n,
                                                     ddense,
                                                     lda,
                                                     percentage,
                                                     descr,
                                                     nullptr,
                                                     nullptr,
                                                     nullptr,
                                                     info,
                                                     &buffer_size);

// Allocate temporary buffer
void* temp_buffer;
hipMalloc(&temp_buffer, buffer_size);

rocsparse_int nnz;
rocsparse_sprune_dense2csr_nnz_by_percentage(handle,
                                            m,
                                            n,
                                            ddense,
                                            lda,
                                            percentage,
                                            descr,
                                            dcsr_row_ptr,
                                            &nnz,
                                            info,
                                            temp_buffer);

rocsparse_int* dcsr_col_ind = nullptr;
float* dcsr_val = nullptr;
hipMalloc((void**)&dcsr_col_ind, sizeof(rocsparse_int) * nnz);
hipMalloc((void**)&dcsr_val, sizeof(float) * nnz);

rocsparse_sprune_dense2csr_by_percentage(handle,
                                        m,
                                        n,
                                        ddense,
                                        lda,
                                        percentage,
                                        descr,
                                        dcsr_val,
                                        dcsr_row_ptr,
                                        dcsr_col_ind,
                                        info,
                                        temp_buffer);

rocsparse_destroy_handle(handle);
rocsparse_destroy_mat_descr(descr);
rocsparse_destroy_mat_info(info);

hipFree(temp_buffer);
hipFree(ddense);

hipFree(dcsr_row_ptr);
hipFree(dcsr_col_ind);
hipFree(dcsr_val);

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

• handle – [in] handle to the rocsparse 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 rocsparse_matrix_type_general and also any valid value of the rocsparse_index_base.

• csr_val – [out] array of nnz ( = csr_row_ptr[m] - csr_row_ptr[0] ) nonzero elements of matrix A.

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

• csr_col_ind – [out] integer array of nnz ( = csr_row_ptr[m] - csr_row_ptr[0] ) column indices of the non-zero elements of matrix A.

• info – [in] prune information structure

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

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or lda or percentage is invalid.

• rocsparse_status_invalid_pointer – A or descr or info or csr_val or csr_row_ptr or csr_col_ind or temp_buffer pointer is invalid.

rocsparse_prune_csr2csr_by_percentage_buffer_size()

rocsparse_status rocsparse_sprune_csr2csr_by_percentage_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, float percentage, const rocsparse_mat_descr csr_descr_C, const float *csr_val_C, const rocsparse_int *csr_row_ptr_C, const rocsparse_int *csr_col_ind_C, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_status rocsparse_dprune_csr2csr_by_percentage_buffer_size(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, double percentage, const rocsparse_mat_descr csr_descr_C, const double *csr_val_C, const rocsparse_int *csr_row_ptr_C, const rocsparse_int *csr_col_ind_C, rocsparse_mat_info info, size_t *buffer_size)

rocsparse_prune_csr2csr_by_percentage_buffer_size returns the size of the temporary buffer that is required by rocsparse_Xprune_csr2csr_nnz_by_percentage() and rocsparse_Xprune_csr2csr_by_percentage(). The temporary storage buffer must be allocated by the user.

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

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

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

• nnz_A – [in] number of non-zeros in the sparse CSR matrix \(A\).

• csr_descr_A – [in] descriptor of the sparse CSR matrix \(A\). Currently, only rocsparse_matrix_type_general is supported.

• csr_val_A – [in] array of nnz_A elements containing the values of the sparse CSR matrix \(A\).

• csr_row_ptr_A – [in] array of m+1 elements that point to the start of every row of the sparse CSR matrix \(A\).

• csr_col_ind_A – [in] array of nnz_A elements containing the column indices of the sparse CSR matrix \(A\).

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

• csr_descr_C – [in] descriptor of the sparse CSR matrix \(C\). Currently, only rocsparse_matrix_type_general is supported.

• csr_val_C – [in] array of nnz_C elements containing the values of the sparse CSR matrix \(C\).

• csr_row_ptr_C – [in] array of m+1 elements that point to the start of every row of the sparse CSR matrix \(C\).

• csr_col_ind_C – [in] array of nnz_C elements containing the column indices of the sparse CSR matrix \(C\).

• info – [in] prune info structure.

• buffer_size – [out] number of bytes of the temporary storage buffer required by rocsparse_Xprune_csr2csr_nnz_by_percentage() and rocsparse_Xprune_csr2csr_by_percentage()

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_pointer – buffer_size pointer is invalid.

• rocsparse_status_internal_error – an internal error occurred.

rocsparse_prune_csr2csr_nnz_by_percentage()

rocsparse_status rocsparse_sprune_csr2csr_nnz_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, float percentage, const rocsparse_mat_descr csr_descr_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *nnz_total_dev_host_ptr, rocsparse_mat_info info, void *temp_buffer)

rocsparse_status rocsparse_dprune_csr2csr_nnz_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, double percentage, const rocsparse_mat_descr csr_descr_C, rocsparse_int *csr_row_ptr_C, rocsparse_int *nnz_total_dev_host_ptr, rocsparse_mat_info info, void *temp_buffer)

rocsparse_prune_csr2csr_nnz_by_percentage computes the number of nonzero elements per row and the total number of nonzero elements in a sparse CSR matrix once a percentage of the smallest magnitude elements have been pruned from the sparse CSR input matrix. See rocsparse_sprune_csr2csr_by_percentage() for a more detailed description of how this pruning based on percentage works.

Note

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

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

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

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

• nnz_A – [in] number of non-zeros in the sparse CSR matrix \(A\).

• csr_descr_A – [in] descriptor of the sparse CSR matrix \(A\). Currently, only rocsparse_matrix_type_general is supported.

• csr_val_A – [in] array of nnz_A elements containing the values of the sparse CSR matrix \(A\).

• csr_row_ptr_A – [in] array of m+1 elements that point to the start of every row of the sparse CSR matrix \(A\).

• csr_col_ind_A – [in] array of nnz_A elements containing the column indices of the sparse CSR matrix \(A\).

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

• csr_descr_C – [in] descriptor of the sparse CSR matrix \(C\). Currently, only rocsparse_matrix_type_general is supported.

• csr_row_ptr_C – [out] array of m+1 elements that point to the start of every row of the sparse CSR matrix \(C\).

• nnz_total_dev_host_ptr – [out] total number of nonzero elements in device or host memory.

• info – [in] prune info structure.

• temp_buffer – [out] buffer allocated by the user whose size is determined by calling rocsparse_Xprune_csr2csr_by_percentage_buffer_size().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or nnz_A or percentage is invalid.

• rocsparse_status_invalid_pointer – csr_descr_A or csr_descr_C or info or csr_val_A or csr_row_ptr_A or csr_col_ind_A or csr_row_ptr_C or nnz_total_dev_host_ptr or temp_buffer pointer is invalid.

rocsparse_prune_csr2csr_by_percentage()

rocsparse_status rocsparse_sprune_csr2csr_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const float *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, float percentage, const rocsparse_mat_descr csr_descr_C, float *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, rocsparse_mat_info info, void *temp_buffer)

rocsparse_status rocsparse_dprune_csr2csr_by_percentage(rocsparse_handle handle, rocsparse_int m, rocsparse_int n, rocsparse_int nnz_A, const rocsparse_mat_descr csr_descr_A, const double *csr_val_A, const rocsparse_int *csr_row_ptr_A, const rocsparse_int *csr_col_ind_A, double percentage, const rocsparse_mat_descr csr_descr_C, double *csr_val_C, const rocsparse_int *csr_row_ptr_C, rocsparse_int *csr_col_ind_C, rocsparse_mat_info info, void *temp_buffer)

Convert and prune by percentage a sparse CSR matrix \(A\) into a sparse CSR matrix \(C\).

This function converts the sparse CSR matrix \(A\) into a sparse CSR matrix \(C\) by pruning values in \(A\) that are less than a threshold. This threshold is determined by using a percentage and the following steps:

Step 1: First the csr_val_A array is sorted in ascending order using the absolute value of each entry:

\[ csr\_val\_A\_sorted = sort(abs(csr\_val\_A)) \]

Step 2: Next we use the percentage parameter to determine the threshold:

\[\begin{split} pos = ceil(nnz\_A \times (percentage/100)) - 1 \\ pos = \min(pos, nnz\_A - 1) \\ pos = \max(pos, 0) \\ threshold = csr\_val\_A\_sorted[pos] \end{split}\]

Step 3: Finally, we use this threshold with the routine rocsparse_Xprune_csr2csr() to complete the conversion.

The conversion involves three steps. The user first calls rocsparse_Xprune_csr2csr_by_percentage_buffer_size() to determine the size of the temporary storage buffer. The user allocates this buffer as well as the array csr_row_ptr_C to have m+1 elements. The user then calls rocsparse_Xprune_csr2csr_nnz_by_percentage() which fills in the csr_row_ptr_C array and stores the number of elements that are larger than the pruning threshold in nnz_total_dev_host_ptr. Now that the number of nonzeros larger than the pruning threshold is known, the user uses this information to allocate the csr_col_ind_C and csr_val_C arrays and then calls rocsparse_prune_csr2csr_by_percentage to complete the conversion. Once the conversion is complete, the temporary storage buffer can be freed.

Example

//     1 2 0 0
// A = 3 0 0 4
//     5 6 0 4
//     7 4 2 5
rocsparse_int m   = 4;
rocsparse_int n   = 4;
rocsparse_int nnz_A = 11;
float percentage = 50.0f;

std::vector<rocsparse_int> hcsr_row_ptr_A = {0, 2, 4, 7, 11}; 
std::vector<rocsparse_int> hcsr_col_ind_A = {0, 1, 0, 3, 0, 1, 3, 0, 1, 2, 3}; 
std::vector<float> hcsr_val_A = {1, 2, 3, 4, 5, 6, 4, 7, 4, 2, 5};

rocsparse_int* dcsr_row_ptr_A = nullptr;
rocsparse_int* dcsr_col_ind_A = nullptr;
float* dcsr_val_A = nullptr;
hipMalloc((void**)&dcsr_row_ptr_A, sizeof(rocsparse_int) * (m + 1));
hipMalloc((void**)&dcsr_col_ind_A, sizeof(rocsparse_int) * nnz_A);
hipMalloc((void**)&dcsr_val_A, sizeof(float) * nnz_A);

hipMemcpy(dcsr_row_ptr_A, hcsr_row_ptr_A.data(), sizeof(rocsparse_int) * (m + 1), hipMemcpyHostToDevice);
hipMemcpy(dcsr_col_ind_A, hcsr_col_ind_A.data(), sizeof(rocsparse_int) * nnz_A, hipMemcpyHostToDevice);
hipMemcpy(dcsr_val_A, hcsr_val_A.data(), sizeof(float) * nnz_A, hipMemcpyHostToDevice);

rocsparse_handle handle;
rocsparse_create_handle(&handle);

rocsparse_mat_descr descr_A;
rocsparse_create_mat_descr(&descr_A);

rocsparse_mat_descr descr_C;
rocsparse_create_mat_descr(&descr_C);

rocsparse_mat_info info;
rocsparse_create_mat_info(&info);

rocsparse_int* dcsr_row_ptr_C = nullptr;
hipMalloc((void**)&dcsr_row_ptr_C, sizeof(rocsparse_int) * (m + 1));

// Obtain the temporary buffer size
size_t buffer_size;
rocsparse_sprune_csr2csr_by_percentage_buffer_size(handle,
                                                   m,
                                                   n,
                                                   nnz_A,
                                                   descr_A,
                                                   dcsr_val_A,
                                                   dcsr_row_ptr_A,
                                                   dcsr_col_ind_A,
                                                   percentage,
                                                   descr_C,
                                                   nullptr,
                                                   nullptr,
                                                   nullptr,
                                                   info,
                                                   &buffer_size);

// Allocate temporary buffer
void* temp_buffer;
hipMalloc(&temp_buffer, buffer_size);

rocsparse_int nnz_C;
rocsparse_sprune_csr2csr_nnz_by_percentage(handle,
                                           m,
                                           n,
                                           nnz_A,
                                           descr_A,
                                           dcsr_val_A,
                                           dcsr_row_ptr_A,
                                           dcsr_col_ind_A,
                                           percentage,
                                           descr_C,
                                           dcsr_row_ptr_C,
                                           &nnz_C,
                                           info,
                                           temp_buffer);

rocsparse_int* dcsr_col_ind_C = nullptr;
float* dcsr_val_C = nullptr;
hipMalloc((void**)&dcsr_col_ind_C, sizeof(rocsparse_int) * nnz_C);
hipMalloc((void**)&dcsr_val_C, sizeof(float) * nnz_C);

rocsparse_sprune_csr2csr_by_percentage(handle,
                                       m,
                                       n,
                                       nnz_A,
                                       descr_A,
                                       dcsr_val_A,
                                       dcsr_row_ptr_A,
                                       dcsr_col_ind_A,
                                       percentage,
                                       descr_C,
                                       dcsr_val_C,
                                       dcsr_row_ptr_C,
                                       dcsr_col_ind_C,
                                       info,
                                       temp_buffer);

rocsparse_destroy_handle(handle);
rocsparse_destroy_mat_descr(descr_A);
rocsparse_destroy_mat_descr(descr_C);
rocsparse_destroy_mat_info(info);

hipFree(temp_buffer);

hipFree(dcsr_row_ptr_A);
hipFree(dcsr_col_ind_A);
hipFree(dcsr_val_A);

hipFree(dcsr_row_ptr_C);
hipFree(dcsr_col_ind_C);
hipFree(dcsr_val_C);

Note

This function is blocking with respect to the host.

Note

This routine does not support execution in a hipGraph context.

Parameters:

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

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

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

• nnz_A – [in] number of non-zeros in the sparse CSR matrix \(A\).

• csr_descr_A – [in] descriptor of the sparse CSR matrix \(A\). Currently, only rocsparse_matrix_type_general is supported.

• csr_val_A – [in] array of nnz_A elements containing the values of the sparse CSR matrix \(A\).

• csr_row_ptr_A – [in] array of m+1 elements that point to the start of every row of the sparse CSR matrix \(A\).

• csr_col_ind_A – [in] array of nnz_A elements containing the column indices of the sparse CSR matrix \(A\).

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

• csr_descr_C – [in] descriptor of the sparse CSR matrix \(C\). Currently, only rocsparse_matrix_type_general is supported.

• csr_val_C – [out] array of nnz_C elements containing the values of the sparse CSR matrix \(C\).

• csr_row_ptr_C – [in] array of m+1 elements that point to the start of every row of the sparse CSR matrix \(C\).

• csr_col_ind_C – [out] array of nnz_C elements containing the column indices of the sparse CSR matrix \(C\).

• info – [in] prune info structure.

• temp_buffer – [in] buffer allocated by the user whose size is determined by calling rocsparse_Xprune_csr2csr_buffer_size().

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m or n or nnz_A or percentage is invalid.

• rocsparse_status_invalid_pointer – csr_descr_A or csr_descr_C or info or csr_val_A or csr_row_ptr_A or csr_col_ind_A or csr_val_C or csr_row_ptr_C or csr_col_ind_C or temp_buffer pointer is invalid.

rocsparse_rocsparse_bsrpad_value()

rocsparse_status rocsparse_sbsrpad_value(rocsparse_handle handle, rocsparse_int m, rocsparse_int mb, rocsparse_int nnzb, rocsparse_int block_dim, float value, const rocsparse_mat_descr bsr_descr, float *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind)

rocsparse_status rocsparse_dbsrpad_value(rocsparse_handle handle, rocsparse_int m, rocsparse_int mb, rocsparse_int nnzb, rocsparse_int block_dim, double value, const rocsparse_mat_descr bsr_descr, double *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind)

rocsparse_status rocsparse_cbsrpad_value(rocsparse_handle handle, rocsparse_int m, rocsparse_int mb, rocsparse_int nnzb, rocsparse_int block_dim, rocsparse_float_complex value, const rocsparse_mat_descr bsr_descr, rocsparse_float_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind)

rocsparse_status rocsparse_zbsrpad_value(rocsparse_handle handle, rocsparse_int m, rocsparse_int mb, rocsparse_int nnzb, rocsparse_int block_dim, rocsparse_double_complex value, const rocsparse_mat_descr bsr_descr, rocsparse_double_complex *bsr_val, const rocsparse_int *bsr_row_ptr, const rocsparse_int *bsr_col_ind)

Pads a value to the diagonal of the last block (if the last block is a diagonal block) in the sparse BSR matrix when the matrix expands outside m x m.

When converting from a CSR matrix to a BSR matrix the resulting BSR matrix will be larger when m < mb * block_dim. In these situations, the CSR to BSR conversion will expand the BSR matrix to have zeros when outside m x m. This routine converts the resulting BSR matrix to one that has a value on the last diagonal blocks diagonal if this last block is a diagonal block in the BSR matrix.

Note

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

Note

This routine supports execution in a hipGraph context.

Parameters:

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

• m – [in] number of rows of the sparse BSR matrix.

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

• nnzb – [in] number of non-zero blocks of the sparse BSR matrix.

• block_dim – [in] block dimension of the sparse BSR matrix.

• value – [in] scalar value that is set on the diagonal of the last block when the matrix expands outside of m x m

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

• bsr_val – [inout] array of nnzb blocks of the sparse BSR matrix.

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

• bsr_col_ind – [in] array of nnzb elements containing the block column indices of the sparse BSR matrix.

Return values:

• rocsparse_status_success – the operation completed successfully.

• rocsparse_status_invalid_handle – the library context was not initialized.

• rocsparse_status_invalid_size – m, mb, nnzb or block_dim is invalid.

• rocsparse_status_invalid_pointer – bsr_descr, bsr_val, bsr_row_ind, bsr_col_ind, pointer is invalid.