muSPARSE API Reference

Functions

	Name
MUSPARSE_EXPORT musparseStatus_t	musparseSetMatDiagType(musparseMatDescr_t descr, musparseDiagType_t diag_type) Specify the matrix diagonal type of a matrix descriptor.
MUSPARSE_EXPORT musparseStatus_t	musparseSetMatFillMode(musparseMatDescr_t descr, musparseFillMode_t fill_mode) Specify the matrix fill mode of a matrix descriptor.
MUSPARSE_EXPORT musparseStatus_t	musparseSetMatIndexBase(musparseMatDescr_t descr, musparseIndexBase_t base) Specify the index base of a matrix descriptor.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsrsv_bufferSize() Sparse triangular solve using BSR storage format.
musparseStatus_t	musparseXbsrsv_analysis() Sparse triangular solve using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsrsv_solve() Sparse triangular solve using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsrsv_zeroPivot(musparseHandle_t handle, musparseMatInfo_t info, muInt * position) Sparse triangular solve using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsrsm_bufferSize() Sparse triangular system solve using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsrsm_analysis() Sparse triangular system solve using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsrsm_solve() Sparse triangular system solve using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsrsm_zeroPivot(musparseHandle_t handle, musparseMatInfo_t info, muInt * position) Sparse triangular system solve using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsrilu0_numericBoost() Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsrilu0_bufferSize() Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsrilu0_analysis() Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.
musparseStatus_t	musparseXbsrilu0() Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsrilu0_zeroPivot(musparseHandle_t handle, musparseMatInfo_t info, muInt * position) Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseCreate(musparseHandle_t * handle) Create a musparse handle.
MUSPARSE_EXPORT musparseStatus_t	musparseDestroy(musparseHandle_t handle) Destroy a musparse handle.
MUSPARSE_EXPORT musparseStatus_t	musparseCreateMatDescr(musparseMatDescr_t * descr) Create a matrix descriptor.
MUSPARSE_EXPORT musparseStatus_t	musparseDestroyMatDescr(musparseMatDescr_t descr) Destroy a matrix descriptor.
musparseDiagType_t	musparseGetMatDiagType(const musparseMatDescr_t descr) Get the matrix diagonal type of a matrix descriptor.
musparseFillMode_t	musparseGetMatFillMode(const musparseMatDescr_t descr) Get the matrix fill mode of a matrix descriptor.
musparseIndexBase_t	musparseGetMatIndexBase(const musparseMatDescr_t descr) Get the index base of a matrix descriptor.
musparseMatrixType_t	musparseGetMatType(const musparseMatDescr_t descr) Get the matrix type of a matrix descriptor.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsrmm() Sparse matrix dense matrix multiplication using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXcsric0_bufferSize() Incomplete Cholesky factorization with 0 fill-ins and no pivoting using CSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXcsric0_analysis() Incomplete Cholesky factorization with 0 fill-ins and no pivoting using CSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXcsric0() Incomplete Cholesky factorization with 0 fill-ins and no pivoting using CSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXcsric0_zeroPivot(musparseHandle_t handle, musparseMatInfo_t info, muInt * position) Incomplete Cholesky factorization with 0 fill-ins and no pivoting using CSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsric0_bufferSize() Incomplete Cholesky factorization with 0 fill-ins and no pivoting using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsric0_analysis() Incomplete Cholesky factorization with 0 fill-ins and no pivoting using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsric0() Incomplete Cholesky factorization with 0 fill-ins and no pivoting using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsric0_zeroPivot(musparseHandle_t handle, musparseMatInfo_t info, muInt * position) Incomplete Cholesky factorization with 0 fill-ins and no pivoting using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXcsrilu0_numericBoost() Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXcsrilu0_bufferSize() Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXcsrilu0_analysis() Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXcsrilu0() Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXcsrilu0_zeroPivot(musparseHandle_t handle, musparseMatInfo_t info, muInt * position) Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseCreateCsr(musparseSpMatDescr_t * descr, int64_t rows, int64_t cols, int64_t nnz, void * csr_row_ptr, void * csr_col_ind, void * csr_val, musparseIndexType_t row_ptr_type, musparseIndexType_t col_ind_type, musparseIndexBase_t idx_base, musparseDataType_t data_type) Create a sparse CSR matrix descriptor.
MUSPARSE_EXPORT musparseStatus_t	musparseCreateDnVec(musparseDnVecDescr_t * descr, int64_t size, void * values, musparseDataType_t data_type) Create a dense vector descriptor.
MUSPARSE_EXPORT musparseStatus_t	musparseDestroyDnVec(musparseDnVecDescr_t descr) Destroy a dense vector descriptor.
MUSPARSE_EXPORT musparseStatus_t	musparseSpMV(musparseHandle_t handle, musparseOperation_t trans, const void * alpha, const musparseSpMatDescr_t mat, const musparseDnVecDescr_t x, const void * beta, const musparseDnVecDescr_t y, musparseDataType_t compute_type, musparseSpMVAlg_t alg, size_t * buffer_size, void * temp_buffer) Sparse matrix vector multiplication.
MUSPARSE_EXPORT musparseStatus_t	musparseXgemvi() Dense matrix sparse vector multiplication.
MUSPARSE_EXPORT musparseStatus_t	musparseSpMM_ex(musparseHandle_t handle, musparseOperation_t trans_A, musparseOperation_t trans_B, const void * alpha, const musparseSpMatDescr_t mat_A, const musparseDnMatDescr_t mat_B, const void * beta, const musparseDnMatDescr_t mat_C, musparseDataType_t compute_type, musparseSpMMAlg_t alg, musparseSpMMStage_t stage, size_t * buffer_size, void * temp_buffer) Sparse matrix dense matrix multiplication, extension routine.
MUSPARSE_EXPORT musparseStatus_t	musparseSpMM(musparseHandle_t handle, musparseOperation_t trans_A, musparseOperation_t trans_B, const void * alpha, const musparseSpMatDescr_t mat_A, const musparseDnMatDescr_t mat_B, const void * beta, const musparseDnMatDescr_t mat_C, musparseDataType_t compute_type, musparseSpMMAlg_t alg, musparseSpMMStage_t stage, size_t * buffer_size, void * temp_buffer)
MUSPARSE_EXPORT musparseStatus_t	musparseSpSM(musparseHandle_t handle, musparseOperation_t trans_A, musparseOperation_t trans_B, const void * alpha, const musparseSpMatDescr_t matA, const musparseDnMatDescr_t matB, const musparseDnMatDescr_t matC, musparseDataType_t compute_type, musparseSpSMAlg_t alg, musparseSpSMStage_t stage, size_t * buffer_size, void * temp_buffer) Sparse triangular system solve.
MUSPARSE_EXPORT musparseStatus_t	musparseSpGEMM(musparseHandle_t handle, musparseOperation_t trans_A, musparseOperation_t trans_B, const void * alpha, const musparseSpMatDescr_t A, const musparseSpMatDescr_t B, const void * beta, const musparseSpMatDescr_t D, musparseSpMatDescr_t C, musparseDataType_t compute_type, musparseSpGEMMAlg_t alg, musparseSpGEMMStage_t stage, size_t * buffer_size, void * temp_buffer) Sparse matrix sparse matrix multiplication.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsrmv() Sparse matrix vector multiplication using BSR storage format.
MUSPARSE_EXPORT musparseStatus_t	musparseXbsr2csr() Convert a sparse BSR matrix into a sparse CSR matrix.
MUSPARSE_EXPORT musparseStatus_t	musparseXcsr2bsr() Convert a sparse CSR matrix into a sparse BSR matrix.
MUSPARSE_EXPORT musparseStatus_t	musparseSparseToDense(musparseHandle_t handle, const musparseSpMatDescr_t mat_A, musparseDnMatDescr_t mat_B, musparseSparseToDenseAlg_t alg, size_t * buffer_size, void * temp_buffer) Sparse matrix to dense matrix conversion.
MUSPARSE_EXPORT musparseStatus_t	musparseDenseToSparse(musparseHandle_t handle, const musparseDnMatDescr_t mat_A, musparseSpMatDescr_t mat_B, musparseDenseToSparseAlg_t alg, size_t * buffer_size, void * temp_buffer) Dense matrix to sparse matrix conversion.
MUSPARSE_EXPORT musparseStatus_t	musparseAxpby(musparseHandle_t handle, const void * alpha, const musparseSpVecDescr_t x, const void * beta, musparseDnVecDescr_t y) Scale a sparse vector and add it to a scaled dense vector.
MUSPARSE_EXPORT musparseStatus_t	musparseSpVV(musparseHandle_t handle, musparseOperation_t trans, const musparseSpVecDescr_t x, const musparseDnVecDescr_t y, void * result, musparseDataType_t compute_type, size_t * buffer_size, void * temp_buffer) Sparse vector inner dot product.
MUSPARSE_EXPORT musparseStatus_t	musparseSpSV(musparseHandle_t handle, musparseOperation_t trans, const void * alpha, const musparseSpMatDescr_t mat, const musparseDnVecDescr_t x, const musparseDnVecDescr_t y, musparseDataType_t compute_type, musparseSpSVAlg_t alg, musparseSpSVStage_t stage, size_t * buffer_size, void * temp_buffer) Sparse triangular solve.

Functions Documentation

function musparseSetMatDiagType

MUSPARSE_EXPORT musparseStatus_t musparseSetMatDiagType(
    musparseMatDescr_t descr,
    musparseDiagType_t diag_type
)

Specify the matrix diagonal type of a matrix descriptor.

Parameters:

descr the matrix descriptor.
diag_type MUSPARSE_DIAG_TYPE_UNIT or MUSPARSE_DIAG_TYPE_NON_UNIT.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_POINTER descr pointer is invalid.
MUSPARSE_STATUS_INVALID_VALUE diag_type is invalid.

musparseSetMatDiagType sets the matrix diagonal type of a matrix descriptor. Valid diagonal types are MUSPARSE_DIAG_TYPE_UNIT or MUSPARSE_DIAG_TYPE_NON_UNIT.

function musparseSetMatFillMode

MUSPARSE_EXPORT musparseStatus_t musparseSetMatFillMode(
    musparseMatDescr_t descr,
    musparseFillMode_t fill_mode
)

Specify the matrix fill mode of a matrix descriptor.

Parameters:

descr the matrix descriptor.
fill_mode MUSPARSE_FILL_MODE_LOWER or MUSPARSE_FILL_MODE_UPPER.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_POINTER descr pointer is invalid.
MUSPARSE_STATUS_INVALID_VALUE fill_mode is invalid.

musparseSetMatFillMode sets the matrix fill mode of a matrix descriptor. Valid fill modes are MUSPARSE_FILL_MODE_LOWER or MUSPARSE_FILL_MODE_UPPER.

function musparseSetMatIndexBase

MUSPARSE_EXPORT musparseStatus_t musparseSetMatIndexBase(
    musparseMatDescr_t descr,
    musparseIndexBase_t base
)

Specify the index base of a matrix descriptor.

Parameters:

descr the matrix descriptor.
base MUSPARSE_INDEX_BASE_ZERO or MUSPARSE_INDEX_BASE_ONE.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_POINTER descr pointer is invalid.
MUSPARSE_STATUS_INVALID_VALUE base is invalid.

musparseSetMatIndexBase sets the index base of a matrix descriptor. Valid options are MUSPARSE_INDEX_BASE_ZERO or MUSPARSE_INDEX_BASE_ONE.

function musparseXbsrsv_bufferSize

MUSPARSE_EXPORT musparseStatus_t musparseXbsrsv_bufferSize()

Sparse triangular solve using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
dir matrix storage of BSR blocks.
trans matrix operation type.
mb number of block rows of the sparse BSR matrix.
nnzb number of non-zero blocks of the sparse BSR matrix.
descr descriptor of the sparse BSR matrix.
bsr_val array of nnzb blocks of the sparse BSR matrix.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix.
bsr_col_ind array of nnz containing the block column indices of the sparse BSR matrix.
block_dim block dimension of the sparse BSR matrix.
info structure that holds the information collected during the analysis step.
buffer_size number of bytes of the temporary storage buffer required by musparseSbsrsv_analysis(), musparseDbsrsv_analysis(), musparseCbsrsv_analysis(), musparseZbsrsv_analysis(), musparseSbsrsv_solve(), musparseDbsrsv_solve(), musparseCbsrsv_solve() and musparseZbsrsv_solve().

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb, nnzb or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER descr, bsr_val, bsr_row_ptr, bsr_col_ind, info or buffer_size pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans == MUSPARSE_OPERATION_CONJUGATE_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

musparseXbsrsv_bufferSize returns the size of the temporary storage buffer that is required by musparseSbsrsv_analysis(), musparseDbsrsv_analysis(), musparseCbsrsv_analysis(), musparseZbsrsv_analysis(), musparseSbsrsv_solve(), musparseDbsrsv_solve(), musparseCbsrsv_solve() and musparseZbsrsv_solve(). The temporary storage buffer must be allocated by the user.

musparseStatus_t musparseSbsrsv_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir, musparseOperation_t trans,
    muInt mb, muInt nnzb, const musparseMatDescr_t descr, const float* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, size_t* buffer_size);

musparseStatus_t musparseDbsrsv_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir, musparseOperation_t trans,
    muInt mb, muInt nnzb, const musparseMatDescr_t descr, const double* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, size_t* buffer_size);

musparseStatus_t musparseCbsrsv_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir, musparseOperation_t trans,
    muInt mb, muInt nnzb, const musparseMatDescr_t descr,
    const muComplex* bsr_val, const muInt* bsr_row_ptr,
    const muInt* bsr_col_ind, muInt block_dim, musparseMatInfo_t info,
    size_t* buffer_size);

musparseStatus_t musparseZbsrsv_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir, musparseOperation_t trans,
    muInt mb, muInt nnzb, const musparseMatDescr_t descr,
    const muDoubleComplex* bsr_val, const muInt* bsr_row_ptr,
    const muInt* bsr_col_ind, muInt block_dim, musparseMatInfo_t info,
    size_t* buffer_size);

function musparseXbsrsv_analysis

musparseStatus_t musparseXbsrsv_analysis()

Sparse triangular solve using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
dir matrix storage of BSR blocks.
trans matrix operation type.
mb number of block rows of the sparse BSR matrix.
nnzb number of non-zero blocks of the sparse BSR matrix.
descr descriptor of the sparse BSR matrix.
bsr_val array of nnzb blocks of the sparse BSR matrix.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix.
bsr_col_ind array of nnz containing the block column indices of the sparse BSR matrix.
block_dim block dimension of the sparse BSR matrix.
info structure that holds the information collected during the analysis step.
analysis MUSPARSE_ANALYSIS_POLICY_REUSE or MUSPARSE_ANALYSIS_POLICY_FORCE.
solve MUSPARSE_SOLVE_POLICY_USE_LEVEL.
temp_buffer temporary storage buffer allocated by the user.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb, nnzb or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER descr, bsr_row_ptr, bsr_col_ind, info or temp_buffer pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans == MUSPARSE_OPERATION_CONJUGATE_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

Note:

If the matrix sparsity pattern changes, the gathered information will become invalid.
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

musparseXbsrsv_analysis performs the analysis step for musparseSbsrsv_solve(), musparseDbsrsv_solve(), musparseCbsrsv_solve() and musparseZbsrsv_solve(). It is expected that this function will be executed only once for a given matrix and particular operation type. The analysis meta data can be cleared by musparseXbsrsv_clear().

musparseXbsrsv_analysis can share its meta data with musparseSbsrsm_analysis(), musparseDbsrsm_analysis(), musparseCbsrsm_analysis(), musparseZbsrsm_analysis(), musparseSbsrilu0_analysis(), musparseDbsrilu0_analysis(), musparseCbsrilu0_analysis(), musparseZbsrilu0_analysis(), musparseSbsric0_analysis(), musparseDbsric0_analysis(), musparseCbsric0_analysis() and musparseZbsric0_analysis(). Selecting MUSPARSE_ANALYSIS_POLICY_REUSE policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, MUSPARSE_ANALYSIS_POLICY_FORCE has to be used.

musparseStatus_t musparseSbsrsv_analysis(
    musparseHandle_t handle, musparseDirection_t dir, musparseOperation_t trans,
    muInt mb, muInt nnzb, const musparseMatDescr_t descr, const float* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);

musparseStatus_t musparseDbsrsv_analysis(
    musparseHandle_t handle, musparseDirection_t dir, musparseOperation_t trans,
    muInt mb, muInt nnzb, const musparseMatDescr_t descr, const double* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);

musparseStatus_t musparseCbsrsv_analysis(
    musparseHandle_t handle, musparseDirection_t dir, musparseOperation_t trans,
    muInt mb, muInt nnzb, const musparseMatDescr_t descr,
    const muComplex* bsr_val, const muInt* bsr_row_ptr,
    const muInt* bsr_col_ind, muInt block_dim, musparseMatInfo_t info,
    musparseAnalysisPolicy_t analysis, musparseSolvePolicy_t solve,
    void* temp_buffer);

musparseStatus_t musparseZbsrsv_analysis(
    musparseHandle_t handle, musparseDirection_t dir, musparseOperation_t trans,
    muInt mb, muInt nnzb, const musparseMatDescr_t descr,
    const muDoubleComplex* bsr_val, const muInt* bsr_row_ptr,
    const muInt* bsr_col_ind, muInt block_dim, musparseMatInfo_t info,
    musparseAnalysisPolicy_t analysis, musparseSolvePolicy_t solve,
    void* temp_buffer);

function musparseXbsrsv_solve

MUSPARSE_EXPORT musparseStatus_t musparseXbsrsv_solve()

Sparse triangular solve using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
dir matrix storage of BSR blocks.
trans matrix operation type.
mb number of block rows of the sparse BSR matrix.
nnzb number of non-zero blocks of the sparse BSR matrix.
alpha scalar $\alpha$ .
descr descriptor of the sparse BSR matrix.
bsr_val array of nnzb blocks of the sparse BSR matrix.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix.
bsr_col_ind array of nnz containing the block column indices of the sparse BSR matrix.
block_dim block dimension of the sparse BSR matrix.
info structure that holds the information collected during the analysis step.
x array of m elements, holding the right-hand side.
y array of m elements, holding the solution.
policy MUSPARSE_SOLVE_POLICY_USE_LEVEL.
temp_buffer temporary storage buffer allocated by the user.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb, nnzb or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER descr, alpha, bsr_val, bsr_row_ptr, bsr_col_ind, x or y pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_ARCH_MISMATCH the the device is not supported.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans == MUSPARSE_OPERATION_CONJUGATE_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

Note:

The sparse BSR matrix has to be sorted.
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.
Currently, only trans == MUSPARSE_OPERATION_NON_TRANSPOSE and trans == MUSPARSE_OPERATION_TRANSPOSE is supported.

Example:

Consider the lower triangular $m \times m$ matrix $L$ , stored in BSR storage format with unit diagonal. The following example solves $L \cdot y = x$ .

// Create musparse handle
musparseHandle_t handle;
musparseCreate(&handle);

// Create matrix descriptor
musparseMatDescr_t descr;
musparseCreateMatDescr(&descr);
musparseSetMatFillMode(descr, MUSPARSE_FILL_MODE_LOWER);
musparseSetMatDiagType(descr, MUSPARSE_DIAG_TYPE_UNIT);

// Create matrix info structure
musparseMatInfo_t info;
musparseCreateMatInfo(&info);

// Obtain required buffer size
size_t buffer_size;
musparseDbsrsv_bufferSize(handle,
                             MUSPARSE_DIRECTION_COLUMN,
                             MUSPARSE_OPERATION_NON_TRANSPOSE,
                             mb,
                             nnzb,
                             descr,
                             bsr_val,
                             bsr_row_ptr,
                             bsr_col_ind,
                             block_dim,
                             info,
                             &buffer_size);

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

// Perform analysis step
musparseDbsrsv_analysis(handle,
                          MUSPARSE_DIRECTION_COLUMN,
                          MUSPARSE_OPERATION_NON_TRANSPOSE,
                          mb,
                          nnzb,
                          descr,
                          bsr_val,
                          bsr_row_ptr,
                          bsr_col_ind,
                          block_dim,
                          info,
                          MUSPARSE_ANALYSIS_POLICY_REUSE,
                          MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                          temp_buffer);

