aoclsparse_create_?tcsr() - 5.2 English - 68552

AOCL API Guide (68552)
Document ID
68552
Release Date
2025-12-29
Version
5.2 English
aoclsparse_status aoclsparse_create_stcsr(aoclsparse_matrix *mat, const aoclsparse_index_base base, const aoclsparse_int M, const aoclsparse_int N, const aoclsparse_int nnz, aoclsparse_int *row_ptr_L, aoclsparse_int *row_ptr_U, aoclsparse_int *col_idx_L, aoclsparse_int *col_idx_U, float *val_L, float *val_U)#
aoclsparse_status aoclsparse_create_dtcsr(aoclsparse_matrix *mat, const aoclsparse_index_base base, const aoclsparse_int M, const aoclsparse_int N, const aoclsparse_int nnz, aoclsparse_int *row_ptr_L, aoclsparse_int *row_ptr_U, aoclsparse_int *col_idx_L, aoclsparse_int *col_idx_U, double *val_L, double *val_U)#
aoclsparse_status aoclsparse_create_ctcsr(aoclsparse_matrix *mat, const aoclsparse_index_base base, const aoclsparse_int M, const aoclsparse_int N, const aoclsparse_int nnz, aoclsparse_int *row_ptr_L, aoclsparse_int *row_ptr_U, aoclsparse_int *col_idx_L, aoclsparse_int *col_idx_U, aoclsparse_float_complex *val_L, aoclsparse_float_complex *val_U)#
aoclsparse_status aoclsparse_create_ztcsr(aoclsparse_matrix *mat, const aoclsparse_index_base base, const aoclsparse_int M, const aoclsparse_int N, const aoclsparse_int nnz, aoclsparse_int *row_ptr_L, aoclsparse_int *row_ptr_U, aoclsparse_int *col_idx_L, aoclsparse_int *col_idx_U, aoclsparse_double_complex *val_L, aoclsparse_double_complex *val_U)#

Creates a new aoclsparse_matrix based on TCSR (Triangular Compressed Sparse Row) format.

aoclsparse_create_?tcsr creates aoclsparse_matrix and initializes it with input parameters passed. Array data must not be modified by the user while matrix is being used as the pointers are copied, not the data. The input arrays are not modified by the library and the matrix should be destroyed at the end using aoclsparse_destroy().

TCSR matrix structure holds lower triangular (L) and upper triangular (U) part of the matrix separately with diagonal (D) elements stored in both the parts. Both triangles (L+D and D+U) are stored like CSR and assumes partial sorting (L+D and D+U order is followed, but the indices within L or U group may not be sorted)

  • One array with L elements potentially unsorted, followed by D elements in the L+D part for each row of the matrix.

  • Another array with D elements, followed by U elements potentially unsorted in the D+U part for each row of the matrix.

  • Currently TCSR storage format supports only square matrices with full(non-zero) diagonals.

Parameters:

  • mat – [out] The pointer to the TCSR sparse matrix.

  • base – [in] aoclsparse_index_base_zero or aoclsparse_index_base_one.

  • M – [in] Total number of rows in the mat.

  • N – [in] Total number of columns in the mat.

  • nnz – [in] Number of non-zero entries in the mat.

  • row_ptr_L – [in] Array of lower triangular elements that point to the start of every row of the mat in col_idx_L and val_L.

  • row_ptr_U – [in] Array of upper triangular elements that point to the start of every row of the mat in col_idx_U and val_U.

  • col_idx_L – [in] Array of lower triangular elements containing column indices of the mat.

  • col_idx_U – [in] Array of upper triangular elements containing column indices of the mat.

  • val_L – [in] Array of lower triangular elements of the mat.

  • val_U – [in] Array of upper triangular elements of the mat.

Return values:

  • aoclsparse_status_success – The operation completed successfully.

  • aoclsparse_status_invalid_pointer – Pointer given to API is invalid or nullptr.

  • aoclsparse_status_invalid_size – M, N, nnz is invalid.

  • aoclsparse_status_invalid_index_value – Index given for mat is out of matrix bounds depending on base given.

  • aoclsparse_status_invalid_value – The cooridante row_ptr or col_idx is out of matrix bound or mat has duplicate diagonals or mat does not have full diagonals.

  • aoclsparse_status_unsorted_input – The mat is unsorted. It supports only fully sorted and partially sorted matrix as input. The lower triangular part must not contain U elements, the upper triangular part must not contain L elements, and the position of the diagonal element must not be altered.

  • aoclsparse_status_memory_error – Memory allocation for matrix failed.