/*! \file */ /* ************************************************************************ * Copyright (C) 2025 Advanced Micro Devices, Inc. All rights Reserved. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal * in the Software without restriction, including without limitation the rights * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell * copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN * THE SOFTWARE. * * ************************************************************************ */ #ifndef HIPSPARSE_BSRIC0_H #define HIPSPARSE_BSRIC0_H #ifdef __cplusplus extern "C" { #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 13000) /*! \ingroup precond_module * \details * \p hipsparseXbsric02_zeroPivot returns \ref HIPSPARSE_STATUS_ZERO_PIVOT if either a * structural or numerical zero has been found during \ref hipsparseSbsric02_analysis * "hipsparseXbsric02_analysis()" or \ref hipsparseSbsric02 "hipsparseXbsric02()" computation. * The first zero pivot \f$j\f$ at \f$A_{j,j}\f$ is stored in \p position, using the same index * base as the BSR matrix. * * \p position can be in host or device memory. If no zero pivot has been found, * \p position is set to -1 and \ref HIPSPARSE_STATUS_SUCCESS is returned instead. * * \note * If a zero pivot is found, \p position=j means that either the diagonal block \p A(j,j) * is missing (structural zero) or the diagonal block \p A(j,j) is not positive definite * (numerical zero). * * \note \p hipsparseXbsric02_zeroPivot is a blocking function. It might negatively influence * performance. * * \deprecated * This function is deprecated when using the CUDA backend (CUDA 12.0+) and will be * removed in CUDA 13.0. This deprecation does not apply to the ROCm backend. * * @param[in] * handle handle to the hipSPARSE library context queue. * @param[in] * info structure that holds the information collected during the analysis step. * @param[inout] * position pointer to zero pivot \f$j\f$, which can be in host or device memory. * * \retval HIPSPARSE_STATUS_SUCCESS the operation completed successfully. * \retval HIPSPARSE_STATUS_NOT_INITIALIZED \p handle is not initialized. * \retval HIPSPARSE_STATUS_INVALID_VALUE \p handle, \p info, or \p position is nullptr. * \retval HIPSPARSE_STATUS_INTERNAL_ERROR an internal error occurred. * \retval HIPSPARSE_STATUS_ZERO_PIVOT zero pivot has been found. */ DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseXbsric02_zeroPivot(hipsparseHandle_t handle, bsric02Info_t info, int* position); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 13000) /*! \ingroup precond_module * \details * \p hipsparseXbsric02_bufferSize returns the size of the temporary storage buffer * in bytes that is required by \ref hipsparseSbsric02_analysis "hipsparseXbsric02_analysis()" * and \ref hipsparseSbsric02 "hipsparseXbsric02()". The temporary storage buffer must be * allocated by the user. * * @param[in] * handle handle to the hipSPARSE library context queue. * @param[in] * dirA direction that specifies whether to count non-zero elements by \ref HIPSPARSE_DIRECTION_ROW * or by \ref HIPSPARSE_DIRECTION_COLUMN. * @param[in] * mb number of block rows in the sparse BSR matrix. Must be non-negative. * @param[in] * nnzb number of non-zero block entries of the sparse BSR matrix. Must be non-negative. * @param[in] * descrA descriptor of the sparse BSR matrix. * @param[in] * bsrValA array of length \p nnzb*blockDim*blockDim containing the values of the sparse BSR matrix. * @param[in] * bsrRowPtrA array of \p mb+1 elements that point to the start of every block row of the * sparse BSR matrix. * @param[in] * bsrColIndA array of \p nnzb elements containing the block column indices of the sparse BSR matrix. * @param[in] * blockDim the block dimension of the BSR matrix. Must be positive, which is between 1 and m where \p m=mb*blockDim. * @param[out] * info structure that holds the information collected during the analysis step. * @param[out] * pBufferSizeInBytes number of bytes of the temporary storage buffer required by * hipsparseSbsric02_analysis(), hipsparseDbsric02_analysis(), * hipsparseCbsric02_analysis(), hipsparseZbsric02_analysis(), * hipsparseSbsric02(), hipsparseDbsric02(), hipsparseCbsric02(), * and hipsparseZbsric02(). * * \retval HIPSPARSE_STATUS_SUCCESS the operation completed successfully. * \retval HIPSPARSE_STATUS_NOT_INITIALIZED \p handle is not initialized. * \retval HIPSPARSE_STATUS_INVALID_VALUE \p handle, \p descrA, \p bsrValA, \p bsrRowPtrA, * \p bsrColIndA, \p info, or \p pBufferSizeInBytes is nullptr, \p mb, or \p nnzb is negative, * or \p blockDim is invalid. * \retval HIPSPARSE_STATUS_INTERNAL_ERROR an internal error occurred. * \retval HIPSPARSE_STATUS_NOT_SUPPORTED \ref hipsparseMatrixType_t != \ref HIPSPARSE_MATRIX_TYPE_GENERAL. */ /**@{*/ DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseSbsric02_bufferSize(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nnzb, const hipsparseMatDescr_t descrA, float* bsrValA, const int* bsrRowPtrA, const int* bsrColIndA, int blockDim, bsric02Info_t info, int* pBufferSizeInBytes); DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDbsric02_bufferSize(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nnzb, const hipsparseMatDescr_t descrA, double* bsrValA, const int* bsrRowPtrA, const int* bsrColIndA, int blockDim, bsric02Info_t info, int* pBufferSizeInBytes); DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCbsric02_bufferSize(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nnzb, const hipsparseMatDescr_t descrA, hipComplex* bsrValA, const int* bsrRowPtrA, const int* bsrColIndA, int blockDim, bsric02Info_t info, int* pBufferSizeInBytes); DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseZbsric02_bufferSize(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nnzb, const hipsparseMatDescr_t descrA, hipDoubleComplex* bsrValA, const int* bsrRowPtrA, const int* bsrColIndA, int blockDim, bsric02Info_t info, int* pBufferSizeInBytes); /**@}*/ #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 13000) /*! \ingroup precond_module * \details * \p hipsparseXbsric02_analysis performs the analysis step for \ref hipsparseSbsric02 * "hipsparseXbsric02()". It is expected that this function will be executed only once * for a given matrix and particular operation type. * * \note * If the matrix sparsity pattern changes, the gathered information will become invalid. * * \note * This function is non-blocking and executed asynchronously with respect to the host. * It can return before the actual computation has finished. * * @param[in] * handle handle to the hipSPARSE library context queue. * @param[in] * dirA direction that specifies whether to count non-zero elements by \ref HIPSPARSE_DIRECTION_ROW or by * \ref HIPSPARSE_DIRECTION_COLUMN. * @param[in] * mb number of block rows in the sparse BSR matrix. * @param[in] * nnzb number of non-zero block entries of the sparse BSR matrix. * @param[in] * descrA descriptor of the sparse BSR matrix. * @param[in] * bsrValA array of length \p nnzb*blockDim*blockDim containing the values of the sparse BSR matrix. * @param[in] * bsrRowPtrA array of \p mb+1 elements that point to the start of every block row of the * sparse BSR matrix. * @param[in] * bsrColIndA array of \p nnzb elements containing the block column indices of the sparse BSR matrix. * @param[in] * blockDim the block dimension of the BSR matrix, which is between 1 and m where \p m=mb*blockDim. * @param[out] * info structure that holds the information collected during the analysis step. * @param[in] * policy \ref HIPSPARSE_SOLVE_POLICY_NO_LEVEL or \ref HIPSPARSE_SOLVE_POLICY_USE_LEVEL. * @param[in] * pBuffer temporary storage buffer allocated by the user. * * \retval HIPSPARSE_STATUS_SUCCESS the operation completed successfully. * \retval HIPSPARSE_STATUS_INVALID_VALUE \p handle, \p mb, \p nnzb, \p blockDim, \p descrA, * \p bsrValA, \p bsrRowPtrA, \p bsrColIndA, \p info, or \p pBuffer pointer is invalid. * \retval HIPSPARSE_STATUS_INTERNAL_ERROR an internal error occurred. * \retval HIPSPARSE_STATUS_NOT_SUPPORTED * \ref hipsparseMatrixType_t != \ref HIPSPARSE_MATRIX_TYPE_GENERAL. */ /**@{*/ DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseSbsric02_analysis(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nnzb, const hipsparseMatDescr_t descrA, const float* bsrValA, const int* bsrRowPtrA, const int* bsrColIndA, int blockDim, bsric02Info_t info, hipsparseSolvePolicy_t policy, void* pBuffer); DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDbsric02_analysis(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nnzb, const hipsparseMatDescr_t descrA, const double* bsrValA, const int* bsrRowPtrA, const int* bsrColIndA, int blockDim, bsric02Info_t info, hipsparseSolvePolicy_t policy, void* pBuffer); DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCbsric02_analysis(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nnzb, const hipsparseMatDescr_t descrA, const hipComplex* bsrValA, const int* bsrRowPtrA, const int* bsrColIndA, int blockDim, bsric02Info_t info, hipsparseSolvePolicy_t policy, void* pBuffer); DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseZbsric02_analysis(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nnzb, const hipsparseMatDescr_t descrA, const hipDoubleComplex* bsrValA, const int* bsrRowPtrA, const int* bsrColIndA, int blockDim, bsric02Info_t info, hipsparseSolvePolicy_t policy, void* pBuffer); /**@}*/ #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 13000) /*! \ingroup precond_module * \brief Incomplete Cholesky factorization with 0 fill-ins and no pivoting using the BSR * storage format. * * \details * \p hipsparseXbsric02 computes the incomplete Cholesky factorization with 0 fill-ins * and no pivoting of a sparse \f$mb \times mb\f$ BSR matrix \f$A\f$, such that * \f[ * A \approx LL^T * \f] * * Computing the above incomplete Cholesky factorization requires three steps to complete. First, * the user determines the size of the required temporary storage buffer by calling * \ref hipsparseSbsric02_bufferSize "hipsparseXbsric02_bufferSize()". After this buffer size has been determined, * the user allocates the buffer and passes it to \ref hipsparseSbsric02_analysis "hipsparseXbsric02_analysis()". * This will perform analysis on the sparsity pattern of the matrix. Finally, the user calls \p hipsparseXbsric02 * to perform the actual factorization. The calculation of the buffer size and the analysis of the sparse matrix * only need to be performed once for a given sparsity pattern, while the factorization can be repeatedly applied * to multiple matrices having the same sparsity pattern. After all calls to \p hipsparseXbsric02 are complete, * the temporary buffer can be deallocated. * * \p hipsparseXbsric02 requires a user-allocated temporary buffer. Its size is returned * by \ref hipsparseSbsric02_bufferSize "hipsparseXbsric02_bufferSize()". Furthermore, * analysis meta data is required. It can be obtained by \ref hipsparseSbsric02_analysis * "hipsparseXbsric02_analysis()". \p hipsparseXbsric02 reports the first zero pivot * (either numerical or structural zero). The zero pivot status can be obtained by calling * \ref hipsparseXbsric02_zeroPivot(). * * \p hipsparseXbsric02 reports the first zero pivot (either numerical or structural zero). * The zero pivot status can be obtained by calling \ref hipsparseXbsric02_zeroPivot(). * * \note * This function is non-blocking and executed asynchronously with respect to the host. * It can return before the actual computation has finished. * * @param[in] * handle handle to the hipSPARSE library context queue. * @param[in] * dirA direction that specifies whether to count non-zero elements by \ref HIPSPARSE_DIRECTION_ROW or by * \ref HIPSPARSE_DIRECTION_COLUMN. * @param[in] * mb number of block rows in the sparse BSR matrix. * @param[in] * nnzb number of non-zero block entries of the sparse BSR matrix. * @param[in] * descrA descriptor of the sparse BSR matrix. * @param[inout] * bsrValA array of length \p nnzb*blockDim*blockDim containing the values of the sparse BSR matrix. * @param[in] * bsrRowPtrA array of \p mb+1 elements that point to the start of every block row of the * sparse BSR matrix. * @param[in] * bsrColIndA array of \p nnzb elements containing the block column indices of the sparse BSR matrix. * @param[in] * blockDim the block dimension of the BSR matrix, which is between 1 and m where \p m=mb*blockDim. * @param[in] * info structure that holds the information collected during the analysis step. * @param[in] * policy \ref HIPSPARSE_SOLVE_POLICY_NO_LEVEL or \ref HIPSPARSE_SOLVE_POLICY_USE_LEVEL. * @param[in] * pBuffer temporary storage buffer allocated by the user. * * \retval HIPSPARSE_STATUS_SUCCESS the operation completed successfully. * \retval HIPSPARSE_STATUS_INVALID_VALUE \p handle, \p mb, \p nnzb, \p blockDim, \p descrA, * \p bsrValA, \p bsrRowPtrA, or \p bsrColIndA pointer is invalid. * \retval HIPSPARSE_STATUS_ARCH_MISMATCH the device is not supported. * \retval HIPSPARSE_STATUS_INTERNAL_ERROR an internal error occurred. * \retval HIPSPARSE_STATUS_NOT_SUPPORTED * \ref hipsparseMatrixType_t != \ref HIPSPARSE_MATRIX_TYPE_GENERAL. */ /**@{*/ DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseSbsric02(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nnzb, const hipsparseMatDescr_t descrA, float* bsrValA, const int* bsrRowPtrA, const int* bsrColIndA, int blockDim, bsric02Info_t info, hipsparseSolvePolicy_t policy, void* pBuffer); DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDbsric02(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nnzb, const hipsparseMatDescr_t descrA, double* bsrValA, const int* bsrRowPtrA, const int* bsrColIndA, int blockDim, bsric02Info_t info, hipsparseSolvePolicy_t policy, void* pBuffer); DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCbsric02(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nnzb, const hipsparseMatDescr_t descrA, hipComplex* bsrValA, const int* bsrRowPtrA, const int* bsrColIndA, int blockDim, bsric02Info_t info, hipsparseSolvePolicy_t policy, void* pBuffer); DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseZbsric02(hipsparseHandle_t handle, hipsparseDirection_t dirA, int mb, int nnzb, const hipsparseMatDescr_t descrA, hipDoubleComplex* bsrValA, const int* bsrRowPtrA, const int* bsrColIndA, int blockDim, bsric02Info_t info, hipsparseSolvePolicy_t policy, void* pBuffer); /**@}*/ #endif #ifdef __cplusplus } #endif #endif /* HIPSPARSE_BSRIC0_H */