// Solve Ly = x
musparseDbsrsv_solve(handle,
                       MUSPARSE_DIRECTION_COLUMN,
                       MUSPARSE_OPERATION_NON_TRANSPOSE,
                       mb,
                       nnzb,
                       &alpha,
                       descr,
                       bsr_val,
                       bsr_row_ptr,
                       bsr_col_ind,
                       block_dim,
                       info,
                       x,
                       y,
                       MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                       temp_buffer);

// No zero pivot should be found, with L having unit diagonal

// Clean up
musaFree(temp_buffer);
musparseDestroyMatInfo(info);
musparseDestroyMatDescr(descr);
musparseDestroy(handle);

musparseXbsrsv_solve solves a sparse triangular linear system of a sparse $m \times m$ matrix, defined in BSR storage format, a dense solution vector $y$ and the right-hand side $x$ that is multiplied by $\alpha$ , such that:

op(A) \cdot y = \alpha \cdot x,

with

op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == \text{MUSPARSE\_OPERATION\_NON\_TRANSPOSE}} \\ A^T, & \text{if trans == \text{MUSPARSE\_OPERATION\_TRANSPOSE}} \\ A^H, & \text{if trans == \text{MUSPARSE\_OPERATION\_CONJUGATE\_TRANSPOSE}} \end{array} \right.

musparseXbsrsv_solve requires a user allocated temporary buffer. Its size is returned by musparseSbsrsv_bufferSize(), musparseDbsrsv_bufferSize(), musparseCbsrsv_bufferSize() or musparseZbsrsv_bufferSize(). Furthermore, analysis meta data is required. It can be obtained by musparseSbsrsv_analysis(), musparseDbsrsv_analysis(), musparseCbsrsv_analysis() or musparseZbsrsv_analysis(). musparseXbsrsv_solve reports the first zero pivot (either numerical or structural zero). The zero pivot status can be checked calling musparseXbsrsv_zeroPivot(). If musparseDiagType_t == MUSPARSE_DIAG_TYPE_UNIT, no zero pivot will be reported, even if $A_{j,j} = 0$ for some $j$ .

musparseStatus_t musparseSbsrsv_solve(
    musparseHandle_t handle, musparseDirection_t dir, musparseOperation_t trans,
    muInt mb, muInt nnzb, const float* alpha, const musparseMatDescr_t descr,
    const float* bsr_val, const muInt* bsr_row_ptr, const muInt* bsr_col_ind,
    muInt block_dim, musparseMatInfo_t info, const float* x, float* y,
    musparseSolvePolicy_t policy, void* temp_buffer);
 
musparseStatus_t musparseDbsrsv_solve(
    musparseHandle_t handle, musparseDirection_t dir, musparseOperation_t trans,
    muInt mb, muInt nnzb, const double* alpha, const musparseMatDescr_t descr,
    const double* bsr_val, const muInt* bsr_row_ptr, const muInt* bsr_col_ind,
    muInt block_dim, musparseMatInfo_t info, const double* x, double* y,
    musparseSolvePolicy_t policy, void* temp_buffer);
  
musparseStatus_t musparseCbsrsv_solve(
    musparseHandle_t handle, musparseDirection_t dir, musparseOperation_t trans,
    muInt mb, muInt nnzb, const muComplex* alpha,
    const musparseMatDescr_t descr, const muComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, const muComplex* x, muComplex* y,
    musparseSolvePolicy_t policy, void* temp_buffer);
 
musparseStatus_t musparseZbsrsv_solve(
    musparseHandle_t handle, musparseDirection_t dir, musparseOperation_t trans,
    muInt mb, muInt nnzb, const muDoubleComplex* alpha,
    const musparseMatDescr_t descr, const muDoubleComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, const muDoubleComplex* x, muDoubleComplex* y,
    musparseSolvePolicy_t policy, void* temp_buffer);

function musparseXbsrsv_zeroPivot

MUSPARSE_EXPORT musparseStatus_t musparseXbsrsv_zeroPivot(
    musparseHandle_t handle,
    musparseMatInfo_t info,
    muInt * position
)

Sparse triangular solve using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
info structure that holds the information collected during the analysis step.
position pointer to zero pivot $j$ , can be in host or device memory.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER info or position pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_ZERO_PIVOT zero pivot has been found.

Note: musparseXbsrsv_zeroPivot is a blocking function. It might influence performance negatively.

musparseXbsrsv_zeroPivot returns MUSPARSE_EXPORT MUSPARSE_STATUS_ZERO_PIVOT, if either a structural or numerical zero has been found during musparseSbsrsv_solve(), musparseDbsrsv_solve(), musparseCbsrsv_solve() or musparseZbsrsv_solve() computation. The first zero pivot $j$ at $A_{j,j}$ is stored in position, using same index base as the BSR matrix.

musparseXbsrsv_zeroPivot returns MUSPARSE_EXPORT MUSPARSE_STATUS_ZERO_PIVOT if either a structural or numerical zero has been found during musparseSbsrsv_solve(), musparseDbsrsv_solve(), musparseCbsrsv_solve(), or musparseZbsrsv_solve() computation. The first zero pivot $j$ at $A_{j,j}$ is stored in position, using the same index base as the BSR matrix.

position can be in host or device memory. If no zero pivot has been found, position is set to -1 and MUSPARSE_STATUS_SUCCESS is returned instead.

function musparseXbsrsm_bufferSize

MUSPARSE_EXPORT musparseStatus_t musparseXbsrsm_bufferSize()

Sparse triangular system solve using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
dir matrix storage of BSR blocks.
trans_A matrix A operation type.
trans_X matrix X operation type.
mb number of block rows of the sparse BSR matrix A.
nrhs number of columns of the dense matrix op(X).
nnzb number of non-zero blocks of the sparse BSR matrix A.
descr descriptor of the sparse BSR matrix A.
bsr_val array of nnzb blocks of the sparse BSR matrix.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix.
bsr_col_ind array of nnzb containing the block column indices of the sparse BSR matrix.
block_dim block dimension of the sparse BSR matrix.
info structure that holds the information collected during the analysis step.
buffer_size number of bytes of the temporary storage buffer required by musparseSbsrsm_analysis(), musparseDbsrsm_analysis(), musparseCbsrsm_analysis(), musparseZbsrsm_analysis(), musparseSbsrsm_solve(), musparseDbsrsm_solve(), musparseCbsrsm_solve() and musparseZbsrsm_solve().

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb, nrhs, nnzb or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER descr, bsr_val, bsr_row_ptr, bsr_col_ind, info or buffer_size pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans_A == MUSPARSE_OPERATION_CONJUGATE_TRANSPOSE, trans_X == MUSPARSE_OPERATION_CONJUGATE_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

musparseXbsrsm_bufferSize returns the size of the temporary storage buffer that is required by musparseSbsrsm_analysis(), musparseDbsrsm_analysis(), musparseCbsrsm_analysis(), musparseZbsrsm_analysis(), musparseSbsrsm_solve(), musparseDbsrsm_solve(), musparseCbsrsm_solve() and musparseZbsrsm_solve(). The temporary storage buffer must be allocated by the user.

musparseStatus_t musparseSbsrsm_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_X, muInt mb,
    muInt nrhs, muInt nnzb, const musparseMatDescr_t descr,
    const float* bsr_val, const muInt* bsr_row_ptr, const muInt* bsr_col_ind,
    muInt block_dim, musparseMatInfo_t info, size_t* buffer_size);
 
musparseStatus_t musparseDbsrsm_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_X, muInt mb,
    muInt nrhs, muInt nnzb, const musparseMatDescr_t descr,
    const double* bsr_val, const muInt* bsr_row_ptr, const muInt* bsr_col_ind,
    muInt block_dim, musparseMatInfo_t info, size_t* buffer_size);
 
musparseStatus_t musparseCbsrsm_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_X, muInt mb,
    muInt nrhs, muInt nnzb, const musparseMatDescr_t descr,
    const muComplex* bsr_val, const muInt* bsr_row_ptr,
    const muInt* bsr_col_ind, muInt block_dim, musparseMatInfo_t info,
    size_t* buffer_size);
 
musparseStatus_t musparseZbsrsm_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_X, muInt mb,
    muInt nrhs, muInt nnzb, const musparseMatDescr_t descr,
    const muDoubleComplex* bsr_val, const muInt* bsr_row_ptr,
    const muInt* bsr_col_ind, muInt block_dim, musparseMatInfo_t info,
    size_t* buffer_size);

function musparseXbsrsm_analysis

MUSPARSE_EXPORT musparseStatus_t musparseXbsrsm_analysis()

Sparse triangular system solve using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
dir matrix storage of BSR blocks.
trans_A matrix A operation type.
trans_X matrix X operation type.
mb number of block rows of the sparse BSR matrix A.
nrhs number of columns of the dense matrix op(X).
nnzb number of non-zero blocks of the sparse BSR matrix A.
descr descriptor of the sparse BSR matrix A.
bsr_val array of nnzb blocks of the sparse BSR matrix A.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix A.
bsr_col_ind array of nnzb containing the block column indices of the sparse BSR matrix A.
block_dim block dimension of the sparse BSR matrix A.
info structure that holds the information collected during the analysis step.
analysis MUSPARSE_ANALYSIS_POLICY_REUSE or MUSPARSE_ANALYSIS_POLICY_FORCE.
solve MUSPARSE_SOLVE_POLICY_USE_LEVEL.
temp_buffer temporary storage buffer allocated by the user.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb, nrhs, nnzb or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER descr, bsr_val, bsr_row_ptr, bsr_col_ind, info or temp_buffer pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans_A == MUSPARSE_OPERATION_CONJUGATE_TRANSPOSE, trans_X == MUSPARSE_OPERATION_CONJUGATE_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

Note:

If the matrix sparsity pattern changes, the gathered information will become invalid.
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

musparseXbsrsm_analysis performs the analysis step for musparseSbsrsm_solve(), musparseDbsrsm_solve(), musparseCbsrsm_solve() and musparseZbsrsm_solve(). It is expected that this function will be executed only once for a given matrix and particular operation type. The analysis meta data can be cleared by musparseXbsrsm_clear().

musparseXbsrsm_analysis can share its meta data with musparseSbsrilu0_analysis(), musparseDbsrilu0_analysis(), musparseCbsrilu0_analysis(), musparseZbsrilu0_analysis(), musparseSbsric0_analysis(), musparseDbsric0_analysis(), musparseCbsric0_analysis(), musparseZbsric0_analysis(), musparseSbsrsv_analysis(), musparseDbsrsv_analysis(), musparseCbsrsv_analysis() and musparseZbsrsv_analysis(). Selecting MUSPARSE_ANALYSIS_POLICY_REUSE policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, MUSPARSE_ANALYSIS_POLICY_FORCE has to be used.

musparseStatus_t musparseSbsrsm_analysis(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_X, muInt mb,
    muInt nrhs, muInt nnzb, const musparseMatDescr_t descr,
    const float* bsr_val, const muInt* bsr_row_ptr, const muInt* bsr_col_ind,
    muInt block_dim, musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);

 
musparseStatus_t musparseDbsrsm_analysis(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_X, muInt mb,
    muInt nrhs, muInt nnzb, const musparseMatDescr_t descr,
    const double* bsr_val, const muInt* bsr_row_ptr, const muInt* bsr_col_ind,
    muInt block_dim, musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);
 
musparseStatus_t musparseCbsrsm_analysis(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_X, muInt mb,
    muInt nrhs, muInt nnzb, const musparseMatDescr_t descr,
    const muComplex* bsr_val, const muInt* bsr_row_ptr,
    const muInt* bsr_col_ind, muInt block_dim, musparseMatInfo_t info,
    musparseAnalysisPolicy_t analysis, musparseSolvePolicy_t solve,
    void* temp_buffer);
 
musparseStatus_t musparseZbsrsm_analysis(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_X, muInt mb,
    muInt nrhs, muInt nnzb, const musparseMatDescr_t descr,
    const muDoubleComplex* bsr_val, const muInt* bsr_row_ptr,
    const muInt* bsr_col_ind, muInt block_dim, musparseMatInfo_t info,
    musparseAnalysisPolicy_t analysis, musparseSolvePolicy_t solve,
    void* temp_buffer);

function musparseXbsrsm_solve

MUSPARSE_EXPORT musparseStatus_t musparseXbsrsm_solve()

Sparse triangular system solve using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
dir matrix storage of BSR blocks.
trans_A matrix A operation type.
trans_X matrix X operation type.
mb number of block rows of the sparse BSR matrix A.
nrhs number of columns of the dense matrix op(X).
nnzb number of non-zero blocks of the sparse BSR matrix A.
alpha scalar $\alpha$ .
descr descriptor of the sparse BSR matrix A.
bsr_val array of nnzb blocks of the sparse BSR matrix.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix.
bsr_col_ind array of nnzb containing the block column indices of the sparse BSR matrix.
block_dim block dimension of the sparse BSR matrix.
info structure that holds the information collected during the analysis step.
B rhs matrix B with leading dimension ldb.
ldb leading dimension of rhs matrix B.
X solution matrix X with leading dimension ldx.
ldx leading dimension of solution matrix X.
policy MUSPARSE_SOLVE_POLICY_USE_LEVEL.
temp_buffer temporary storage buffer allocated by the user.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb, nrhs, nnzb or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER alpha, descr, bsr_val, bsr_row_ptr, bsr_col_ind, B, X``info or temp_buffer pointer is invalid. *
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred. * *
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans_A == MUSPARSE_OPERATION_CONJUGATE_TRANSPOSE, trans_X == MUSPARSE_OPERATION_CONJUGATE_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

Note:

The sparse BSR matrix has to be sorted.
Operation type of B and X must match, if $op(B)=B, op(X)=X$ .
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.
Currently, only trans_A != MUSPARSE_OPERATION_CONJUGATE_TRANSPOSE and trans_X != MUSPARSE_OPERATION_CONJUGATE_TRANSPOSE is supported.

musparseXbsrsm_solve solves a sparse triangular linear system of a sparse $m \times m$ matrix, defined in BSR storage format, a dense solution matrix $X$ and the right-hand side matrix $B$ that is multiplied by $\alpha$ , such that

op(A) \cdot op(X) = \alpha \cdot op(B),

with

op(A) = \begin{cases} A, & \text{if trans\_A == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \\ A^T, & \text{if trans\_A == MUSPARSE\_OPERATION\_TRANSPOSE} \\ A^H, & \text{if trans\_A == MUSPARSE\_OPERATION\_CONJUGATE\_TRANSPOSE} \end{cases}

and

op(X) = \begin{cases} X, & \text{if trans\_X == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \\ X^T, & \text{if trans\_X == MUSPARSE\_OPERATION\_TRANSPOSE} \\ X^H, & \text{if trans\_X == MUSPARSE\_OPERATION\_CONJUGATE\_TRANSPOSE} \end{cases}

musparseXbsrsm_solve requires a user allocated temporary buffer. Its size is returned by musparseSbsrsm_bufferSize(), musparseDbsrsm_bufferSize(), musparseCbsrsm_bufferSize() or musparseZbsrsm_bufferSize(). Furthermore, analysis meta data is required. It can be obtained by musparseSbsrsm_analysis(), musparseDbsrsm_analysis(), musparseCbsrsm_analysis() or musparseZbsrsm_analysis(). musparseXbsrsm_solve reports the first zero pivot (either numerical or structural zero). The zero pivot status can be checked calling [musparseXbsrsm_zeroPivot()]. If musparseDiagType_t == MUSPARSE_DIAG_TYPE_UNIT, no zero pivot will be reported, even if $A_{j,j} = 0$ for some $j$ .

musparseStatus_t musparseSbsrsm_solve(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_X, muInt mb,
    muInt nrhs, muInt nnzb, const float* alpha, const musparseMatDescr_t descr,
    const float* bsr_val, const muInt* bsr_row_ptr, const muInt* bsr_col_ind,
    muInt block_dim, musparseMatInfo_t info, const float* B, muInt ldb,
    float* X, muInt ldx, musparseSolvePolicy_t policy, void* temp_buffer);
 
musparseStatus_t musparseDbsrsm_solve(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_X, muInt mb,
    muInt nrhs, muInt nnzb, const double* alpha, const musparseMatDescr_t descr,
    const double* bsr_val, const muInt* bsr_row_ptr, const muInt* bsr_col_ind,
    muInt block_dim, musparseMatInfo_t info, const double* B, muInt ldb,
    double* X, muInt ldx, musparseSolvePolicy_t policy, void* temp_buffer);
 
musparseStatus_t musparseCbsrsm_solve(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_X, muInt mb,
    muInt nrhs, muInt nnzb, const muComplex* alpha,
    const musparseMatDescr_t descr, const muComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, const muComplex* B, muInt ldb, muComplex* X,
    muInt ldx, musparseSolvePolicy_t policy, void* temp_buffer);
 
musparseStatus_t musparseZbsrsm_solve(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_X, muInt mb,
    muInt nrhs, muInt nnzb, const muDoubleComplex* alpha,
    const musparseMatDescr_t descr, const muDoubleComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, const muDoubleComplex* B, muInt ldb,
    muDoubleComplex* X, muInt ldx, musparseSolvePolicy_t policy,
    void* temp_buffer);

function musparseXbsrsm_zeroPivot

MUSPARSE_EXPORT musparseStatus_t musparseXbsrsm_zeroPivot(
    musparseHandle_t handle,
    musparseMatInfo_t info,
    muInt * position
)

Sparse triangular system solve using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
info structure that holds the information collected during the analysis step.
position pointer to zero pivot $j$ , can be in host or device memory.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER info or position pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_ZERO_PIVOT zero pivot has been found.

Note: musparseXbsrsm_zeroPivot is a blocking function. It might influence performance negatively.

musparseXbsrsm_zeroPivot returns MUSPARSE_EXPORT MUSPARSE_STATUS_ZERO_PIVOT, if either a structural or numerical zero has been found during musparseSbsrsm_solve(), musparseDbsrsm_solve(), musparseCbsrsm_solve() or musparseZbsrsm_solve() computation. The first zero pivot $j$ at $A_{j,j}$ is stored in position, using same index base as the BSR matrix.

position can be in host or device memory. If no zero pivot has been found, position is set to -1 and MUSPARSE_STATUS_SUCCESS is returned instead.

function musparseXbsrilu0_numericBoost

MUSPARSE_EXPORT musparseStatus_t musparseXbsrilu0_numericBoost()

Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
info structure that holds the information collected during the analysis step.
enable_boost enable/disable numeric boost.
boost_tol tolerance to determine whether a numerical value is replaced or not.
boost_val boost value to replace a numerical value.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER info, tol or boost_val pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.

Note:

The boost value is enabled by setting enable_boost to 1 or disabled by setting enable_boost to 0.
tol and boost_val can be in host or device memory.

musparseXbsrilu0_numericBoost enables the user to replace a numerical value in an incomplete LU factorization. tol is used to determine whether a numerical value is replaced by boost_val, such that $A_{j,j} = \text{boost\_val}$ if $\, \text{tol} \ge \left| A_{j,j} \right|.$

musparseStatus_t musparseSbsrilu0_numericBoost(musparseHandle_t handle,
                                               musparseMatInfo_t info,
                                               int enable_boost,
                                               const float* boost_tol,
                                               const float* boost_val);
 
musparseStatus_t musparseDbsrilu0_numericBoost(musparseHandle_t handle,
                                               musparseMatInfo_t info,
                                               int enable_boost,
                                               const double* boost_tol,
                                               const double* boost_val);
 
musparseStatus_t musparseCbsrilu0_numericBoost(musparseHandle_t handle,
                                               musparseMatInfo_t info,
                                               int enable_boost,
                                               const float* boost_tol,
                                               const muComplex* boost_val);
 
musparseStatus_t musparseZbsrilu0_numericBoost(
    musparseHandle_t handle, musparseMatInfo_t info, int enable_boost,
    const double* boost_tol, const muDoubleComplex* boost_val);
 
musparseStatus_t musparseDSbsrilu0_numericBoost(musparseHandle_t handle,
                                                musparseMatInfo_t info,
                                                int enable_boost,
                                                const double* boost_tol,
                                                const float* boost_val);
 
musparseStatus_t musparseDCbsrilu0_numericBoost(musparseHandle_t handle,
                                                musparseMatInfo_t info,
                                                int enable_boost,
                                                const double* boost_tol,
                                                const muComplex* boost_val);

function musparseXbsrilu0_bufferSize

MUSPARSE_EXPORT musparseStatus_t musparseXbsrilu0_bufferSize()

Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
dir direction that specifies whether to count nonzero elements by MUSPARSE_DIRECTION_ROW or by MUSPARSE_DIRECTION_ROW.
mb number of block rows in the sparse BSR matrix.
nnzb number of non-zero block entries of the sparse BSR matrix.
descr descriptor of the sparse BSR matrix.
bsr_val array of length nnzb*block_dim*block_dim containing the values of the sparse BSR matrix.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix.
bsr_col_ind array of nnzb elements containing the block column indices of the sparse BSR matrix.
block_dim the block dimension of the BSR matrix. Between 1 and m where m=mb*block_dim.
info structure that holds the information collected during the analysis step.
buffer_size number of bytes of the temporary storage buffer required by musparseSbsrilu0_analysis(), musparseDbsrilu0_analysis(), musparseCbsrilu0_analysis(), musparseZbsrilu0_analysis(), musparseSbsrilu0(), musparseDbsrilu0(), musparseCbsrilu0() and musparseZbsrilu0().

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb, nnzb, or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER descr, bsr_val, bsr_row_ptr, bsr_col_ind, info or buffer_size pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

musparseXbsrilu0_bufferSize returns the size of the temporary storage buffer that is required by musparseSbsrilu0_analysis(), musparseDbsrilu0_analysis(), musparseCbsrilu0_analysis(), musparseZbsrilu0_analysis(), musparseSbsrilu0(), musparseDbsrilu0(), musparseSbsrilu0() and musparseDbsrilu0(). The temporary storage buffer must be allocated by the user. The size of the temporary storage buffer is identical to the size returned by musparseSbsrsv_bufferSize(), musparseDbsrsv_bufferSize(), musparseCbsrsv_bufferSize(), musparseZbsrsv_bufferSize(), musparseSbsric0_bufferSize(), musparseDbsric0_bufferSize(), musparseCbsric0_bufferSize() and musparseZbsric0_bufferSize() if the matrix sparsity pattern is identical. The user allocated buffer can thus be shared between subsequent calls to those functions.

musparseStatus_t musparseSbsrilu0_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const float* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, size_t* buffer_size);
 
musparseStatus_t musparseDbsrilu0_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const double* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, size_t* buffer_size);
 
