aoclsparse_create_?bsr() - 5.2 English - 68552

AOCL API Guide (68552)
Document ID
68552
Release Date
2025-12-29
Version
5.2 English
aoclsparse_status aoclsparse_create_sbsr(aoclsparse_matrix *mat, const aoclsparse_index_base base, const aoclsparse_order order, const aoclsparse_int bM, const aoclsparse_int bN, const aoclsparse_int block_dim, aoclsparse_int *row_ptr, aoclsparse_int *col_idx, float *val, bool fast_chck)#
aoclsparse_status aoclsparse_create_dbsr(aoclsparse_matrix *mat, const aoclsparse_index_base base, const aoclsparse_order order, const aoclsparse_int bM, const aoclsparse_int bN, const aoclsparse_int block_dim, aoclsparse_int *row_ptr, aoclsparse_int *col_idx, double *val, bool fast_chck)#
aoclsparse_status aoclsparse_create_cbsr(aoclsparse_matrix *mat, const aoclsparse_index_base base, const aoclsparse_order order, const aoclsparse_int bM, const aoclsparse_int bN, const aoclsparse_int block_dim, aoclsparse_int *row_ptr, aoclsparse_int *col_idx, aoclsparse_float_complex *val, bool fast_chck)#
aoclsparse_status aoclsparse_create_zbsr(aoclsparse_matrix *mat, const aoclsparse_index_base base, const aoclsparse_order order, const aoclsparse_int bM, const aoclsparse_int bN, const aoclsparse_int block_dim, aoclsparse_int *row_ptr, aoclsparse_int *col_idx, aoclsparse_double_complex *val, bool fast_chck)#

Creates a new aoclsparse_matrix based on BSR (Block-compressed Sparse Row) format.

aoclsparse_create_?bsr creates aoclsparse_matrix in BSR format and initializes it with input parameters passed. In BSR format, the matrix is split into a rectangular grid of square blocks of size block_dim, having bM blocks per row and bN blocks per column. Each block containing at least one non-zero is stored as a dense subblock, padded with zeros for the missing elements in the block. All such blocks are stored in the similar fashion to CSR where each element is a block. The elements inside each non-zero block are either stored in row-major or column-major order based on the order parameter. The input arrays are not modified by the library.

Parameters:

  • mat – [out] the pointer to the BSR matrix allocated in the API.

  • base – [in] aoclsparse_index_base_zero or aoclsparse_index_base_one.

  • order – [in] storage order of dense blocks. Possible options are aoclsparse_order_row and aoclsparse_order_column.

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

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

  • block_dim – [in] size of the non-zero blocks of the BSR matrix.

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

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

  • val – [in] array containing the non-zero elements of the BSR matrix. The length of val array must be equal to the length of col_idx multiplied by block_dim*block_dim.

  • fast_chck – [in] flag to perform a minimal and faster validation on the input matrix. If it is set to true, it skips the checks on diagonals/indices/sorting of the matrix.

Return values:

  • aoclsparse_status_success – the operation completed successfully.

  • aoclsparse_status_invalid_pointer – at least one of mat, row_ptr, col_idx or val pointer is NULL.

  • aoclsparse_status_invalid_size – at least one of bM or bN has an invalid size.

  • aoclsparse_status_invalid_value – if block_dim has an invalid value.

  • aoclsparse_status_invalid_index_value – either col_idx or row_ptr value is invalid.

  • aoclsparse_status_memory_error – memory allocation for matrix failed.