musparseStatus_t musparseCbsrilu0_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const muComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, size_t* buffer_size);
 
musparseStatus_t musparseZbsrilu0_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const muDoubleComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, size_t* buffer_size);

function musparseXbsrilu0_analysis

MUSPARSE_EXPORT musparseStatus_t musparseXbsrilu0_analysis()

Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
dir direction that specified whether to count nonzero elements by MUSPARSE_DIRECTION_ROW or by MUSPARSE_DIRECTION_ROW.
mb number of block rows in the sparse BSR matrix.
nnzb number of non-zero block entries of the sparse BSR matrix.
descr descriptor of the sparse BSR matrix.
bsr_val array of length nnzb*block_dim*block_dim containing the values of the sparse BSR matrix.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix.
bsr_col_ind array of nnzb elements containing the block column indices of the sparse BSR matrix.
block_dim the block dimension of the BSR matrix. Between 1 and m where m=mb*block_dim.
info structure that holds the information collected during the analysis step.
analysis MUSPARSE_ANALYSIS_POLICY_REUSE or MUSPARSE_ANALYSIS_POLICY_FORCE.
solve MUSPARSE_SOLVE_POLICY_USE_LEVEL.
temp_buffer temporary storage buffer allocated by the user.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb, nnzb, or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER descr, bsr_val, bsr_row_ptr, bsr_col_ind, info or temp_buffer pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

Note:

If the matrix sparsity pattern changes, the gathered information will become invalid.
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

musparseXbsrilu0_analysis performs the analysis step for musparseSbsrilu0() musparseDbsrilu0(), musparseCbsrilu0(), and musparseZbsrilu0(). It is expected that this function will be executed only once for a given matrix. The analysis meta data can be cleared by musparseXbsrilu0_clear().

musparseXbsrilu0_analysis can share its meta data with musparseSbsric0_analysis(), musparseDbsric0_analysis(), musparseCbsric0_analysis(), musparseZbsric0_analysis(), musparseSbsrsv_analysis(), musparseDbsrsv_analysis(), musparseCbsrsv_analysis(), musparseZbsrsv_analysis(), musparseSbsrsm_analysis(), musparseDbsrsm_analysis(), musparseCbsrsm_analysis() and musparseZbsrsm_analysis(). Selecting MUSPARSE_ANALYSIS_POLICY_REUSE policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, MUSPARSE_ANALYSIS_POLICY_FORCE has to be used.

musparseStatus_t musparseSbsrilu0_analysis(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const float* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);
 
musparseStatus_t musparseDbsrilu0_analysis(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const double* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);
 
musparseStatus_t musparseCbsrilu0_analysis(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const muComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);
 
musparseStatus_t musparseZbsrilu0_analysis(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const muDoubleComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);

function musparseXbsrilu0

musparseStatus_t musparseXbsrilu0()

Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
dir direction that specified whether to count nonzero elements by MUSPARSE_DIRECTION_ROW or by MUSPARSE_DIRECTION_ROW.
mb number of block rows in the sparse BSR matrix.
nnzb number of non-zero block entries of the sparse BSR matrix.
descr descriptor of the sparse BSR matrix.
bsr_val array of length nnzb*block_dim*block_dim containing the values of the sparse BSR matrix.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix.
bsr_col_ind array of nnzb elements containing the block column indices of the sparse BSR matrix.
block_dim the block dimension of the BSR matrix. Between 1 and m where m=mb*block_dim.
info structure that holds the information collected during the analysis step.
policy MUSPARSE_SOLVE_POLICY_USE_LEVEL.
temp_buffer temporary storage buffer allocated by the user.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb, nnzb, or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER descr, bsr_val, bsr_row_ptr or bsr_col_ind pointer is invalid. *
MUSPARSE_EXPORT MUSPARSE_STATUS_ARCH_MISMATCH the device is not supported. *
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred. * *
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

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

Example:

Consider the sparse $m \times m$ matrix $A$ , stored in BSR storage format. The following example computes the incomplete LU factorization $M \approx LU$ and solves the preconditioned system $My = x$ .

     // Create musparse handle
     musparseHandle_t handle;
     musparseCreate(&handle);
   
     // Create matrix descriptor for M
     musparseMatDescr_t descr_M;
     musparseCreateMatDescr(&descr_M);
   
     // Create matrix descriptor for L
     musparseMatDescr_t descr_L;
     musparseCreateMatDescr(&descr_L);
     musparseSetMatFillMode(descr_L, MUSPARSE_FILL_MODE_LOWER);
     musparseSetMatDiagType(descr_L, MUSPARSE_DIAG_TYPE_UNIT);
   
     // Create matrix descriptor for U
     musparseMatDescr_t descr_U;
     musparseCreateMatDescr(&descr_U);
     musparseSetMatFillMode(descr_U, MUSPARSE_FILL_MODE_UPPER);
     musparseSetMatDiagType(descr_U, MUSPARSE_DIAG_TYPE_NON_UNIT);
   
     // Create matrix info structure
     musparseMatInfo_t info;
     musparseCreateMatInfo(&info);
   
     // Obtain required buffer size
     size_t buffer_size_M;
     size_t buffer_size_L;
     size_t buffer_size_U;
     musparseDbsrilu0_bufferSize(handle,
                                    MUSPARSE_DIRECTION_ROW,
                                    mb,
                                    nnzb,
                                    descr_M,
                                    bsr_val,
                                    bsr_row_ptr,
                                    bsr_col_ind,
                                    block_dim,
                                    info,
                                    &buffer_size_M);
     musparseDbsrsv_bufferSize(handle,
                                  MUSPARSE_DIRECTION_ROW,
                                  MUSPARSE_OPERATION_NON_TRANSPOSE,
                                  mb,
                                  nnzb,
                                  descr_L,
                                  bsr_val,
                                  bsr_row_ptr,
                                  bsr_col_ind,
                                  block_dim,
                                  info,
                                  &buffer_size_L);
     musparseDbsrsv_bufferSize(handle,
                                  MUSPARSE_DIRECTION_ROW,
                                  MUSPARSE_OPERATION_TRANSPOSE,
                                  mb,
                                  nnzb,
                                  descr_U,
                                  bsr_val,
                                  bsr_row_ptr,
                                  bsr_col_ind,
                                  block_dim,
                                  info,
                                  &buffer_size_U);
   
     size_t buffer_size = max(buffer_size_M, max(buffer_size_L,
buffer_size_U));

     // Allocate temporary buffer
     void* temp_buffer;
     musaMalloc(&temp_buffer, buffer_size);
   
     // Perform analysis steps, using MUSPARSE_ANALYSIS_POLICY_REUSE to
improve
     // computation performance
     musparseDbsrilu0_analysis(handle,
                                 MUSPARSE_DIRECTION_ROW,
                                 mb,
                                 nnzb,
                                 descr_M,
                                 bsr_val,
                                 bsr_row_ptr,
                                 bsr_col_ind,
                                 block_dim,
                                 info,
                                 MUSPARSE_ANALYSIS_POLICY_REUSE,
                                 MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                                 temp_buffer);
     musparseDbsrsv_analysis(handle,
                               MUSPARSE_DIRECTION_ROW,
                               MUSPARSE_OPERATION_NON_TRANSPOSE,
                               mb,
                               nnzb,
                               descr_L,
                               bsr_val,
                               bsr_row_ptr,
                               bsr_col_ind,
                               block_dim,
                               info,
                               MUSPARSE_ANALYSIS_POLICY_REUSE,
                               MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                               temp_buffer);
     musparseDbsrsv_analysis(handle,
                               MUSPARSE_DIRECTION_ROW,
                               MUSPARSE_OPERATION_TRANSPOSE,
                               mb,
                               nnzb,
                               descr_U,
                               bsr_val,
                               bsr_row_ptr,
                               bsr_col_ind,
                               block_dim,
                               info,
                               MUSPARSE_ANALYSIS_POLICY_REUSE,
                               MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                               temp_buffer);

     // Check for zero pivot
     muInt position;
     if(MUSPARSE_EXPORT MUSPARSE_STATUS_ZERO_PIVOT == musparseXbsrilu0_zeroPivot(handle,
                                                                   info,
&position))
     {
         printf("A has structural zero at A(%d,%d)\n", position, position);
     }

     // Compute incomplete LU factorization M = LU
     musparseDbsrilu0(handle,
                        MUSPARSE_DIRECTION_ROW,
                        mb,
                        nnzb,
                        descr_M,
                        bsr_val,
                        bsr_row_ptr,
                        bsr_col_ind,
                        block_dim,
                        info,
                        MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                        temp_buffer);
   
     // Check for zero pivot
     if(MUSPARSE_EXPORT
MUSPARSE_STATUS_ZERO_PIVOT == musparseXbsrilu0_zeroPivot(handle,
                                                                    info,
&position))
     {
         printf("L has structural and/or numerical zero at L(%d,%d)\n",
                position,
                position);
     }

     // Solve Lz = x
     musparseDbsrsv_solve(handle,
                            MUSPARSE_DIRECTION_ROW,
                            MUSPARSE_OPERATION_NON_TRANSPOSE,
                            mb,
                            nnzb,
                            &alpha,
                            descr_L,
                            bsr_val,
                            bsr_row_ptr,
                            bsr_col_ind,
                            block_dim,
                            info,
                            x,
                            z,
                            MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                            temp_buffer);
   
     // Solve Uy = z
     musparseDbsrsv_solve(handle,
                            MUSPARSE_DIRECTION_ROW,
                            MUSPARSE_OPERATION_TRANSPOSE,
                            mb,
                            nnzb,
                            &alpha,
                            descr_U,
                            bsr_val,
                            bsr_row_ptr,
                            bsr_col_ind,
                            block_dim,
                            info,
                            z,
                            y,
                            MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                            temp_buffer);
   
     // Clean up
     musaFree(temp_buffer);
     musparseDestroyMatInfo(info);
     musparseDestroyMatDescr(descr_M);
     musparseDestroyMatDescr(descr_L);
     musparseDestroyMatDescr(descr_U);
     musparseDestroy(handle);

musparseXbsrilu0 computes the incomplete LU factorization with 0 fill-ins and no pivoting of a sparse $mb \times mb$ BSR matrix $A$ , such that $A \approx LU$

musparseXbsrilu0 requires a user allocated temporary buffer. Its size is returned by musparseSbsrilu0_bufferSize(), musparseDbsrilu0_bufferSize(), musparseCbsrilu0_bufferSize() or musparseZbsrilu0_bufferSize(). Furthermore, analysis meta data is required. It can be obtained by musparseSbsrilu0_analysis(), musparseDbsrilu0_analysis(), musparseCbsrilu0_analysis() or musparseZbsrilu0_analysis(). musparseXbsrilu0 reports the first zero pivot (either numerical or structural zero). The zero pivot status can be obtained by calling [musparseXbsrilu0_zeroPivot()].

musparseStatus_t musparseSbsrilu0(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, float* bsr_val, const muInt* bsr_row_ptr,
    const muInt* bsr_col_ind, muInt block_dim, musparseMatInfo_t info,
    musparseSolvePolicy_t policy, void* temp_buffer);
 
musparseStatus_t musparseDbsrilu0(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, double* bsr_val, const muInt* bsr_row_ptr,
    const muInt* bsr_col_ind, muInt block_dim, musparseMatInfo_t info,
    musparseSolvePolicy_t policy, void* temp_buffer);
 
musparseStatus_t musparseCbsrilu0(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, muComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, musparseSolvePolicy_t policy, void* temp_buffer);
 
musparseStatus_t musparseZbsrilu0(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, muDoubleComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, musparseSolvePolicy_t policy, void* temp_buffer);

function musparseXbsrilu0_zeroPivot

MUSPARSE_EXPORT musparseStatus_t musparseXbsrilu0_zeroPivot(
    musparseHandle_t handle,
    musparseMatInfo_t info,
    muInt * position
)

Incomplete LU factorization with 0 fill-ins and no pivoting using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
info structure that holds the information collected during the analysis step.
position pointer to zero pivot $j$ , can be in host or device memory.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER info or position pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_ZERO_PIVOT zero pivot has been found.

Note:

If a zero pivot is found, position $=j$ means that either the diagonal block $A_{j,j}$ is missing (structural zero) or the diagonal block $A_{j,j}$ is not invertible (numerical zero).
musparseXbsrilu0_zeroPivot is a blocking function. It might influence performance negatively.

musparseXbsrilu0_zeroPivot returns MUSPARSE_EXPORT MUSPARSE_STATUS_ZERO_PIVOT, if either a structural or numerical zero has been found during musparseSbsrilu0(), musparseDbsrilu0(), musparseCbsrilu0() or musparseZbsrilu0() computation. The first zero pivot $j$ at $A_{j,j}$ is stored in position, using same index base as the BSR matrix.

position can be in host or device memory. If no zero pivot has been found, position is set to -1 and MUSPARSE_STATUS_SUCCESS is returned instead.

function musparseCreate

MUSPARSE_EXPORT musparseStatus_t musparseCreate(
    musparseHandle_t * handle
)

Create a musparse handle.

Parameters:

handle the pointer to the handle to the musparse library context.

Returns:

MUSPARSE_STATUS_SUCCESS the initialization succeeded.
MUSPARSE_STATUS_INVALID_HANDLE handle pointer is invalid.
MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.

musparseCreate creates the musparse library context. It must be initialized before any other musparse API function is invoked and must be passed to all subsequent library function calls. The handle should be destroyed at the end using [musparseDestroy()].

function musparseDestroy

MUSPARSE_EXPORT musparseStatus_t musparseDestroy(
    musparseHandle_t handle
)

Destroy a musparse handle.

Parameters:

handle the handle to the musparse library context.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE handle is invalid.
MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.

musparseDestroy destroys the musparse library context and releases all resources used by the musparse library.

function musparseCreateMatDescr

MUSPARSE_EXPORT musparseStatus_t musparseCreateMatDescr(
    musparseMatDescr_t * descr
)

Create a matrix descriptor.

Parameters:

descr the pointer to the matrix descriptor.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_POINTER descr pointer is invalid.

musparseCreateMatDescr creates a matrix descriptor. It initializes musparseMatrixType_t to MUSPARSE_MATRIX_TYPE_GENERAL and musparseIndexBase_t to MUSPARSE_INDEX_BASE_ZERO. It should be destroyed at the end using [musparseDestroyMatDescr()].

function musparseDestroyMatDescr

MUSPARSE_EXPORT musparseStatus_t musparseDestroyMatDescr(
    musparseMatDescr_t descr
)

Destroy a matrix descriptor.

Parameters:

descr the matrix descriptor.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_POINTER descr is invalid.

musparseDestroyMatDescr destroys a matrix descriptor and releases all resources used by the descriptor.

function musparseGetMatDiagType

musparseDiagType_t musparseGetMatDiagType(
    const musparseMatDescr_t descr
)

Get the matrix diagonal type of a matrix descriptor.

Parameters:

descr the matrix descriptor.

Return: MUSPARSE_DIAG_TYPE_UNIT or MUSPARSE_DIAG_TYPE_NON_UNIT.

musparseGetMatDiagType returns the matrix diagonal type of a matrix descriptor.

function musparseGetMatFillMode

musparseFillMode_t musparseGetMatFillMode(
    const musparseMatDescr_t descr
)

Get the matrix fill mode of a matrix descriptor.

Parameters:

descr the matrix descriptor.

Return: MUSPARSE_FILL_MODE_LOWER or MUSPARSE_FILL_MODE_UPPER.

musparseGetMatFillMode returns the matrix fill mode of a matrix descriptor.

function musparseGetMatIndexBase

musparseIndexBase_t musparseGetMatIndexBase(
    const musparseMatDescr_t descr
)

Get the index base of a matrix descriptor.

Parameters:

descr the matrix descriptor.

Return: MUSPARSE_INDEX_BASE_ZERO or MUSPARSE_INDEX_BASE_ONE.

musparseGetMatIndexBase returns the index base of a matrix descriptor.

function musparseGetMatType

musparseMatrixType_t musparseGetMatType(
    const musparseMatDescr_t descr
)

Get the matrix type of a matrix descriptor.

Parameters:

descr the matrix descriptor.

Return: MUSPARSE_MATRIX_TYPE_GENERAL, MUSPARSE_MATRIX_TYPE_SYMMETRIC, MUSPARSE_MATRIX_TYPE_HERMITIAN or MUSPARSE_MATRIX_TYPE_TRIANGULAR.

musparseGetMatType returns the matrix type of a matrix descriptor.

function musparseXbsrmm

MUSPARSE_EXPORT musparseStatus_t musparseXbsrmm()

Sparse matrix dense matrix multiplication using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
dir the storage format of the blocks. Can be MUSPARSE_DIRECTION_ROW or MUSPARSE_DIRECTION_COLUMN.
trans_A matrix $A$ operation type. Currently, only MUSPARSE_OPERATION_NON_TRANSPOSE is supported.
trans_B matrix $B$ operation type. Currently, only MUSPARSE_OPERATION_NON_TRANSPOSE and MUSPARSE_OPERATION_TRANSPOSE are supported.
mb number of block rows of the sparse BSR matrix $A$ .
n number of columns of the dense matrix $op(B)$ and $C$ .
kb number of block columns of the sparse BSR matrix $A$ .
nnzb number of non-zero blocks of the sparse BSR matrix $A$ .
alpha scalar $\alpha$ .
descr descriptor of the sparse BSR matrix $A$ . Currently, only MUSPARSE_MATRIX_TYPE_GENERAL is supported.
bsr_val array of nnzb*block_dim*block_dim elements of the sparse BSR matrix $A$ .
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix $A$ .
bsr_col_ind array of nnzb elements containing the block column indices of the sparse BSR matrix $A$ .
block_dim size of the blocks in the sparse BSR matrix.
B array of dimension $ldb \times n$ ( $op(B) == B$ ), $ldb \times k$ otherwise.
ldb leading dimension of $B$ , must be at least $\max{(1,k)}$ ( $op(B) == B$ ) where $k = block\_dim \times kb$ , $\max{(1,n)}$ otherwise.
beta scalar $\beta$ .
C array of dimension $ldc \times n$ .
ldc leading dimension of $C$ , must be at least $\max{(1,m)}$ ( $op(A) == A$ ) where $m = block\_dim \times mb$ , $\max{(1,k)}$ where $k = block\_dim \times kb$ otherwise.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb, n, kb, nnzb, ldb or ldc is invalid.
MUSPARSE_STATUS_INVALID_POINTER descr, alpha, bsr_val, bsr_row_ptr, bsr_col_ind, B, beta or C pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_ARCH_MISMATCH the the device is not supported.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans_A != MUSPARSE_OPERATION_NON_TRANSPOSE or trans_B == MUSPARSE_OPERATION_CONJUGATE_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

Note:

This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.
Currently, only trans_A == MUSPARSE_OPERATION_NON_TRANSPOSE is supported.

Example:

This example multiplies a BSR matrix with a dense matrix.

     //     1 2 0 3 0 0
     // A = 0 4 5 0 0 0
     //     0 0 0 7 8 0
     //     0 0 1 2 4 1
    
     muInt block_dim = 2;
     muInt mb   = 2;
     muInt kb   = 3;
     muInt nnzb = 4;
     musparseDirection_t dir = MUSPARSE_DIRECTION_ROW;
    
     bsr_row_ptr[mb+1]                 = {0, 2, 4}; // device memory
     bsr_col_ind[nnzb]                 = {0, 1, 1, 2}; // device memory
     bsr_val[nnzb*block_dim*block_dim] = {1, 2, 0, 4, 0, 3, 5, 0, 0, 7, 1, 2,
8, 0, 4, 1}; // device memory

     // Set dimension n of B
     muInt n = 64;
     muInt m = mb * block_dim;
     muInt k = kb * block_dim;
    
     // Allocate and generate dense matrix B
     std::vector<float> hB(k * n);
     for(muInt i = 0; i < k * n; ++i)
     {
         hB[i] = static_cast<float>(rand()) / RAND_MAX;
     }
    
     // Copy B to the device
     float* B;
     musaMalloc((void**)&B, sizeof(float) * k * n);
     musaMemcpy(B, hB.data(), sizeof(float) * k * n, musaMemcpyHostToDevice);
    
     // alpha and beta
     float alpha = 1.0f;
     float beta  = 0.0f;
    
     // Allocate memory for the resulting matrix C
     float* C;
     musaMalloc((void**)&C, sizeof(float) * m * n);
    
     // Perform the matrix multiplication
     musparseSbsrmm(handle,
                      dir,
                      MUSPARSE_OPERATION_NON_TRANSPOSE,
                      MUSPARSE_OPERATION_NON_TRANSPOSE,
                      mb,
                      n,
                      kb,
                      nnzb,
                      &alpha,
                      descr,
                      bsr_val,
                      bsr_row_ptr,
                      bsr_col_ind,
                      block_dim,
                      B,
                      k,
                      &beta,
                      C,
                      m);

musparseXbsrmm multiplies the scalar $\alpha$ with a sparse $mb \times kb$ matrix $A$ , defined in BSR storage format, and the dense $k \times n$ matrix $B$ (where $k = block\_dim \times kb$ ) and adds the result to the dense $m \times n$ matrix $C$ (where $m = block\_dim \times mb$ ) that is multiplied by the scalar $\beta$ , such that $C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C,$ with

op(A) = \begin{cases} A, & \text{if trans\_A == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \end{cases}

and

op(B) = \begin{cases} B, & \text{if trans\_B == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \\ B^T, & \text{if trans\_B == MUSPARSE\_OPERATION\_TRANSPOSE} \end{cases}

 MUSPARSE_EXPORT
musparseStatus_t musparseSbsrmm(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_B, muInt mb, muInt n,
    muInt kb, muInt nnzb, const float* alpha, const musparseMatDescr_t descr,
    const float* bsr_val, const muInt* bsr_row_ptr, const muInt* bsr_col_ind,
    muInt block_dim, const float* B, muInt ldb, const float* beta, float* C,
    muInt ldc);

MUSPARSE_EXPORT
musparseStatus_t musparseDbsrmm(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_B, muInt mb, muInt n,
    muInt kb, muInt nnzb, const double* alpha, const musparseMatDescr_t descr,
    const double* bsr_val, const muInt* bsr_row_ptr, const muInt* bsr_col_ind,
    muInt block_dim, const double* B, muInt ldb, const double* beta, double* C,
    muInt ldc);

MUSPARSE_EXPORT
musparseStatus_t musparseCbsrmm(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_B, muInt mb, muInt n,
    muInt kb, muInt nnzb, const muComplex* alpha,
    const musparseMatDescr_t descr, const muComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    const muComplex* B, muInt ldb, const muComplex* beta, muComplex* C,
    muInt ldc);

MUSPARSE_EXPORT
musparseStatus_t musparseZbsrmm(
    musparseHandle_t handle, musparseDirection_t dir,
    musparseOperation_t trans_A, musparseOperation_t trans_B, muInt mb, muInt n,
    muInt kb, muInt nnzb, const muDoubleComplex* alpha,
    const musparseMatDescr_t descr, const muDoubleComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    const muDoubleComplex* B, muInt ldb, const muDoubleComplex* beta,
    muDoubleComplex* C, muInt ldc);

function musparseXcsric0_bufferSize

MUSPARSE_EXPORT musparseStatus_t musparseXcsric0_bufferSize()

Incomplete Cholesky factorization with 0 fill-ins and no pivoting using CSR storage format.

Parameters:

handle handle to the musparse library context queue.
m number of rows of the sparse CSR matrix.
nnz number of non-zero entries of the sparse CSR matrix.
descr descriptor of the sparse CSR matrix.
csr_val array of nnz elements of the sparse CSR matrix.
csr_row_ptr array of m+1 elements that point to the start of every row of the sparse CSR matrix.
csr_col_ind array of nnz elements containing the column indices of the sparse CSR matrix.
info structure that holds the information collected during the analysis step.
buffer_size number of bytes of the temporary storage buffer required by musparseScsric0_analysis(), musparseDcsric0_analysis(), musparseScsric0() and musparseDcsric0().

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE m or nnz is invalid.
MUSPARSE_STATUS_INVALID_POINTER
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans != MUSPARSE_OPERATION_NON_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

musparseXcsric0_bufferSize returns the size of the temporary storage buffer that is required by musparseScsric0_analysis(), musparseDcsric0_analysis(), musparseScsric0() and musparseDcsric0(). The temporary storage buffer must be allocated by the user. The size of the temporary storage buffer is identical to the size returned by musparseScsrsv_bufferSize(), musparseDcsrsv_bufferSize(), musparseScsrilu0_bufferSize() and musparseDcsrilu0_bufferSize() if the matrix sparsity pattern is identical. The user allocated buffer can thus be shared between subsequent calls to those functions.

MUSPARSE_EXPORT
musparseStatus_t musparseScsric0_bufferSize(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const float* csr_val, const muInt* csr_row_ptr, const muInt* csr_col_ind,
    musparseMatInfo_t info, size_t* buffer_size);

MUSPARSE_EXPORT
musparseStatus_t musparseDcsric0_bufferSize(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const double* csr_val, const muInt* csr_row_ptr, const muInt* csr_col_ind,
    musparseMatInfo_t info, size_t* buffer_size);

MUSPARSE_EXPORT
musparseStatus_t musparseCcsric0_bufferSize(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const muComplex* csr_val, const muInt* csr_row_ptr,
    const muInt* csr_col_ind, musparseMatInfo_t info, size_t* buffer_size);

MUSPARSE_EXPORT
musparseStatus_t musparseZcsric0_bufferSize(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const muDoubleComplex* csr_val, const muInt* csr_row_ptr,
    const muInt* csr_col_ind, musparseMatInfo_t info, size_t* buffer_size);

p descr, csr_val, csr_row_ptr, csr_col_ind, info or buffer_size pointer is invalid.

function musparseXcsric0_analysis

MUSPARSE_EXPORT musparseStatus_t musparseXcsric0_analysis()

Incomplete Cholesky factorization with 0 fill-ins and no pivoting using CSR storage format.

Parameters:

handle handle to the musparse library context queue.
m number of rows of the sparse CSR matrix.
nnz number of non-zero entries of the sparse CSR matrix.
descr descriptor of the sparse CSR matrix.
csr_val array of nnz elements of the sparse CSR matrix.
csr_row_ptr array of m+1 elements that point to the start of every row of the sparse CSR matrix.
csr_col_ind array of nnz elements containing the column indices of the sparse CSR matrix.
info structure that holds the information collected during the analysis step.
analysis MUSPARSE_ANALYSIS_POLICY_REUSE or MUSPARSE_ANALYSIS_POLICY_FORCE.
solve MUSPARSE_SOLVE_POLICY_USE_LEVEL.
temp_buffer temporary storage buffer allocated by the user.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE m or nnz is invalid.
MUSPARSE_STATUS_INVALID_POINTER
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans != MUSPARSE_OPERATION_NON_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

Note:

If the matrix sparsity pattern changes, the gathered information will become invalid.
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

musparseXcsric0_analysis performs the analysis step for musparseScsric0() and musparseDcsric0(). It is expected that this function will be executed only once for a given matrix and particular operation type. The analysis meta data can be cleared by musparseXcsric0_clear().

musparseXcsric0_analysis can share its meta data with musparseScsrilu0_analysis(), musparseDcsrilu0_analysis(), musparseCcsrilu0_analysis(), musparseZcsrilu0_analysis(), musparseScsrsv_analysis(), musparseDcsrsv_analysis(), musparseCcsrsv_analysis(), musparseZcsrsv_analysis(), musparseScsrsm_analysis(), musparseDcsrsm_analysis(), musparseScsrsm_analysis() and musparseDcsrsm_analysis(). Selecting MUSPARSE_ANALYSIS_POLICY_REUSE policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, MUSPARSE_ANALYSIS_POLICY_FORCE has to be used.

 MUSPARSE_EXPORT
musparseStatus_t musparseScsric0_analysis(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const float* csr_val, const muInt* csr_row_ptr, const muInt* csr_col_ind,
    musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseDcsric0_analysis(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const double* csr_val, const muInt* csr_row_ptr, const muInt* csr_col_ind,
    musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseCcsric0_analysis(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const muComplex* csr_val, const muInt* csr_row_ptr,
    const muInt* csr_col_ind, musparseMatInfo_t info,
    musparseAnalysisPolicy_t analysis, musparseSolvePolicy_t solve,
    void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseZcsric0_analysis(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const muDoubleComplex* csr_val, const muInt* csr_row_ptr,
    const muInt* csr_col_ind, musparseMatInfo_t info,
    musparseAnalysisPolicy_t analysis, musparseSolvePolicy_t solve,
    void* temp_buffer);

p descr, csr_val, csr_row_ptr, csr_col_ind, info or temp_buffer pointer is invalid.

function musparseXcsric0

MUSPARSE_EXPORT musparseStatus_t musparseXcsric0()

Incomplete Cholesky factorization with 0 fill-ins and no pivoting using CSR storage format.

Parameters:

handle handle to the musparse library context queue.
m number of rows of the sparse CSR matrix.
nnz number of non-zero entries of the sparse CSR matrix.
descr descriptor of the sparse CSR matrix.
csr_val array of nnz elements of the sparse CSR matrix.
csr_row_ptr array of m+1 elements that point to the start of every row of the sparse CSR matrix.
csr_col_ind array of nnz elements containing the column indices of the sparse CSR matrix.
info structure that holds the information collected during the analysis step.
policy MUSPARSE_SOLVE_POLICY_USE_LEVEL.
temp_buffer temporary storage buffer allocated by the user.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE m or nnz is invalid.
MUSPARSE_STATUS_INVALID_POINTER
MUSPARSE_EXPORT MUSPARSE_STATUS_ARCH_MISMATCH the device is not supported. *
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred. * *
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans != MUSPARSE_OPERATION_NON_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

Note:

The sparse CSR matrix has to be sorted. This can be achieved by calling musparseXcsrsort().
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

 MUSPARSE_EXPORT
musparseStatus_t musparseScsric0(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    float* csr_val, const muInt* csr_row_ptr, const muInt* csr_col_ind,
    musparseMatInfo_t info, musparseSolvePolicy_t policy, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseDcsric0(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    double* csr_val, const muInt* csr_row_ptr, const muInt* csr_col_ind,
    musparseMatInfo_t info, musparseSolvePolicy_t policy, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseCcsric0(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    muComplex* csr_val, const muInt* csr_row_ptr, const muInt* csr_col_ind,
    musparseMatInfo_t info, musparseSolvePolicy_t policy, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseZcsric0(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    muDoubleComplex* csr_val, const muInt* csr_row_ptr,
    const muInt* csr_col_ind, musparseMatInfo_t info,
    musparseSolvePolicy_t policy, void* temp_buffer);

Example:

Consider the sparse $m \times m$ matrix $A$ , stored in CSR storage format. The following example computes the incomplete Cholesky factorization $M \approx LL^T$ and solves the preconditioned system $My = x$ .

     // Create musparse handle
     musparseHandle_t handle;
     musparseCreate(&handle);
   
     // Create matrix descriptor for M
     musparseMatDescr_t descr_M;
     musparseCreateMatDescr(&descr_M);
   
     // Create matrix descriptor for L
     musparseMatDescr_t descr_L;
     musparseCreateMatDescr(&descr_L);
     musparseSetMatFillMode(descr_L, MUSPARSE_FILL_MODE_LOWER);
     musparseSetMatDiagType(descr_L, MUSPARSE_DIAG_TYPE_UNIT);
   
     // Create matrix descriptor for L'
     musparseMatDescr_t descr_Lt;
     musparseCreateMatDescr(&descr_Lt);
     musparseSetMatFillMode(descr_Lt, MUSPARSE_FILL_MODE_UPPER);
     musparseSetMatDiagType(descr_Lt, MUSPARSE_DIAG_TYPE_NON_UNIT);
   
     // Create matrix info structure
     musparseMatInfo_t info;
     musparseCreateMatInfo(&info);
   
     // Obtain required buffer size
     size_t buffer_size_M;
     size_t buffer_size_L;
     size_t buffer_size_Lt;
     musparseDcsric0_bufferSize(handle,
                                   m,
                                   nnz,
                                   descr_M,
                                   csr_val,
                                   csr_row_ptr,
                                   csr_col_ind,
                                   info,
                                   &buffer_size_M);
     musparseDcsrsv_bufferSize(handle,
                                  MUSPARSE_OPERATION_NON_TRANSPOSE,
                                  m,
                                  nnz,
                                  descr_L,
                                  csr_val,
                                  csr_row_ptr,
                                  csr_col_ind,
                                  info,
                                  &buffer_size_L);
     musparseDcsrsv_bufferSize(handle,
                                  MUSPARSE_OPERATION_TRANSPOSE,
                                  m,
                                  nnz,
                                  descr_Lt,
                                  csr_val,
                                  csr_row_ptr,
                                  csr_col_ind,
                                  info,
                                  &buffer_size_Lt);
   
     size_t buffer_size = max(buffer_size_M, max(buffer_size_L,
buffer_size_Lt));

     // Allocate temporary buffer
     void* temp_buffer;
     musaMalloc(&temp_buffer, buffer_size);
   
     // Perform analysis steps, using MUSPARSE_ANALYSIS_POLICY_REUSE to
improve
     // computation performance
     musparseDcsric0_analysis(handle,
                                m,
                                nnz,
                                descr_M,
                                csr_val,
                                csr_row_ptr,
                                csr_col_ind,
                                info,
                                MUSPARSE_ANALYSIS_POLICY_REUSE,
                                MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                                temp_buffer);
     musparseDcsrsv_analysis(handle,
                               MUSPARSE_OPERATION_NON_TRANSPOSE,
                               m,
                               nnz,
                               descr_L,
                               csr_val,
                               csr_row_ptr,
                               csr_col_ind,
                               info,
                               MUSPARSE_ANALYSIS_POLICY_REUSE,
                               MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                               temp_buffer);
     musparseDcsrsv_analysis(handle,
                               MUSPARSE_OPERATION_TRANSPOSE,
                               m,
                               nnz,
                               descr_Lt,
                               csr_val,
                               csr_row_ptr,
                               csr_col_ind,
                               info,
                               MUSPARSE_ANALYSIS_POLICY_REUSE,
                               MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                               temp_buffer);

     // Check for zero pivot
     muInt position;
     if(MUSPARSE_EXPORT
MUSPARSE_STATUS_ZERO_PIVOT == musparseXcsric0_zeroPivot(handle,
                                                                   info,
&position))
     {
         printf("A has structural zero at A(%d,%d)\n", position, position);
     }

     // Compute incomplete Cholesky factorization M = LL'
     musparseDcsric0(handle,
                       m,
                       nnz,
                       descr_M,
                       csr_val,
                       csr_row_ptr,
                       csr_col_ind,
                       info,
                       MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                       temp_buffer);
   
     // Check for zero pivot
     if(MUSPARSE_EXPORT
MUSPARSE_STATUS_ZERO_PIVOT == musparseXcsric0_zeroPivot(handle,
                                                                   info,
&position))
     {
         printf("L has structural and/or numerical zero at L(%d,%d)\n",
                position,
                position);
     }

     // Solve Lz = x
     musparseDcsrsv_solve(handle,
                            MUSPARSE_OPERATION_NON_TRANSPOSE,
                            m,
                            nnz,
                            &alpha,
                            descr_L,
                            csr_val,
                            csr_row_ptr,
                            csr_col_ind,
                            info,
                            x,
                            z,
                            MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                            temp_buffer);
   
     // Solve L'y = z
     musparseDcsrsv_solve(handle,
                            MUSPARSE_OPERATION_TRANSPOSE,
                            m,
                            nnz,
                            &alpha,
                            descr_Lt,
                            csr_val,
                            csr_row_ptr,
                            csr_col_ind,
                            info,
                            z,
                            y,
                            MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                            temp_buffer);
   
     // Clean up
     musaFree(temp_buffer);
     musparseDestroyMatInfo(info);
     musparseDestroyMatDescr(descr_M);
     musparseDestroyMatDescr(descr_L);
     musparseDestroyMatDescr(descr_Lt);
     musparseDestroy(handle);

musparseXcsric0 computes the incomplete Cholesky factorization with 0 fill-ins and no pivoting of a sparse $m \times m$ CSR matrix $A$ , such that $A \approx LL^T$

musparseXcsric0 requires a user allocated temporary buffer. Its size is returned by musparseScsric0_bufferSize() or musparseDcsric0_bufferSize(). Furthermore, analysis meta data is required. It can be obtained by musparseScsric0_analysis() or musparseDcsric0_analysis(). musparseXcsric0 reports the first zero pivot (either numerical or structural zero). The zero pivot status can be obtained by calling [musparseXcsric0_zeroPivot()].

p descr, csr_val, csr_row_ptr or csr_col_ind pointer is invalid. *

function musparseXcsric0_zeroPivot

MUSPARSE_EXPORT musparseStatus_t musparseXcsric0_zeroPivot(
    musparseHandle_t handle,
    musparseMatInfo_t info,
    muInt * position
)

Incomplete Cholesky factorization with 0 fill-ins and no pivoting using CSR storage format.

Parameters:

handle handle to the musparse library context queue.
info structure that holds the information collected during the analysis step.
position pointer to zero pivot $j$ , can be in host or device memory.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER info or position pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_ZERO_PIVOT zero pivot has been found.

Note: musparseXcsric0_zeroPivot is a blocking function. It might influence performance negatively.

musparse_csric_zero_pivot returns MUSPARSE_EXPORT MUSPARSE_STATUS_ZERO_PIVOT, if either a structural or numerical zero has been found during musparseScsric0() or musparseDcsric0() computation. The first zero pivot $j$ at $A_{j,j}$ is stored in position, using same index base as the CSR matrix.

position can be in host or device memory. If no zero pivot has been found, position is set to -1 and MUSPARSE_STATUS_SUCCESS is returned instead.

function musparseXbsric0_bufferSize

MUSPARSE_EXPORT musparseStatus_t musparseXbsric0_bufferSize()

Incomplete Cholesky factorization with 0 fill-ins and no pivoting using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
dir direction that specifies whether to count nonzero elements by MUSPARSE_DIRECTION_ROW or by MUSPARSE_DIRECTION_ROW.
mb number of block rows in the sparse BSR matrix.
nnzb number of non-zero block entries of the sparse BSR matrix.
descr descriptor of the sparse BSR matrix.
bsr_val array of length nnzb*block_dim*block_dim containing the values of the sparse BSR matrix.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix.
bsr_col_ind array of nnzb elements containing the block column indices of the sparse BSR matrix.
block_dim the block dimension of the BSR matrix. Between 1 and m where m=mb*block_dim.
info structure that holds the information collected during the analysis step.
buffer_size number of bytes of the temporary storage buffer required by musparseSbsric0_analysis(), musparseDbsric0_analysis(), musparseCbsric0_analysis(), musparseZbsric0_analysis(), musparseSbsric0(), musparseDbsric0(), musparseCbsric0() and musparseZbsric0().

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb, nnzb, or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER descr, bsr_val, bsr_row_ptr, bsr_col_ind, info or buffer_size pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

musparseXbsric0_bufferSize returns the size of the temporary storage buffer that is required by musparseSbsric0_analysis(), musparseDbsric0_analysis(), musparseCbsric0_analysis(), musparseZbsric0_analysis(), musparseSbsric0(), musparseDbsric0(), musparseSbsric0() and musparseDbsric0(). The temporary storage buffer must be allocated by the user. The size of the temporary storage buffer is identical to the size returned by musparseSbsrsv_bufferSize(), musparseDbsrsv_bufferSize(), musparseCbsrsv_bufferSize(), musparseZbsrsv_bufferSize(), musparseSbsrilu0_bufferSize(), musparseDbsrilu0_bufferSize(), musparseCbsrilu0_bufferSize() and musparseZbsrilu0_bufferSize() if the matrix sparsity pattern is identical. The user allocated buffer can thus be shared between subsequent calls to those functions.

 MUSPARSE_EXPORT
musparseStatus_t musparseSbsric0_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const float* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, size_t* buffer_size);

MUSPARSE_EXPORT
musparseStatus_t musparseDbsric0_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const double* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, size_t* buffer_size);

MUSPARSE_EXPORT
musparseStatus_t musparseCbsric0_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const muComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, size_t* buffer_size);

MUSPARSE_EXPORT
musparseStatus_t musparseZbsric0_bufferSize(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const muDoubleComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, size_t* buffer_size);

function musparseXbsric0_analysis

MUSPARSE_EXPORT musparseStatus_t musparseXbsric0_analysis()

Incomplete Cholesky factorization with 0 fill-ins and no pivoting using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
dir direction that specified whether to count nonzero elements by MUSPARSE_DIRECTION_ROW or by MUSPARSE_DIRECTION_ROW.
mb number of block rows in the sparse BSR matrix.
nnzb number of non-zero block entries of the sparse BSR matrix.
descr descriptor of the sparse BSR matrix.
bsr_val array of length nnzb*block_dim*block_dim containing the values of the sparse BSR matrix.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix.
bsr_col_ind array of nnzb elements containing the block column indices of the sparse BSR matrix.
block_dim the block dimension of the BSR matrix. Between 1 and m where m=mb*block_dim.
info structure that holds the information collected during the analysis step.
analysis MUSPARSE_ANALYSIS_POLICY_REUSE or MUSPARSE_ANALYSIS_POLICY_FORCE.
solve MUSPARSE_SOLVE_POLICY_USE_LEVEL.
temp_buffer temporary storage buffer allocated by the user.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb, nnzb, or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER descr, bsr_val, bsr_row_ptr, bsr_col_ind, info or temp_buffer pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

Note:

If the matrix sparsity pattern changes, the gathered information will become invalid.
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

musparseXbsric0_analysis performs the analysis step for musparseSbsric0() musparseDbsric0(), musparseCbsric0(), and musparseZbsric0(). It is expected that this function will be executed only once for a given matrix and particular operation type. The analysis meta data can be cleared by musparseXbsric0_clear().

musparseXbsric0_analysis can share its meta data with musparseSbsrilu0_analysis(), musparseDbsrilu0_analysis(), musparseCbsrilu0_analysis(), musparseZbsrilu0_analysis(), musparseSbsrsv_analysis(), musparseDbsrsv_analysis(), musparseCbsrsv_analysis(), musparseZbsrsv_analysis(), musparseSbsrsm_analysis(), musparseDbsrsm_analysis(), musparseCbsrsm_analysis() and musparseZbsrsm_analysis(). Selecting MUSPARSE_ANALYSIS_POLICY_REUSE policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, MUSPARSE_ANALYSIS_POLICY_FORCE has to be used.

 MUSPARSE_EXPORT
musparseStatus_t musparseSbsric0_analysis(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const float* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseDbsric0_analysis(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const double* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseCbsric0_analysis(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const muComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseZbsric0_analysis(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, const muDoubleComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);

function musparseXbsric0

MUSPARSE_EXPORT musparseStatus_t musparseXbsric0()

Incomplete Cholesky factorization with 0 fill-ins and no pivoting using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
dir direction that specified whether to count nonzero elements by MUSPARSE_DIRECTION_ROW or by MUSPARSE_DIRECTION_ROW.
mb number of block rows in the sparse BSR matrix.
nnzb number of non-zero block entries of the sparse BSR matrix.
descr descriptor of the sparse BSR matrix.
bsr_val array of length nnzb*block_dim*block_dim containing the values of the sparse BSR matrix.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix.
bsr_col_ind array of nnzb elements containing the block column indices of the sparse BSR matrix.
block_dim the block dimension of the BSR matrix. Between 1 and m where m=mb*block_dim.
info structure that holds the information collected during the analysis step.
policy MUSPARSE_SOLVE_POLICY_USE_LEVEL.
temp_buffer temporary storage buffer allocated by the user.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb, nnzb, or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER descr, bsr_val, bsr_row_ptr or bsr_col_ind pointer is invalid. *
MUSPARSE_EXPORT MUSPARSE_STATUS_ARCH_MISMATCH the device is not supported. *
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred. * *
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

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

Example:

Consider the sparse $m \times m$ matrix $A$ , stored in BSR storage format. The following example computes the incomplete Cholesky factorization $M \approx LL^T$ and solves the preconditioned system $My = x$ .

     // Create musparse handle
     musparseHandle_t handle;
     musparseCreate(&handle);
   
     // Create matrix descriptor for M
     musparseMatDescr_t descr_M;
     musparseCreateMatDescr(&descr_M);
   
     // Create matrix descriptor for L
     musparseMatDescr_t descr_L;
     musparseCreateMatDescr(&descr_L);
     musparseSetMatFillMode(descr_L, MUSPARSE_FILL_MODE_LOWER);
     musparseSetMatDiagType(descr_L, MUSPARSE_DIAG_TYPE_UNIT);
   
     // Create matrix descriptor for L'
     musparseMatDescr_t descr_Lt;
     musparseCreateMatDescr(&descr_Lt);
     musparseSetMatFillMode(descr_Lt, MUSPARSE_FILL_MODE_UPPER);
     musparseSetMatDiagType(descr_Lt, MUSPARSE_DIAG_TYPE_NON_UNIT);
   
     // Create matrix info structure
     musparseMatInfo_t info;
     musparseCreateMatInfo(&info);
   
     // Obtain required buffer size
     size_t buffer_size_M;
     size_t buffer_size_L;
     size_t buffer_size_Lt;
     musparseDbsric0_bufferSize(handle,
                                    MUSPARSE_DIRECTION_ROW,
                                    mb,
                                    nnzb,
                                    descr_M,
                                    bsr_val,
                                    bsr_row_ptr,
                                    bsr_col_ind,
                                    block_dim,
                                    info,
                                    &buffer_size_M);
     musparseDbsrsv_bufferSize(handle,
                                  MUSPARSE_DIRECTION_ROW,
                                  MUSPARSE_OPERATION_NON_TRANSPOSE,
                                  mb,
                                  nnzb,
                                  descr_L,
                                  bsr_val,
                                  bsr_row_ptr,
                                  bsr_col_ind,
                                  block_dim,
                                  info,
                                  &buffer_size_L);
     musparseDbsrsv_bufferSize(handle,
                                  MUSPARSE_DIRECTION_ROW,
                                  MUSPARSE_OPERATION_TRANSPOSE,
                                  mb,
                                  nnzb,
                                  descr_Lt,
                                  bsr_val,
                                  bsr_row_ptr,
                                  bsr_col_ind,
                                  block_dim,
                                  info,
                                  &buffer_size_Lt);
   
     size_t buffer_size = max(buffer_size_M, max(buffer_size_L,
buffer_size_Lt));

     // Allocate temporary buffer
     void* temp_buffer;
     musaMalloc(&temp_buffer, buffer_size);
   
     // Perform analysis steps, using MUSPARSE_ANALYSIS_POLICY_REUSE to
improve
     // computation performance
     musparseDbsric0_analysis(handle,
                                 MUSPARSE_DIRECTION_ROW,
                                 mb,
                                 nnzb,
                                 descr_M,
                                 bsr_val,
                                 bsr_row_ptr,
                                 bsr_col_ind,
                                 block_dim,
                                 info,
                                 MUSPARSE_ANALYSIS_POLICY_REUSE,
                                 MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                                 temp_buffer);
     musparseDbsrsv_analysis(handle,
                               MUSPARSE_DIRECTION_ROW,
                               MUSPARSE_OPERATION_NON_TRANSPOSE,
                               mb,
                               nnzb,
                               descr_L,
                               bsr_val,
                               bsr_row_ptr,
                               bsr_col_ind,
                               block_dim,
                               info,
                               MUSPARSE_ANALYSIS_POLICY_REUSE,
                               MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                               temp_buffer);
     musparseDbsrsv_analysis(handle,
                               MUSPARSE_DIRECTION_ROW,
                               MUSPARSE_OPERATION_TRANSPOSE,
                               mb,
                               nnzb,
                               descr_Lt,
                               bsr_val,
                               bsr_row_ptr,
                               bsr_col_ind,
                               block_dim,
                               info,
                               MUSPARSE_ANALYSIS_POLICY_REUSE,
                               MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                               temp_buffer);

     // Check for zero pivot
     muInt position;
     if(MUSPARSE_EXPORT
MUSPARSE_STATUS_ZERO_PIVOT == musparseXbsric0_zeroPivot(handle,
                                                                   info,
&position))
     {
         printf("A has structural zero at A(%d,%d)\n", position, position);
     }

     // Compute incomplete Cholesky factorization M = LL'
     musparseDbsric0(handle,
                        MUSPARSE_DIRECTION_ROW,
                        mb,
                        nnzb,
                        descr_M,
                        bsr_val,
                        bsr_row_ptr,
                        bsr_col_ind,
                        block_dim,
                        info,
                        MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                        temp_buffer);
   
     // Check for zero pivot
     if(MUSPARSE_EXPORT
MUSPARSE_STATUS_ZERO_PIVOT == musparseXbsric0_zeroPivot(handle,
                                                                    info,
&position))
     {
         printf("L has structural and/or numerical zero at L(%d,%d)\n",
                position,
                position);
     }

     // Solve Lz = x
     musparseDbsrsv_solve(handle,
                            MUSPARSE_DIRECTION_ROW,
                            MUSPARSE_OPERATION_NON_TRANSPOSE,
                            mb,
                            nnzb,
                            &alpha,
                            descr_L,
                            bsr_val,
                            bsr_row_ptr,
                            bsr_col_ind,
                            block_dim,
                            info,
                            x,
                            z,
                            MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                            temp_buffer);
   
     // Solve L'y = z
     musparseDbsrsv_solve(handle,
                            MUSPARSE_DIRECTION_ROW,
                            MUSPARSE_OPERATION_TRANSPOSE,
                            mb,
                            nnzb,
                            &alpha,
                            descr_Lt,
                            bsr_val,
                            bsr_row_ptr,
                            bsr_col_ind,
                            block_dim,
                            info,
                            z,
                            y,
                            MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                            temp_buffer);
   
     // Clean up
     musaFree(temp_buffer);
     musparseDestroyMatInfo(info);
     musparseDestroyMatDescr(descr_M);
     musparseDestroyMatDescr(descr_L);
     musparseDestroyMatDescr(descr_Lt);
     musparseDestroy(handle);

musparseXbsric0 computes the incomplete Cholesky factorization with 0 fill-ins and no pivoting of a sparse $mb \times mb$ BSR matrix $A$ , such that $A \approx LL^T$

musparseXbsric0 requires a user allocated temporary buffer. Its size is returned by musparseSbsric0_bufferSize(), musparseDbsric0_bufferSize(), musparseCbsric0_bufferSize() or musparseZbsric0_bufferSize(). Furthermore, analysis meta data is required. It can be obtained by musparseSbsric0_analysis(), musparseDbsric0_analysis(), musparseCbsric0_analysis() or musparseZbsric0_analysis(). musparseXbsric0 reports the first zero pivot (either numerical or structural zero). The zero pivot status can be obtained by calling [musparseXbsric0_zeroPivot()].

MUSPARSE_EXPORT
musparseStatus_t musparseSbsric0(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, float* bsr_val, const muInt* bsr_row_ptr,
    const muInt* bsr_col_ind, muInt block_dim, musparseMatInfo_t info,
    musparseSolvePolicy_t policy, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseDbsric0(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, double* bsr_val, const muInt* bsr_row_ptr,
    const muInt* bsr_col_ind, muInt block_dim, musparseMatInfo_t info,
    musparseSolvePolicy_t policy, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseCbsric0(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, muComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, musparseSolvePolicy_t policy, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseZbsric0(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nnzb,
    const musparseMatDescr_t descr, muDoubleComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    musparseMatInfo_t info, musparseSolvePolicy_t policy, void* temp_buffer);

function musparseXbsric0_zeroPivot

MUSPARSE_EXPORT musparseStatus_t musparseXbsric0_zeroPivot(
    musparseHandle_t handle,
    musparseMatInfo_t info,
    muInt * position
)

Incomplete Cholesky factorization with 0 fill-ins and no pivoting using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
info structure that holds the information collected during the analysis step.
position pointer to zero pivot $j$ , can be in host or device memory.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER info or position pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_ZERO_PIVOT zero pivot has been found.

Note:

If a zero pivot is found, position=j means that either the diagonal block A(j,j) is missing (structural zero) or the diagonal block A(j,j) is not positive definite (numerical zero).
musparseXbsric0_zeroPivot is a blocking function. It might influence performance negatively.

musparseXbsric0_zeroPivot returns MUSPARSE_EXPORT MUSPARSE_STATUS_ZERO_PIVOT, if either a structural or numerical zero has been found during musparseSbsric0(), musparseDbsric0(), musparseCbsric0() or musparseZbsric0() computation. The first zero pivot $j$ at $A_{j,j}$ is stored in position, using same index base as the BSR matrix.

position can be in host or device memory. If no zero pivot has been found, position is set to -1 and MUSPARSE_STATUS_SUCCESS is returned instead.

function musparseXcsrilu0_numericBoost

MUSPARSE_EXPORT musparseStatus_t musparseXcsrilu0_numericBoost()

Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

Parameters:

handle handle to the musparse library context queue.
info structure that holds the information collected during the analysis step.
enable_boost enable/disable numeric boost.
boost_tol tolerance to determine whether a numerical value is replaced or not.
boost_val boost value to replace a numerical value.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER info, tol or boost_val pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.

Note:

The boost value is enabled by setting enable_boost to 1 or disabled by setting enable_boost to 0.
tol and boost_val can be in host or device memory.

MUSPARSE_EXPORT
musparseStatus_t musparseScsrilu0_numericBoost(musparseHandle_t handle,
                                               musparseMatInfo_t info,
                                               int enable_boost,
                                               const float* boost_tol,
                                               const float* boost_val);

MUSPARSE_EXPORT
musparseStatus_t musparseDcsrilu0_numericBoost(musparseHandle_t handle,
                                               musparseMatInfo_t info,
                                               int enable_boost,
                                               const double* boost_tol,
                                               const double* boost_val);

MUSPARSE_EXPORT
musparseStatus_t musparseCcsrilu0_numericBoost(musparseHandle_t handle,
                                               musparseMatInfo_t info,
                                               int enable_boost,
                                               const float* boost_tol,
                                               const muComplex* boost_val);

MUSPARSE_EXPORT
musparseStatus_t musparseZcsrilu0_numericBoost(
    musparseHandle_t handle, musparseMatInfo_t info, int enable_boost,
    const double* boost_tol, const muDoubleComplex* boost_val);

MUSPARSE_EXPORT
musparseStatus_t musparseDScsrilu0_numericBoost(musparseHandle_t handle,
                                                musparseMatInfo_t info,
                                                int enable_boost,
                                                const double* boost_tol,
                                                const float* boost_val);

MUSPARSE_EXPORT
musparseStatus_t musparseDCcsrilu0_numericBoost(musparseHandle_t handle,
                                                musparseMatInfo_t info,
                                                int enable_boost,
                                                const double* boost_tol,
                                                const muComplex* boost_val);

musparseXcsrilu0_numericBoost enables the user to replace a numerical value in an incomplete LU factorization. tol is used to determine whether a numerical value is replaced by boost_val, such that $A_{j,j} = \text{boost\_val}$ if $\, \text{tol} \ge \left| A_{j,j} \right|$ .

function musparseXcsrilu0_bufferSize

MUSPARSE_EXPORT musparseStatus_t musparseXcsrilu0_bufferSize()

Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

Parameters:

handle handle to the musparse library context queue.
m number of rows of the sparse CSR matrix.
nnz number of non-zero entries of the sparse CSR matrix.
descr descriptor of the sparse CSR matrix.
csr_val array of nnz elements of the sparse CSR matrix.
csr_row_ptr array of m+1 elements that point to the start of every row of the sparse CSR matrix.
csr_col_ind array of nnz elements containing the column indices of the sparse CSR matrix.
info structure that holds the information collected during the analysis step.
buffer_size number of bytes of the temporary storage buffer required by musparseScsrilu0_analysis(), musparseDcsrilu0_analysis(), musparseCcsrilu0_analysis(), musparseZcsrilu0_analysis(), musparseScsrilu0(), musparseDcsrilu0(), musparseCcsrilu0() and musparseZcsrilu0().

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE m or nnz is invalid.
MUSPARSE_STATUS_INVALID_POINTER
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans != MUSPARSE_OPERATION_NON_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

musparseXcsrilu0_bufferSize returns the size of the temporary storage buffer that is required by musparseScsrilu0_analysis(), musparseDcsrilu0_analysis(), musparseCcsrilu0_analysis(), musparseZcsrilu0_analysis(), musparseScsrilu0(), musparseDcsrilu0(), musparseCcsrilu0() and musparseZcsrilu0(). The temporary storage buffer must be allocated by the user. The size of the temporary storage buffer is identical to the size returned by musparseScsrsv_bufferSize(), musparseDcsrsv_bufferSize(), musparseCcsrsv_bufferSize() and musparseZcsrsv_bufferSize() if the matrix sparsity pattern is identical. The user allocated buffer can thus be shared between subsequent calls to those functions.

MUSPARSE_EXPORT
musparseStatus_t musparseScsrilu0_bufferSize(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const float* csr_val, const muInt* csr_row_ptr, const muInt* csr_col_ind,
    musparseMatInfo_t info, size_t* buffer_size);

MUSPARSE_EXPORT
musparseStatus_t musparseDcsrilu0_bufferSize(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const double* csr_val, const muInt* csr_row_ptr, const muInt* csr_col_ind,
    musparseMatInfo_t info, size_t* buffer_size);

MUSPARSE_EXPORT
musparseStatus_t musparseCcsrilu0_bufferSize(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const muComplex* csr_val, const muInt* csr_row_ptr,
    const muInt* csr_col_ind, musparseMatInfo_t info, size_t* buffer_size);

MUSPARSE_EXPORT
musparseStatus_t musparseZcsrilu0_bufferSize(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const muDoubleComplex* csr_val, const muInt* csr_row_ptr,
    const muInt* csr_col_ind, musparseMatInfo_t info, size_t* buffer_size);

p descr, csr_val, csr_row_ptr, csr_col_ind, info or buffer_size pointer is invalid.

function musparseXcsrilu0_analysis

MUSPARSE_EXPORT musparseStatus_t musparseXcsrilu0_analysis()

Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

Parameters:

handle handle to the musparse library context queue.
m number of rows of the sparse CSR matrix.
nnz number of non-zero entries of the sparse CSR matrix.
descr descriptor of the sparse CSR matrix.
csr_val array of nnz elements of the sparse CSR matrix.
csr_row_ptr array of m+1 elements that point to the start of every row of the sparse CSR matrix.
csr_col_ind array of nnz elements containing the column indices of the sparse CSR matrix.
info structure that holds the information collected during the analysis step.
analysis MUSPARSE_ANALYSIS_POLICY_REUSE or MUSPARSE_ANALYSIS_POLICY_FORCE.
solve MUSPARSE_SOLVE_POLICY_USE_LEVEL.
temp_buffer temporary storage buffer allocated by the user.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE m or nnz is invalid.
MUSPARSE_STATUS_INVALID_POINTER
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans != MUSPARSE_OPERATION_NON_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

Note:

If the matrix sparsity pattern changes, the gathered information will become invalid.
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

MUSPARSE_EXPORT
musparseStatus_t musparseScsrilu0_analysis(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const float* csr_val, const muInt* csr_row_ptr, const muInt* csr_col_ind,
    musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseDcsrilu0_analysis(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const double* csr_val, const muInt* csr_row_ptr, const muInt* csr_col_ind,
    musparseMatInfo_t info, musparseAnalysisPolicy_t analysis,
    musparseSolvePolicy_t solve, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseCcsrilu0_analysis(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const muComplex* csr_val, const muInt* csr_row_ptr,
    const muInt* csr_col_ind, musparseMatInfo_t info,
    musparseAnalysisPolicy_t analysis, musparseSolvePolicy_t solve,
    void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseZcsrilu0_analysis(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    const muDoubleComplex* csr_val, const muInt* csr_row_ptr,
    const muInt* csr_col_ind, musparseMatInfo_t info,
    musparseAnalysisPolicy_t analysis, musparseSolvePolicy_t solve,
    void* temp_buffer);

musparseXcsrilu0_analysis performs the analysis step for musparseScsrilu0(), musparseDcsrilu0(), musparseCcsrilu0() and musparseZcsrilu0(). It is expected that this function will be executed only once for a given matrix and particular operation type. The analysis meta data can be cleared by musparseXcsrilu0_clear().

musparseXcsrilu0_analysis can share its meta data with musparseScsric0_analysis(), musparseDcsric0_analysis(), musparseCcsric0_analysis(), musparseZcsric0_analysis(), musparseScsrsv_analysis(), musparseDcsrsv_analysis(), musparseCcsrsv_analysis(), musparseZcsrsv_analysis(), musparseScsrsm_analysis(), musparseDcsrsm_analysis(), musparseScsrsm_analysis() and musparseDcsrsm_analysis(). Selecting MUSPARSE_ANALYSIS_POLICY_REUSE policy can greatly improve computation performance of meta data. However, the user need to make sure that the sparsity pattern remains unchanged. If this cannot be assured, MUSPARSE_ANALYSIS_POLICY_FORCE has to be used.

p descr, csr_val, csr_row_ptr, csr_col_ind, info or temp_buffer pointer is invalid.

function musparseXcsrilu0

MUSPARSE_EXPORT musparseStatus_t musparseXcsrilu0()

Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

Parameters:

handle handle to the musparse library context queue.
m number of rows of the sparse CSR matrix.
nnz number of non-zero entries of the sparse CSR matrix.
descr descriptor of the sparse CSR matrix.
csr_val array of nnz elements of the sparse CSR matrix.
csr_row_ptr array of m+1 elements that point to the start of every row of the sparse CSR matrix.
csr_col_ind array of nnz elements containing the column indices of the sparse CSR matrix.
info structure that holds the information collected during the analysis step.
policy MUSPARSE_SOLVE_POLICY_USE_LEVEL.
temp_buffer temporary storage buffer allocated by the user.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE m or nnz is invalid.
MUSPARSE_STATUS_INVALID_POINTER
MUSPARSE_EXPORT MUSPARSE_STATUS_ARCH_MISMATCH the device is not supported. *
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred. * *
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans != MUSPARSE_OPERATION_NON_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

Note:

The sparse CSR matrix has to be sorted. This can be achieved by calling musparseXcsrsort().
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

MUSPARSE_EXPORT
musparseStatus_t musparseScsrilu0(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    float* csr_val, const muInt* csr_row_ptr, const muInt* csr_col_ind,
    musparseMatInfo_t info, musparseSolvePolicy_t policy, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseDcsrilu0(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    double* csr_val, const muInt* csr_row_ptr, const muInt* csr_col_ind,
    musparseMatInfo_t info, musparseSolvePolicy_t policy, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseCcsrilu0(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    muComplex* csr_val, const muInt* csr_row_ptr, const muInt* csr_col_ind,
    musparseMatInfo_t info, musparseSolvePolicy_t policy, void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseZcsrilu0(
    musparseHandle_t handle, muInt m, muInt nnz, const musparseMatDescr_t descr,
    muDoubleComplex* csr_val, const muInt* csr_row_ptr,
    const muInt* csr_col_ind, musparseMatInfo_t info,
    musparseSolvePolicy_t policy, void* temp_buffer);

Example:

Consider the sparse $m \times m$ matrix $A$ , stored in CSR storage format. The following example computes the incomplete LU factorization $M \approx LU$ and solves the preconditioned system $My =x$ .

     // Create musparse handle
     musparseHandle_t handle;
     musparseCreate(&handle);
   
     // Create matrix descriptor for M
     musparseMatDescr_t descr_M;
     musparseCreateMatDescr(&descr_M);
   
     // Create matrix descriptor for L
     musparseMatDescr_t descr_L;
     musparseCreateMatDescr(&descr_L);
     musparseSetMatFillMode(descr_L, MUSPARSE_FILL_MODE_LOWER);
     musparseSetMatDiagType(descr_L, MUSPARSE_DIAG_TYPE_UNIT);
   
     // Create matrix descriptor for U
     musparseMatDescr_t descr_U;
     musparseCreateMatDescr(&descr_U);
     musparseSetMatFillMode(descr_U, MUSPARSE_FILL_MODE_UPPER);
     musparseSetMatDiagType(descr_U, MUSPARSE_DIAG_TYPE_NON_UNIT);
   
     // Create matrix info structure
     musparseMatInfo_t info;
     musparseCreateMatInfo(&info);
   
     // Obtain required buffer size
     size_t buffer_size_M;
     size_t buffer_size_L;
     size_t buffer_size_U;
     musparseDcsrilu0_bufferSize(handle,
                                   m,
                                   nnz,
                                   descr_M,
                                   csr_val,
                                   csr_row_ptr,
                                   csr_col_ind,
                                   info,
                                   &buffer_size_M);
     musparseDcsrsv_bufferSize(handle,
                                  MUSPARSE_OPERATION_NON_TRANSPOSE,
                                  m,
                                  nnz,
                                  descr_L,
                                  csr_val,
                                  csr_row_ptr,
                                  csr_col_ind,
                                  info,
                                  &buffer_size_L);
     musparseDcsrsv_bufferSize(handle,
                                  MUSPARSE_OPERATION_NON_TRANSPOSE,
                                  m,
                                  nnz,
                                  descr_U,
                                  csr_val,
                                  csr_row_ptr,
                                  csr_col_ind,
                                  info,
                                  &buffer_size_U);
   
     size_t buffer_size = max(buffer_size_M, max(buffer_size_L,
buffer_size_U));

     // Allocate temporary buffer
     void* temp_buffer;
     musaMalloc(&temp_buffer, buffer_size);
   
     // Perform analysis steps, using MUSPARSE_ANALYSIS_POLICY_REUSE to
improve
     // computation performance
     musparseDcsrilu0_analysis(handle,
                                 m,
                                 nnz,
                                 descr_M,
                                 csr_val,
                                 csr_row_ptr,
                                 csr_col_ind,
                                 info,
                                 MUSPARSE_ANALYSIS_POLICY_REUSE,
                                 MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                                 temp_buffer);
     musparseDcsrsv_analysis(handle,
                               MUSPARSE_OPERATION_NON_TRANSPOSE,
                               m,
                               nnz,
                               descr_L,
                               csr_val,
                               csr_row_ptr,
                               csr_col_ind,
                               info,
                               MUSPARSE_ANALYSIS_POLICY_REUSE,
                               MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                               temp_buffer);
     musparseDcsrsv_analysis(handle,
                               MUSPARSE_OPERATION_NON_TRANSPOSE,
                               m,
                               nnz,
                               descr_U,
                               csr_val,
                               csr_row_ptr,
                               csr_col_ind,
                               info,
                               MUSPARSE_ANALYSIS_POLICY_REUSE,
                               MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                               temp_buffer);

     // Check for zero pivot
     muInt position;
     if(MUSPARSE_EXPORT
MUSPARSE_STATUS_ZERO_PIVOT == musparseXcsrilu0_zeroPivot(handle,
                                                                    info,
&position))
     {
         printf("A has structural zero at A(%d,%d)\n", position, position);
     }

     // Compute incomplete LU factorization
     musparseDcsrilu0(handle,
                        m,
                        nnz,
                        descr_M,
                        csr_val,
                        csr_row_ptr,
                        csr_col_ind,
                        info,
                        MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                        temp_buffer);
   
     // Check for zero pivot
     if(MUSPARSE_EXPORT
MUSPARSE_STATUS_ZERO_PIVOT == musparseXcsrilu0_zeroPivot(handle,
                                                                    info,
&position))
     {
         printf("U has structural and/or numerical zero at U(%d,%d)\n",
                position,
                position);
     }

     // Solve Lz = x
     musparseDcsrsv_solve(handle,
                            MUSPARSE_OPERATION_NON_TRANSPOSE,
                            m,
                            nnz,
                            &alpha,
                            descr_L,
                            csr_val,
                            csr_row_ptr,
                            csr_col_ind,
                            info,
                            x,
                            z,
                            MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                            temp_buffer);
   
     // Solve Uy = z
     musparseDcsrsv_solve(handle,
                            MUSPARSE_OPERATION_NON_TRANSPOSE,
                            m,
                            nnz,
                            &alpha,
                            descr_U,
                            csr_val,
                            csr_row_ptr,
                            csr_col_ind,
                            info,
                            z,
                            y,
                            MUSPARSE_SOLVE_POLICY_USE_LEVEL,
                            temp_buffer);
   
     // Clean up
     musaFree(temp_buffer);
     musparseDestroyMatInfo(info);
     musparseDestroyMatDescr(descr_M);
     musparseDestroyMatDescr(descr_L);
     musparseDestroyMatDescr(descr_U);
     musparseDestroy(handle);

musparseXcsrilu0 computes the incomplete LU factorization with 0 fill-ins and no pivoting of a sparse $m \times m$ CSR matrix $A$ , such that $A \approx LU$

musparseXcsrilu0 requires a user allocated temporary buffer. Its size is returned by musparseScsrilu0_bufferSize(), musparseDcsrilu0_bufferSize(), musparseCcsrilu0_bufferSize() or musparseZcsrilu0_bufferSize(). Furthermore, analysis meta data is required. It can be obtained by musparseScsrilu0_analysis(), musparseDcsrilu0_analysis(), musparseCcsrilu0_analysis() or musparseZcsrilu0_analysis(). musparseXcsrilu0 reports the first zero pivot (either numerical or structural zero). The zero pivot status can be obtained by calling [musparseXcsrilu0_zeroPivot()].

p descr, csr_val, csr_row_ptr or csr_col_ind pointer is invalid. *

function musparseXcsrilu0_zeroPivot

MUSPARSE_EXPORT musparseStatus_t musparseXcsrilu0_zeroPivot(
    musparseHandle_t handle,
    musparseMatInfo_t info,
    muInt * position
)

Incomplete LU factorization with 0 fill-ins and no pivoting using CSR storage format.

Parameters:

handle handle to the musparse library context queue.
info structure that holds the information collected during the analysis step.
position pointer to zero pivot $j$ , can be in host or device memory.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER info or position pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_INTERNAL_ERROR an internal error occurred.
MUSPARSE_EXPORT MUSPARSE_STATUS_ZERO_PIVOT zero pivot has been found.

Note: musparseXcsrilu0_zeroPivot is a blocking function. It might influence performance negatively.

musparseXcsrilu0_zeroPivot returns MUSPARSE_EXPORT MUSPARSE_STATUS_ZERO_PIVOT, if either a structural or numerical zero has been found during musparseScsrilu0(), musparseDcsrilu0(), musparseCcsrilu0() or musparseZcsrilu0() computation. The first zero pivot $j$ at $A_{j,j}$ is stored in position, using same index base as the CSR matrix.

position can be in host or device memory. If no zero pivot has been found, position is set to -1 and MUSPARSE_STATUS_SUCCESS is returned instead.

function musparseCreateCsr

MUSPARSE_EXPORT musparseStatus_t musparseCreateCsr(
    musparseSpMatDescr_t * descr,
    int64_t rows,
    int64_t cols,
    int64_t nnz,
    void * csr_row_ptr,
    void * csr_col_ind,
    void * csr_val,
    musparseIndexType_t row_ptr_type,
    musparseIndexType_t col_ind_type,
    musparseIndexBase_t idx_base,
    musparseDataType_t data_type
)

Create a sparse CSR matrix descriptor.

Parameters:

descr the pointer to the sparse CSR matrix descriptor.
rows number of rows in the CSR matrix.
cols number of columns in the CSR matrix
nnz number of non-zeros in the CSR matrix.
csr_row_ptr row offsets of the CSR matrix (must be array of length rows+1 ).
csr_col_ind column indices of the CSR matrix (must be array of length nnz ).
csr_val values of the CSR matrix (must be array of length nnz ).
row_ptr_type MUSPARSE_INDEX_32I or MUSPARSE_INDEX_64I.
col_ind_type MUSPARSE_INDEX_32I or MUSPARSE_INDEX_64I.
idx_base MUSPARSE_INDEX_BASE_ZERO or MUSPARSE_INDEX_BASE_ONE.
data_type MUSA_R_32F, MUSA_R_64F, MUSA_C_32F or MUSA_C_64F.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_POINTER if descr or csr_row_ptr or csr_col_ind or csr_val is invalid.
MUSPARSE_STATUS_INVALID_SIZE if rows or cols or nnz is invalid.
MUSPARSE_STATUS_INVALID_VALUE if row_ptr_type or col_ind_type or idx_base or data_type is invalid.

musparseCreateCsr creates a sparse CSR matrix descriptor. It should be destroyed at the end using musparseDestroySpMat.

function musparseCreateDnVec

MUSPARSE_EXPORT musparseStatus_t musparseCreateDnVec(
    musparseDnVecDescr_t * descr,
    int64_t size,
    void * values,
    musparseDataType_t data_type
)

Create a dense vector descriptor.

Parameters:

descr the pointer to the dense vector descriptor.
size size of the dense vector.
values non-zero values in the dense vector (must be array of length size ).
data_type MUSA_R_32F, MUSA_R_64F, MUSA_C_32F or MUSA_C_64F.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_POINTER if descr or values is invalid.
MUSPARSE_STATUS_INVALID_SIZE if size is invalid.
MUSPARSE_STATUS_INVALID_VALUE if data_type is invalid.

musparseCreateDnVec creates a dense vector descriptor. It should be destroyed at the end using musparseDestroyDnVec.

function musparseDestroyDnVec

MUSPARSE_EXPORT musparseStatus_t musparseDestroyDnVec(
    musparseDnVecDescr_t descr
)

Destroy a dense vector descriptor.

Parameters:

descr the matrix descriptor.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_POINTER descr is invalid.

musparseDestroyDnVec destroys a dense vector descriptor and releases all resources used by the descriptor.

function musparseSpMV

MUSPARSE_EXPORT musparseStatus_t musparseSpMV(
    musparseHandle_t handle,
    musparseOperation_t trans,
    const void * alpha,
    const musparseSpMatDescr_t mat,
    const musparseDnVecDescr_t x,
    const void * beta,
    const musparseDnVecDescr_t y,
    musparseDataType_t compute_type,
    musparseSpMVAlg_t alg,
    size_t * buffer_size,
    void * temp_buffer
)

Sparse matrix vector multiplication.

Parameters:

handle handle to the musparse library context queue.
trans matrix operation type.
alpha scalar $\alpha$ .
mat matrix descriptor.
x vector descriptor.
beta scalar $\beta$ .
y vector descriptor.
compute_type floating point precision for the SpMV computation.
alg SpMV algorithm for the SpMV computation.
buffer_size number of bytes of the temporary storage buffer. buffer_size is set when temp_buffer is nullptr.
temp_buffer temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to buffer_size and function returns without performing the SpMV operation.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER alpha, mat, x, beta, y or buffer_size pointer is
***** MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED compute_type or alg is currently not supported.

Note:

This function writes the required allocation size (in bytes) to buffer_size and returns without performing the SpMV operation, when a nullptr is passed for temp_buffer.
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

[musparseSpMV] multiplies the scalar $\alpha$ with a sparse $m \times n$ matrix and the dense vector $x$ and adds the result to the dense vector $y$ that is multiplied by the scalar $\beta$ , such that

y := \alpha \cdot op(A) \cdot x + \beta \cdot y,

with

op(A) = \begin{cases} A, & \text{if trans == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \\ A^T, & \text{if trans == MUSPARSE\_OPERATION\_TRANSPOSE} \\ A^H, & \text{if trans == MUSPARSE\_OPERATION\_CONJUGATE\_TRANSPOSE} \end{cases}

function musparseXgemvi

MUSPARSE_EXPORT musparseStatus_t musparseXgemvi()

Dense matrix sparse vector multiplication.

Parameters:

handle handle to the musparse library context queue.
trans matrix operation type.
m number of rows of the dense matrix.
n number of columns of the dense matrix.
alpha scalar $\alpha$ .
A pointer to the dense matrix.
lda leading dimension of the dense matrix
nnz number of non-zero entries in the sparse vector
x_val array of nnz elements containing the values of the sparse vector
x_ind array of nnz elements containing the indices of the sparse vector
beta scalar $\beta$ .
y array of m elements ( $op(A) == A$ ) or n elements ( $op(A) == A^T$ or $op(A) == A^H$ ).
idx_base MUSPARSE_INDEX_BASE_ZERO or MUSPARSE_INDEX_BASE_ONE.
temp_buffer temporary storage buffer

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE m, n, lda or nnz is invalid.
MUSPARSE_STATUS_INVALID_POINTER alpha, A, x_val, x_ind, beta, y or temp_buffer pointer is
***** MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans != MUSPARSE_OPERATION_NON_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

Note:

This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.
Currently, only trans == MUSPARSE_OPERATION_NON_TRANSPOSE is supported.

MUSPARSE_EXPORT
musparseStatus_t musparseSgemvi(musparseHandle_t handle,
                                musparseOperation_t trans, muInt m, muInt n,
                                const float* alpha, const float* A, muInt lda,
                                muInt nnz, const float* x_val,
                                const muInt* x_ind, const float* beta, float* y,
                                musparseIndexBase_t idx_base,
                                void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseDgemvi(musparseHandle_t handle,
                                musparseOperation_t trans, muInt m, muInt n,
                                const double* alpha, const double* A, muInt lda,
                                muInt nnz, const double* x_val,
                                const muInt* x_ind, const double* beta,
                                double* y, musparseIndexBase_t idx_base,
                                void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseCgemvi(musparseHandle_t handle,
                                musparseOperation_t trans, muInt m, muInt n,
                                const muComplex* alpha, const muComplex* A,
                                muInt lda, muInt nnz, const muComplex* x_val,
                                const muInt* x_ind, const muComplex* beta,
                                muComplex* y, musparseIndexBase_t idx_base,
                                void* temp_buffer);

MUSPARSE_EXPORT
musparseStatus_t musparseZgemvi(
    musparseHandle_t handle, musparseOperation_t trans, muInt m, muInt n,
    const muDoubleComplex* alpha, const muDoubleComplex* A, muInt lda,
    muInt nnz, const muDoubleComplex* x_val, const muInt* x_ind,
    const muDoubleComplex* beta, muDoubleComplex* y,
    musparseIndexBase_t idx_base, void* temp_buffer);  

musparseXgemvi multiplies the scalar $\alpha$ with a dense $m \times n$ matrix $A$ and the sparse vector $x$ and adds the result to the dense vector $y$ that is multiplied by the scalar $\beta$ , such that $y := \alpha \cdot op(A) \cdot x + \beta \cdot y,$ with

op(A) = \begin{cases} A, & \text{if trans == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \\ A^T, & \text{if trans == MUSPARSE\_OPERATION\_TRANSPOSE} \\ A^H, & \text{if trans == MUSPARSE\_OPERATION\_CONJUGATE\_TRANSPOSE} \end{cases}

musparseXgemvi requires a user allocated temporary buffer. Its size is returned by musparseSgemvi_bufferSize(), musparseDgemvi_bufferSize(), musparseCgemvi_bufferSize() or musparseZgemvi_bufferSize().

function musparseSpMM_ex

MUSPARSE_EXPORT musparseStatus_t musparseSpMM_ex(
    musparseHandle_t handle,
    musparseOperation_t trans_A,
    musparseOperation_t trans_B,
    const void * alpha,
    const musparseSpMatDescr_t mat_A,
    const musparseDnMatDescr_t mat_B,
    const void * beta,
    const musparseDnMatDescr_t mat_C,
    musparseDataType_t compute_type,
    musparseSpMMAlg_t alg,
    musparseSpMMStage_t stage,
    size_t * buffer_size,
    void * temp_buffer
)

Sparse matrix dense matrix multiplication, extension routine.

Parameters:

handle handle to the musparse library context queue.
trans_A matrix operation type.
trans_B matrix operation type.
alpha scalar $\alpha$ .
mat_A matrix descriptor.
mat_B matrix descriptor.
beta scalar $\beta$ .
mat_C matrix descriptor.
compute_type floating point precision for the SpMM computation.
alg SpMM algorithm for the SpMM computation.
stage SpMM stage for the SpMM computation.
buffer_size number of bytes of the temporary storage buffer. buffer_size is set when temp_buffer is nullptr.
temp_buffer temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to buffer_size and function returns without performing the SpMM operation.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER alpha, mat_A, mat_B, mat_C, beta, or buffer_size pointer is
***** MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans_A, trans_B, compute_type or alg is currently not supported.

Note:

This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.
Currently, only trans_A == MUSPARSE_OPERATION_NON_TRANSPOSE is supported for COO and Blocked ELL formats.
Currently, only CSR, COO and Blocked ELL sparse formats are supported.
Different algorithms are available which can provide better performance for different matrices. Currently, the available algorithms are MUSPARSE_SPMM_ALG_CSR, MUSPARSE_SPMM_ALG_CSR_ROW_SPLIT or MUSPARSE_SPMM_ALG_CSR_MERGE for CSR matrices, MUSPARSE_SPMM_ALG_BLOCKED_ELL for Blocked ELL matrices and MUSPARSE_SPMM_ALG_COO_SEGMENTED or MUSPARSE_SPMM_ALG_COO_ATOMIC for COO matrices. Additionally, one can specify the algorithm to be MUSPARSE_SPMM_ALG_DEFAULT. In the case of CSR matrices this will set the algorithm to be MUSPARSE_SPMM_ALG_CSR, in the case of Blocked ELL matrices this will set the algorithm to be MUSPARSE_SPMM_ALG_BLOCKED_ELL and for COO matrices it will set the algorithm to be MUSPARSE_SPMM_ALG_COO_ATOMIC.
This function writes the required allocation size (in bytes) to buffer_size and returns without performing the SpMM operation, when a nullptr is passed for temp_buffer.
SpMM requires three stages to complete. The first stage MUSPARSE_SPMM_STAGE_BUFFER_SIZE will return the size of the temporary storage buffer that is required for subsequent calls to musparseSpMM (or [musparseSpMM_ex]). The second stage MUSPARSE_SPMM_STAGE_PREPROCESS will preprocess data that would be saved in the temporary storage buffer. In the final stage MUSPARSE_SPMM_STAGE_COMPUTE, the actual computation is performed.
If MUSPARSE_SPMM_STAGE_AUTO is selected, musparse will automatically detect which stage is required based on the following indicators: If temp_buffer is equal to nullptr, the required buffer size will be returned. Else, the SpMM preprocess and the SpMM algorithm will be executed.

musparseSpMM (or musparseSpMM_ex ) multiplies the scalar $\alpha$ with a sparse $m \times k$ matrix $A$ , defined in CSR or COO or Blocked ELL storage format, and the dense $k \times n$ matrix $B$ and adds the result to the dense $m \times n$ matrix $C$ that is multiplied by the scalar $\beta$ , such that $C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot C,$ with

op(A) = \begin{cases} A, & \text{if trans\_A == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \\ A^T, & \text{if trans\_A == MUSPARSE\_OPERATION\_TRANSPOSE} \\ A^H, & \text{if trans\_A == MUSPARSE\_OPERATION\_CONJUGATE\_TRANSPOSE} \end{cases}

and

op(B) = \begin{cases} B, & \text{if trans\_B == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \\ B^T, & \text{if trans\_B == MUSPARSE\_OPERATION\_TRANSPOSE} \\ B^H, & \text{if trans\_B == MUSPARSE\_OPERATION\_CONJUGATE\_TRANSPOSE} \end{cases}

function musparseSpMM

MUSPARSE_EXPORT musparseStatus_t musparseSpMM(
    musparseHandle_t handle,
    musparseOperation_t trans_A,
    musparseOperation_t trans_B,
    const void * alpha,
    const musparseSpMatDescr_t mat_A,
    const musparseDnMatDescr_t mat_B,
    const void * beta,
    const musparseDnMatDescr_t mat_C,
    musparseDataType_t compute_type,
    musparseSpMMAlg_t alg,
    musparseSpMMStage_t stage,
    size_t * buffer_size,
    void * temp_buffer
)

function musparseSpSM

MUSPARSE_EXPORT musparseStatus_t musparseSpSM(
    musparseHandle_t handle,
    musparseOperation_t trans_A,
    musparseOperation_t trans_B,
    const void * alpha,
    const musparseSpMatDescr_t matA,
    const musparseDnMatDescr_t matB,
    const musparseDnMatDescr_t matC,
    musparseDataType_t compute_type,
    musparseSpSMAlg_t alg,
    musparseSpSMStage_t stage,
    size_t * buffer_size,
    void * temp_buffer
)

Sparse triangular system solve.

Parameters:

handle handle to the musparse library context queue.
trans_A matrix operation type for the sparse matrix A.
trans_B matrix operation type for the dense matrix B.
alpha scalar $\alpha$ .
matA sparse matrix descriptor.
matB dense matrix descriptor.
matC dense matrix descriptor.
compute_type floating point precision for the SpSM computation.
alg SpSM algorithm for the SpSM computation.
stage SpSM stage for the SpSM computation.
buffer_size number of bytes of the temporary storage buffer.
temp_buffer temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to buffer_size and function returns without performing the SpSM operation.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER alpha, matA, matB, matC, descr or buffer_size pointer is
***** MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans_A, trans_B, compute_type, stage or alg is currently not supported.

Note:

SpSM requires three stages to complete. The first stage MUSPARSE_SPSM_STAGE_BUFFER_SIZE will return the size of the temporary storage buffer that is required for subsequent calls. The second stage MUSPARSE_SPSM_STAGE_PREPROCESS will preprocess data that would be saved in the temporary storage buffer. In the final stage MUSPARSE_SPSM_STAGE_COMPUTE, the actual computation is performed.
If MUSPARSE_SPSM_STAGE_AUTO is selected, musparse will automatically detect which stage is required based on the following indicators: If temp_buffer is equal to nullptr, the required buffer size will be returned. If buffer_size is equal to nullptr, analysis will be performed. Otherwise, the SpSM preprocess and the SpSM algorithm will be executed.
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.
Currently, only trans_A == MUSPARSE_OPERATION_NON_TRANSPOSE and trans_A == MUSPARSE_OPERATION_TRANSPOSE is supported. Currently, only trans_B == MUSPARSE_OPERATION_NON_TRANSPOSE and trans_B == MUSPARSE_OPERATION_TRANSPOSE is supported.

musparse_spsm_solve solves a sparse triangular linear system of a sparse $m \times m$ matrix, defined in CSR or COO storage format, a dense solution matrix $C$ and the right-hand side $B$ that is multiplied by $\alpha$ , such that $op(A) \cdot C = \alpha \cdot op(B),$ with

op(A) = \begin{cases} A, & \text{if trans == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \\ A^T, & \text{if trans == MUSPARSE\_OPERATION\_TRANSPOSE} \\ A^H, & \text{if trans == MUSPARSE\_OPERATION\_CONJUGATE\_TRANSPOSE} \end{cases}

and

op(B) = \begin{cases} B, & \text{if trans\_B == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \\ B^T, & \text{if trans\_B == MUSPARSE\_OPERATION\_TRANSPOSE} \\ B^H, & \text{if trans\_B == MUSPARSE\_OPERATION\_CONJUGATE\_TRANSPOSE} \end{cases}

function musparseSpGEMM

MUSPARSE_EXPORT musparseStatus_t musparseSpGEMM(
    musparseHandle_t handle,
    musparseOperation_t trans_A,
    musparseOperation_t trans_B,
    const void * alpha,
    const musparseSpMatDescr_t A,
    const musparseSpMatDescr_t B,
    const void * beta,
    const musparseSpMatDescr_t D,
    musparseSpMatDescr_t C,
    musparseDataType_t compute_type,
    musparseSpGEMMAlg_t alg,
    musparseSpGEMMStage_t stage,
    size_t * buffer_size,
    void * temp_buffer
)

Sparse matrix sparse matrix multiplication.

Parameters:

handle handle to the musparse library context queue.
trans_A sparse matrix $A$ operation type.
trans_B sparse matrix $B$ operation type.
alpha scalar $\alpha$ .
A sparse matrix $A$ descriptor.
B sparse matrix $B$ descriptor.
beta scalar $\beta$ .
D sparse matrix $D$ descriptor.
C sparse matrix $C$ descriptor.
compute_type floating point precision for the SpGEMM computation.
alg SpGEMM algorithm for the SpGEMM computation.
stage SpGEMM stage for the SpGEMM computation.
buffer_size number of bytes of the temporary storage buffer. buffer_size is set when temp_buffer is nullptr.
temp_buffer temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to buffer_size and function returns without performing the SpGEMM operation.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER alpha and beta are invalid, A, B, D, C or buffer_size pointer is invalid. *
MUSPARSE_EXPORT MUSPARSE_STATUS_MEMORY_ERROR additional buffer for long rows could not be allocated.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans_A != MUSPARSE_OPERATION_NON_TRANSPOSE or trans_B != MUSPARSE_OPERATION_NON_TRANSPOSE.

Note:

SpGEMM requires three stages to complete. The first stage MUSPARSE_SPGEMM_STAGE_BUFFER_SIZE will return the size of the temporary storage buffer that is required for subsequent calls to [musparseSpGEMM]. The second stage MUSPARSE_SPGEMM_STAGE_NNZ will determine the number of non-zero elements of the resulting $C$ matrix. If the sparsity pattern of $C$ is already known, this stage can be skipped. In the final stage MUSPARSE_SPGEMM_STAGE_COMPUTE, the actual computation is performed.
If MUSPARSE_SPGEMM_STAGE_AUTO is selected, musparse will automatically detect which stage is required based on the following indicators: If temp_buffer is equal to nullptr, the required buffer size will be returned. Else, if the number of non-zeros of $C$ is zero, the number of non-zero entries will be computed. Else, the SpGEMM algorithm will be executed.
If $\alpha == 0$ , then $C = \beta \cdot D$ will be computed.
If $\beta == 0$ , then $C = \alpha \cdot op(A) \cdot op(B)$ will be computed.
If MUSPARSE_SPGEMM_STAGE_SYMBOLIC is selected then the symbolic computation is performed only.
If MUSPARSE_SPGEMM_STAGE_NUMERIC is selected then the numeric computation is performed only.
$\alpha == beta == 0$ is invalid.
It is allowed to pass the same sparse matrix for $C$ and $D$ , if both matrices have the same sparsity pattern.
Currently, only trans_A == MUSPARSE_OPERATION_NON_TRANSPOSE is supported.
Currently, only trans_B == MUSPARSE_OPERATION_NON_TRANSPOSE is supported.
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.
Please note, that for rare matrix products with more than 4096 non-zero entries per row, additional temporary storage buffer is allocated by the algorithm.

[musparseSpGEMM] multiplies the scalar $\alpha$ with the sparse $m \times k$ matrix $A$ and the sparse $k \times n$ matrix $B$ and adds the result to the sparse $m \times n$ matrix $D$ that is multiplied by $\beta$ . The final result is stored in the sparse $m \times n$ matrix $C$ , such that

C := \alpha \cdot op(A) \cdot op(B) + \beta \cdot D,

with

op(A) = \begin{cases} A, & \text{if trans\_A == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \\ A^T, & \text{if trans\_A == MUSPARSE\_OPERATION\_TRANSPOSE} \\ A^H, & \text{if trans\_A == MUSPARSE\_OPERATION\_CONJUGATE\_TRANSPOSE} \end{cases}

and

op(B) = \begin{cases} B, & \text{if trans\_B == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \\ B^T, & \text{if trans\_B == MUSPARSE\_OPERATION\_TRANSPOSE} \\ B^H, & \text{if trans\_B == MUSPARSE\_OPERATION\_CONJUGATE\_TRANSPOSE} \end{cases}

function musparseXbsrmv

MUSPARSE_EXPORT musparseStatus_t musparseXbsrmv()

Sparse matrix vector multiplication using BSR storage format.

Parameters:

handle handle to the musparse library context queue.
dir matrix storage of BSR blocks.
trans matrix operation type.
mb number of block rows of the sparse BSR matrix.
nb number of block columns of the sparse BSR matrix.
nnzb number of non-zero blocks of the sparse BSR matrix.
alpha scalar $\alpha$ .
descr descriptor of the sparse BSR matrix. Currently, only MUSPARSE_MATRIX_TYPE_GENERAL is supported.
bsr_val array of nnzb blocks of the sparse BSR matrix.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix.
bsr_col_ind array of nnzb elements containing the block column indices of the sparse BSR matrix.
block_dim block dimension of the sparse BSR matrix.
x array of nb*block_dim elements ( $op(A) = A$ ) or mb*block_dim elements ( $op(A) = A^T$ or $op(A) = A^H$ ).
beta scalar $\beta$ .
y array of mb*block_dim elements ( $op(A) = A$ ) or nb*block_dim elements ( $op(A) = A^T$ or $op(A) = A^H$ ).

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb, nb, nnzb or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER descr, alpha, bsr_val, bsr_row_ind, bsr_col_ind, x, beta or y pointer is invalid.
MUSPARSE_EXPORT MUSPARSE_STATUS_ARCH_MISMATCH the the device is not supported.
MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans != MUSPARSE_OPERATION_NON_TRANSPOSE or musparseMatrixType_t != MUSPARSE_MATRIX_TYPE_GENERAL.

Note:

This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.
Currently, only trans == MUSPARSE_OPERATION_NON_TRANSPOSE is supported.

MUSPARSE_EXPORT
musparseStatus_t musparseSbsrmv(musparseHandle_t handle,
                                musparseDirection_t dir,
                                musparseOperation_t trans, muInt mb, muInt nb,
                                muInt nnzb, const float* alpha,
                                const musparseMatDescr_t descr,
                                const float* bsr_val, const muInt* bsr_row_ptr,
                                const muInt* bsr_col_ind, muInt block_dim,
                                const float* x, const float* beta, float* y);

MUSPARSE_EXPORT
musparseStatus_t musparseDbsrmv(musparseHandle_t handle,
                                musparseDirection_t dir,
                                musparseOperation_t trans, muInt mb, muInt nb,
                                muInt nnzb, const double* alpha,
                                const musparseMatDescr_t descr,
                                const double* bsr_val, const muInt* bsr_row_ptr,
                                const muInt* bsr_col_ind, muInt block_dim,
                                const double* x, const double* beta, double* y);

MUSPARSE_EXPORT
musparseStatus_t musparseCbsrmv(
    musparseHandle_t handle, musparseDirection_t dir, musparseOperation_t trans,
    muInt mb, muInt nb, muInt nnzb, const muComplex* alpha,
    const musparseMatDescr_t descr, const muComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    const muComplex* x, const muComplex* beta, muComplex* y);

MUSPARSE_EXPORT
musparseStatus_t musparseZbsrmv(
    musparseHandle_t handle, musparseDirection_t dir, musparseOperation_t trans,
    muInt mb, muInt nb, muInt nnzb, const muDoubleComplex* alpha,
    const musparseMatDescr_t descr, const muDoubleComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    const muDoubleComplex* x, const muDoubleComplex* beta, muDoubleComplex* y);

musparseXbsrmv multiplies the scalar $\alpha$ with a sparse $(mb \cdot \text{block_dim}) \times (nb \cdot \text{block_dim})$ matrix, defined in BSR storage format, and the dense vector $x$ and adds the result to the dense vector $y$ that is multiplied by the scalar $\beta$ , such that:

musparseXbsrmv multiplies the scalar $\alpha$ with a sparse $(mb \cdot \text{block\_dim}) \times (nb \cdot \text{block\_dim})$ matrix, defined in BSR storage format, and the dense vector $x$ , and adds the result to the dense vector $y$ that is multiplied by the scalar $\beta$ , such that:

y := \alpha \cdot op(A) \cdot x + \beta \cdot y

with

op(A) = \left\{ \begin{array}{ll} A, & \text{if trans == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \\ A^T, & \text{if trans == MUSPARSE\_OPERATION\_TRANSPOSE} \\ A^H, & \text{if trans == MUSPARSE\_OPERATION\_CONJUGATE\_TRANSPOSE} \end{array} \right.

function musparseXbsr2csr

MUSPARSE_EXPORT musparseStatus_t musparseXbsr2csr()

Convert a sparse BSR matrix into a sparse CSR matrix.

Parameters:

handle handle to the musparse library context queue.
dir the storage format of the blocks, MUSPARSE_DIRECTION_ROW or MUSPARSE_DIRECTION_COLUMN
mb number of block rows in the sparse BSR matrix.
nb number of block columns in the sparse BSR matrix.
bsr_descr descriptor of the sparse BSR matrix. Currently, only MUSPARSE_MATRIX_TYPE_GENERAL is supported.
bsr_val array of nnzb*block_dim*block_dim containing the values of the sparse BSR matrix.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix.
bsr_col_ind array of nnzb elements containing the block column indices of the sparse BSR matrix.
block_dim size of the blocks in the sparse BSR matrix.
csr_descr descriptor of the sparse CSR matrix. Currently, only MUSPARSE_MATRIX_TYPE_GENERAL is supported.
csr_val array of nnzb*block_dim*block_dim elements containing the values of the sparse CSR matrix.
csr_row_ptr 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 array of nnzb*block_dim*block_dim elements containing the column indices of the sparse CSR matrix.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE mb or nb or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER bsr_val, bsr_row_ptr, bsr_col_ind, csr_val, csr_row_ptr or csr_col_ind pointer is invalid.

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

MUSPARSE_EXPORT
musparseStatus_t musparseSbsr2csr(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nb,
    const musparseMatDescr_t bsr_descr, const float* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    const musparseMatDescr_t csr_descr, float* csr_val, muInt* csr_row_ptr,
    muInt* csr_col_ind);

MUSPARSE_EXPORT
musparseStatus_t musparseDbsr2csr(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nb,
    const musparseMatDescr_t bsr_descr, const double* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    const musparseMatDescr_t csr_descr, double* csr_val, muInt* csr_row_ptr,
    muInt* csr_col_ind);

MUSPARSE_EXPORT
musparseStatus_t musparseCbsr2csr(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nb,
    const musparseMatDescr_t bsr_descr, const muComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    const musparseMatDescr_t csr_descr, muComplex* csr_val, muInt* csr_row_ptr,
    muInt* csr_col_ind);

MUSPARSE_EXPORT
musparseStatus_t musparseZbsr2csr(
    musparseHandle_t handle, musparseDirection_t dir, muInt mb, muInt nb,
    const musparseMatDescr_t bsr_descr, const muDoubleComplex* bsr_val,
    const muInt* bsr_row_ptr, const muInt* bsr_col_ind, muInt block_dim,
    const musparseMatDescr_t csr_descr, muDoubleComplex* csr_val,
    muInt* csr_row_ptr, muInt* csr_col_ind);

Example:

This example converts a 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
    
     muInt mb   = 2;
     muInt nb   = 3;
     muInt block_dim = 2;
     muInt m = Mb * block_dim;
     muInt n = Nb * block_dim;
    
     bsr_row_ptr[mb+1]                 = {0, 2, 5}; // device memory
     bsr_col_ind[nnzb]                 = {0, 1, 0, 1, 2}; // device memory
     bsr_val[nnzb*block_dim*block_dim] = {1, 0, 4, 2, 0, 3, 0, 0, 5, 0, 0, 0,
0, 9, 7, 0, 8, 6, 0, 0}; // device memory

     muInt nnzb = bsr_row_ptr[mb] - bsr_row_ptr[0];
    
     // Create CSR arrays on device
     muInt* csr_row_ptr;
     muInt* csr_col_ind;
     float* csr_val;
     musaMalloc((void**)&csr_row_ptr, sizeof(muInt) * (m + 1));
     musaMalloc((void**)&csr_col_ind, sizeof(muInt) * nnzb *
block_dim * block_dim); musaMalloc((void**)&csr_val, sizeof(float) * nnzb *
block_dim * block_dim);

     // Create musparse handle
     musparse_local_handle handle;
    
     musparseMatDescr_t bsr_descr = nullptr;
     musparseCreateMatDescr(&bsr_descr);
    
     musparseMatDescr_t csr_descr = nullptr;
     musparseCreateMatDescr(&csr_descr);
    
     musparseSetMatIndexBase(bsr_descr, MUSPARSE_INDEX_BASE_ZERO);
     musparseSetMatIndexBase(csr_descr, MUSPARSE_INDEX_BASE_ZERO);
    
     // Format conversion
     musparseSbsr2csr(handle,
                        MUSPARSE_DIRECTION_COLUMN,
                        mb,
                        nb,
                        bsr_descr,
                        bsr_val,
                        bsr_row_ptr,
                        bsr_col_ind,
                        block_dim,
                        csr_descr,
                        csr_val,
                        csr_row_ptr,
                        csr_col_ind);

musparseXbsr2csr 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 computed by the number of block rows multiplied by the block dimension plus one. 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.

function musparseXcsr2bsr

MUSPARSE_EXPORT musparseStatus_t musparseXcsr2bsr()

Convert a sparse CSR matrix into a sparse BSR matrix.

Parameters:

handle handle to the musparse library context queue.
dir the storage format of the blocks, MUSPARSE_DIRECTION_ROW or MUSPARSE_DIRECTION_COLUMN
m number of rows in the sparse CSR matrix.
n number of columns in the sparse CSR matrix.
csr_descr descriptor of the sparse CSR matrix. Currently, only MUSPARSE_MATRIX_TYPE_GENERAL is supported.
csr_val array of nnz elements containing the values of the sparse CSR matrix.
csr_row_ptr array of m+1 elements that point to the start of every row of the sparse CSR matrix.
csr_col_ind array of nnz elements containing the column indices of the sparse CSR matrix.
block_dim size of the blocks in the sparse BSR matrix.
bsr_descr descriptor of the sparse BSR matrix. Currently, only MUSPARSE_MATRIX_TYPE_GENERAL is supported.
bsr_val array of nnzb*block_dim*block_dim containing the values of the sparse BSR matrix.
bsr_row_ptr array of mb+1 elements that point to the start of every block row of the sparse BSR matrix.
bsr_col_ind array of nnzb elements containing the block column indices of the sparse BSR matrix.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_SIZE m or n or block_dim is invalid.
MUSPARSE_STATUS_INVALID_POINTER bsr_val, bsr_row_ptr, bsr_col_ind, csr_val, csr_row_ptr or csr_col_ind pointer is invalid.

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

muInt m   = 4;
muInt n   = 6;
muInt block_dim = 2;
muInt nnz = 9;
muInt mb = (m + block_dim - 1) / block_dim;
muInt 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

musaMalloc(&bsr_row_ptr, sizeof(muInt) *(mb + 1));
muInt nnzb;
muInt* nnzTotalHostPtr = &nnzb;
csr2bsr_nnz(handle,
            MUSPARSE_DIRECTION_ROW,
            m,
            n,
            csr_descr,
            csr_row_ptr,
            csr_col_ind,
            block_dim,
            bsr_descr,
            bsr_row_ptr,
            nnzTotalHostPtr);
nnzb = *nnzTotalDevHostPtr;
musaMalloc(&bsr_col_ind, sizeof(int)*nnzb);
musaMalloc(&bsr_val, sizeof(float)*(block_dim * block_dim) * nnzb);
scsr2bsr(handle,
         MUSPARSE_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);

musparseXcsr2bsr 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 in the BSR matrix. Allocation size for bsr_val and bsr_col_ind is computed using csr2bsr_nnz() which also fills in bsr_row_ptr.

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

MUSPARSE_EXPORT
musparseStatus_t musparseScsr2bsr(
    musparseHandle_t handle, musparseDirection_t dir, muInt m, muInt n,
    const musparseMatDescr_t csr_descr, const float* csr_val,
    const muInt* csr_row_ptr, const muInt* csr_col_ind, muInt block_dim,
    const musparseMatDescr_t bsr_descr, float* bsr_val, muInt* bsr_row_ptr,
    muInt* bsr_col_ind);

MUSPARSE_EXPORT
musparseStatus_t musparseDcsr2bsr(
    musparseHandle_t handle, musparseDirection_t dir, muInt m, muInt n,
    const musparseMatDescr_t csr_descr, const double* csr_val,
    const muInt* csr_row_ptr, const muInt* csr_col_ind, muInt block_dim,
    const musparseMatDescr_t bsr_descr, double* bsr_val, muInt* bsr_row_ptr,
    muInt* bsr_col_ind);

MUSPARSE_EXPORT
musparseStatus_t musparseCcsr2bsr(
    musparseHandle_t handle, musparseDirection_t dir, muInt m, muInt n,
    const musparseMatDescr_t csr_descr, const muComplex* csr_val,
    const muInt* csr_row_ptr, const muInt* csr_col_ind, muInt block_dim,
    const musparseMatDescr_t bsr_descr, muComplex* bsr_val, muInt* bsr_row_ptr,
    muInt* bsr_col_ind);

MUSPARSE_EXPORT
musparseStatus_t musparseZcsr2bsr(
    musparseHandle_t handle, musparseDirection_t dir, muInt m, muInt n,
    const musparseMatDescr_t csr_descr, const muDoubleComplex* csr_val,
    const muInt* csr_row_ptr, const muInt* csr_col_ind, muInt block_dim,
    const musparseMatDescr_t bsr_descr, muDoubleComplex* bsr_val,
    muInt* bsr_row_ptr, muInt* bsr_col_ind);

function musparseSparseToDense

MUSPARSE_EXPORT musparseStatus_t musparseSparseToDense(
    musparseHandle_t handle,
    const musparseSpMatDescr_t mat_A,
    musparseDnMatDescr_t mat_B,
    musparseSparseToDenseAlg_t alg,
    size_t * buffer_size,
    void * temp_buffer
)

Sparse matrix to dense matrix conversion.

Parameters:

handle handle to the musparse library context queue.
mat_A sparse matrix descriptor.
mat_B dense matrix descriptor.
alg algorithm for the sparse to dense computation.
buffer_size number of bytes of the temporary storage buffer. buffer_size is set when temp_buffer is nullptr.
temp_buffer temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to buffer_size and function returns without performing the sparse to dense operation.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER mat_A, mat_B, or buffer_size pointer is invalid.

Note:

This function writes the required allocation size (in bytes) to buffer_size and returns without performing the sparse to dense operation, when a nullptr is passed for temp_buffer.
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

musparseSparseToDense``musparseSparseToDense performs the conversion of a sparse matrix in CSR, CSC, or COO format to a dense matrix

function musparseDenseToSparse

MUSPARSE_EXPORT musparseStatus_t musparseDenseToSparse(
    musparseHandle_t handle,
    const musparseDnMatDescr_t mat_A,
    musparseSpMatDescr_t mat_B,
    musparseDenseToSparseAlg_t alg,
    size_t * buffer_size,
    void * temp_buffer
)

Dense matrix to sparse matrix conversion.

Parameters:

handle handle to the musparse library context queue.
mat_A dense matrix descriptor.
mat_B sparse matrix descriptor.
alg algorithm for the sparse to dense computation.
buffer_size number of bytes of the temporary storage buffer. buffer_size is set when temp_buffer is nullptr.
temp_buffer temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to buffer_size and function returns without performing the dense to sparse operation.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER mat_A, mat_B, or buffer_size pointer is invalid.

Note:

This function writes the required allocation size (in bytes) to buffer_size and returns without performing the dense to sparse operation, when a nullptr is passed for temp_buffer.
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

musparseDenseToSparse``musparseDenseToSparse performs the conversion of a dense matrix to a sparse matrix in CSR, CSC, or COO format.

function musparseAxpby

MUSPARSE_EXPORT musparseStatus_t musparseAxpby(
    musparseHandle_t handle,
    const void * alpha,
    const musparseSpVecDescr_t x,
    const void * beta,
    musparseDnVecDescr_t y
)

Scale a sparse vector and add it to a scaled dense vector.

Parameters:

handle handle to the musparse library context queue.
alpha scalar $\alpha$ .
x sparse matrix descriptor.
beta scalar $\beta$ .
y dense matrix descriptor.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER alpha, x, beta or y pointer is invalid.

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

[musparseAxpby] multiplies the sparse vector $x$ with scalar $\alpha$ and adds the result to the dense vector $y$ that is multiplied with scalar $\beta$ , such that

y := \alpha \cdot x + \beta \cdot y

for(i = 0; i < nnz; ++i)
{
   y[x_ind[i]] = alpha * x_val[i] + beta * y[x_ind[i]]
}

function musparseSpVV

MUSPARSE_EXPORT musparseStatus_t musparseSpVV(
    musparseHandle_t handle,
    musparseOperation_t trans,
    const musparseSpVecDescr_t x,
    const musparseDnVecDescr_t y,
    void * result,
    musparseDataType_t compute_type,
    size_t * buffer_size,
    void * temp_buffer
)

Sparse vector inner dot product.

Parameters:

handle handle to the musparse library context queue.
trans sparse vector operation type.
x sparse vector descriptor.
y dense vector descriptor.
result pointer to the result, can be host or device memory
compute_type floating point precision for the SpVV computation.
buffer_size number of bytes of the temporary storage buffer. buffer_size is set when temp_buffer is nullptr.
temp_buffer temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to buffer_size and function returns without performing the SpVV operation.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER x, y, result or buffer_size pointer is
***** MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED compute_type is currently not supported.

Note:

This function writes the required allocation size (in bytes) to buffer_size and returns without performing the SpVV operation, when a nullptr is passed for temp_buffer.
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.

[musparseSpVV] computes the inner dot product of the sparse vecotr $x$ with the dense vector $y$ , such that

\text{result} := x^{'} \cdot y,

with

op(x) = \begin{cases} x, & \text{if trans == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \\ \bar{x}, & \text{if trans == MUSPARSE\_OPERATION\_CONJUGATE\_TRANSPOSE} \end{cases}

result = 0;
for(i = 0; i < nnz; ++i)
{
    result += x_val[i] * y[x_ind[i]];
}

function musparseSpSV

MUSPARSE_EXPORT musparseStatus_t musparseSpSV(
    musparseHandle_t handle,
    musparseOperation_t trans,
    const void * alpha,
    const musparseSpMatDescr_t mat,
    const musparseDnVecDescr_t x,
    const musparseDnVecDescr_t y,
    musparseDataType_t compute_type,
    musparseSpSVAlg_t alg,
    musparseSpSVStage_t stage,
    size_t * buffer_size,
    void * temp_buffer
)

Sparse triangular solve.

Parameters:

handle handle to the musparse library context queue.
trans matrix operation type.
alpha scalar $\alpha$ .
mat matrix descriptor.
x vector descriptor.
y vector descriptor.
compute_type floating point precision for the SpSV computation.
alg SpSV algorithm for the SpSV computation.
stage SpSV stage for the SpSV computation.
buffer_size number of bytes of the temporary storage buffer.
temp_buffer temporary storage buffer allocated by the user. When a nullptr is passed, the required allocation size (in bytes) is written to buffer_size and function returns without performing the SpSV operation.

Returns:

MUSPARSE_STATUS_SUCCESS the operation completed successfully.
MUSPARSE_STATUS_INVALID_HANDLE the library context was not initialized.
MUSPARSE_STATUS_INVALID_POINTER alpha, mat, x, y, descr or buffer_size pointer is
***** MUSPARSE_EXPORT MUSPARSE_STATUS_NOT_IMPLEMENTED trans, compute_type, stage or alg is currently not supported.

Note:

SpSV requires three stages to complete. The first stage MUSPARSE_SPSV_STAGE_BUFFER_SIZE will return the size of the temporary storage buffer that is required for subsequent calls. The second stage MUSPARSE_SPSV_STAGE_PREPROCESS will preprocess data that would be saved in the temporary storage buffer. In the final stage MUSPARSE_SPSV_STAGE_COMPUTE, the actual computation is performed.
If MUSPARSE_SPSV_STAGE_AUTO is selected, musparse will automatically detect which stage is required based on the following indicators: If temp_buffer is equal to nullptr, the required buffer size will be returned. If buffer_size is equal to nullptr, analysis will be performed. Otherwise, the SpSV preprocess and the SpSV algorithm will be executed.
This function is non blocking and executed asynchronously with respect to the host. It may return before the actual computation has finished.
Currently, only trans == MUSPARSE_OPERATION_NON_TRANSPOSE and trans == MUSPARSE_OPERATION_TRANSPOSE is supported.

musparse_spsv_solve solves a sparse triangular linear system of a sparse $m \times m$ matrix, defined in CSR or COO storage format, a dense solution vector $y$ and the right-hand side $x$ that is multiplied by $\alpha$ , such that $op(A) \cdot y = \alpha \cdot x,$ with

op(A) = \begin{cases} A, & \text{if trans == MUSPARSE\_OPERATION\_NON\_TRANSPOSE} \\ A^T, & \text{if trans == MUSPARSE\_OPERATION\_TRANSPOSE} \\ A^H, & \text{if trans == MUSPARSE\_OPERATION\_CONJUGATE\_TRANSPOSE} \end{cases}

Functions​

Functions Documentation​

function musparseSetMatDiagType​

function musparseSetMatFillMode​

function musparseSetMatIndexBase​

function musparseXbsrsv_bufferSize​

function musparseXbsrsv_analysis​

function musparseXbsrsv_solve​

function musparseXbsrsv_zeroPivot​

function musparseXbsrsm_bufferSize​

function musparseXbsrsm_analysis​

function musparseXbsrsm_solve​

function musparseXbsrsm_zeroPivot​

function musparseXbsrilu0_numericBoost​

function musparseXbsrilu0_bufferSize​

function musparseXbsrilu0_analysis​

function musparseXbsrilu0​

function musparseXbsrilu0_zeroPivot​

function musparseCreate​

function musparseDestroy​

function musparseCreateMatDescr​

function musparseDestroyMatDescr​

function musparseGetMatDiagType​

function musparseGetMatFillMode​

function musparseGetMatIndexBase​

function musparseGetMatType​

function musparseXbsrmm​

function musparseXcsric0_bufferSize​

function musparseXcsric0_analysis​

function musparseXcsric0​

function musparseXcsric0_zeroPivot​

function musparseXbsric0_bufferSize​

function musparseXbsric0_analysis​

function musparseXbsric0​

function musparseXbsric0_zeroPivot​

function musparseXcsrilu0_numericBoost​

function musparseXcsrilu0_bufferSize​

function musparseXcsrilu0_analysis​

function musparseXcsrilu0​

function musparseXcsrilu0_zeroPivot​

function musparseCreateCsr​

function musparseCreateDnVec​

function musparseDestroyDnVec​

function musparseSpMV​

function musparseXgemvi​

function musparseSpMM_ex​

function musparseSpMM​

function musparseSpSM​

function musparseSpGEMM​

function musparseXbsrmv​

function musparseXbsr2csr​

function musparseXcsr2bsr​

function musparseSparseToDense​

function musparseDenseToSparse​

function musparseAxpby​

function musparseSpVV​

function musparseSpSV​

这篇文章对您有帮助吗？

Functions

Functions Documentation

function musparseSetMatDiagType

function musparseSetMatFillMode

function musparseSetMatIndexBase

function musparseXbsrsv_bufferSize

function musparseXbsrsv_analysis

function musparseXbsrsv_solve

function musparseXbsrsv_zeroPivot

function musparseXbsrsm_bufferSize

function musparseXbsrsm_analysis

function musparseXbsrsm_solve

function musparseXbsrsm_zeroPivot

function musparseXbsrilu0_numericBoost

function musparseXbsrilu0_bufferSize

function musparseXbsrilu0_analysis

function musparseXbsrilu0

function musparseXbsrilu0_zeroPivot

function musparseCreate

function musparseDestroy

function musparseCreateMatDescr

function musparseDestroyMatDescr

function musparseGetMatDiagType

function musparseGetMatFillMode

function musparseGetMatIndexBase

function musparseGetMatType

function musparseXbsrmm

function musparseXcsric0_bufferSize

function musparseXcsric0_analysis

function musparseXcsric0

function musparseXcsric0_zeroPivot

function musparseXbsric0_bufferSize

function musparseXbsric0_analysis

function musparseXbsric0

function musparseXbsric0_zeroPivot

function musparseXcsrilu0_numericBoost

function musparseXcsrilu0_bufferSize

function musparseXcsrilu0_analysis

function musparseXcsrilu0

function musparseXcsrilu0_zeroPivot

function musparseCreateCsr

function musparseCreateDnVec

function musparseDestroyDnVec

function musparseSpMV

function musparseXgemvi

function musparseSpMM_ex

function musparseSpMM

function musparseSpSM

function musparseSpGEMM

function musparseXbsrmv

function musparseXbsr2csr

function musparseXcsr2bsr

function musparseSparseToDense

function musparseDenseToSparse

function musparseAxpby

function musparseSpVV

function musparseSpSV