/*! \file */ /* ************************************************************************ * Copyright (C) 2025-2026 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_AUXILIARY_H #define HIPSPARSE_AUXILIARY_H #ifdef __cplusplus extern "C" { #endif /*! \ingroup aux_module * \brief Create a hipSPARSE handle. * * \details * \p hipsparseCreate creates the hipSPARSE library context. It must be * initialized before any other hipSPARSE API function is invoked and must be passed to * all subsequent library function calls. The handle should be destroyed at the end * using hipsparseDestroy(). */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreate(hipsparseHandle_t* handle); /*! \ingroup aux_module * \brief Destroy a hipSPARSE handle. * * \details * \p hipsparseDestroy destroys the hipSPARSE library context and releases all * resources used by the hipSPARSE library. */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroy(hipsparseHandle_t handle); #if(!defined(CUDART_VERSION) || CUDART_VERSION > 10000) /*! \ingroup aux_module * \brief Return the string representation of a hipSPARSE status's matching backend status enum name * * \details * \p hipsparseGetErrorName takes a hipSPARSE status as input and first converts it to the matching backend * status (either \p rocsparse_status or \p cusparseStatus_t). It then returns the string representation of this status * enum name. If the status is not recognized, the function returns "Unrecognized status code". * * For example, \p hipsparseGetErrorName( \ref HIPSPARSE_STATUS_SUCCESS) on a system with a rocSPARSE backend will * return \p rocsparse_status_success. On a system with a cuSPARSE backend this function would return * \p CUSPARSE_STATUS_SUCCESS. */ HIPSPARSE_EXPORT const char* hipsparseGetErrorName(hipsparseStatus_t status); /*! \ingroup aux_module * \brief Return the hipSPARSE status's matching backend status description as a string * * \details * \p hipsparseGetErrorString takes a hipSPARSE status as input and first converts it to the matching backend * status (either \p rocsparse_status or \p cusparseStatus_t). It then returns the string description of this status. * If the status is not recognized, the function returns "Unrecognized status code". */ HIPSPARSE_EXPORT const char* hipsparseGetErrorString(hipsparseStatus_t status); #endif /*! \ingroup aux_module * \brief Get the hipSPARSE version. * * \details * \p hipsparseGetVersion gets the hipSPARSE library version number. * - patch = version % 100 * - minor = version / 100 % 1000 * - major = version / 100000 */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseGetVersion(hipsparseHandle_t handle, int* version); /*! \ingroup aux_module * \brief Get the hipSPARSE git revision. * * \details * \p hipsparseGetGitRevision gets the hipSPARSE library git commit revision (SHA-1). */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseGetGitRevision(hipsparseHandle_t handle, char* rev); /*! \ingroup aux_module * \brief Specify the user-defined HIP stream. * * \details * \p hipsparseSetStream specifies the stream to be used by the hipSPARSE library * context and all subsequent function calls. */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseSetStream(hipsparseHandle_t handle, hipStream_t streamId); /*! \ingroup aux_module * \brief Get the current stream from the library context. * * \details * \p hipsparseGetStream gets the hipSPARSE library context stream which is currently * used for all subsequent function calls. */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseGetStream(hipsparseHandle_t handle, hipStream_t* streamId); /*! \ingroup aux_module * \brief Specify the pointer mode. * * \details * \p hipsparseSetPointerMode specifies the pointer mode to be used by the hipSPARSE * library context and all subsequent function calls. By default, all values are passed * by reference on the host. Valid pointer modes are \ref HIPSPARSE_POINTER_MODE_HOST * or \ref HIPSPARSE_POINTER_MODE_DEVICE. */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseSetPointerMode(hipsparseHandle_t handle, hipsparsePointerMode_t mode); /*! \ingroup aux_module * \brief Get the current pointer mode from the library context. * * \details * \p hipsparseGetPointerMode gets the hipSPARSE library context pointer mode which * is currently used for all subsequent function calls. */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseGetPointerMode(hipsparseHandle_t handle, hipsparsePointerMode_t* mode); /*! \ingroup aux_module * \brief Create a matrix descriptor. * \details * \p hipsparseCreateMatDescr creates a matrix descriptor. It initializes * \ref hipsparseMatrixType_t to \ref HIPSPARSE_MATRIX_TYPE_GENERAL and * \ref hipsparseIndexBase_t to \ref HIPSPARSE_INDEX_BASE_ZERO. It should be destroyed * at the end using hipsparseDestroyMatDescr(). */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreateMatDescr(hipsparseMatDescr_t* descrA); /*! \ingroup aux_module * \brief Destroy a matrix descriptor. * * \details * \p hipsparseDestroyMatDescr destroys a matrix descriptor and releases all * resources used by the descriptor. */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroyMatDescr(hipsparseMatDescr_t descrA); /*! \ingroup aux_module * \brief Copy a matrix descriptor. * \details * \p hipsparseCopyMatDescr copies a matrix descriptor. Both source and destination * matrix descriptors must be initialized prior to calling \p hipsparseCopyMatDescr. */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCopyMatDescr(hipsparseMatDescr_t dest, const hipsparseMatDescr_t src); /*! \ingroup aux_module * \brief Specify the matrix type of a matrix descriptor. * * \details * \p hipsparseSetMatType sets the matrix type of a matrix descriptor. Valid * matrix types are \ref HIPSPARSE_MATRIX_TYPE_GENERAL, * \ref HIPSPARSE_MATRIX_TYPE_SYMMETRIC, \ref HIPSPARSE_MATRIX_TYPE_HERMITIAN, or * \ref HIPSPARSE_MATRIX_TYPE_TRIANGULAR. */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseSetMatType(hipsparseMatDescr_t descrA, hipsparseMatrixType_t type); /*! \ingroup aux_module * \brief Get the matrix type of a matrix descriptor. * * \details * \p hipsparseGetMatType returns the matrix type of a matrix descriptor. */ HIPSPARSE_EXPORT hipsparseMatrixType_t hipsparseGetMatType(const hipsparseMatDescr_t descrA); /*! \ingroup aux_module * \brief Specify the matrix fill mode of a matrix descriptor. * * \details * \p hipsparseSetMatFillMode sets the matrix fill mode of a matrix descriptor. * Valid fill modes are \ref HIPSPARSE_FILL_MODE_LOWER or * \ref HIPSPARSE_FILL_MODE_UPPER. */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseSetMatFillMode(hipsparseMatDescr_t descrA, hipsparseFillMode_t fillMode); /*! \ingroup aux_module * \brief Get the matrix fill mode of a matrix descriptor. * * \details * \p hipsparseGetMatFillMode returns the matrix fill mode of a matrix descriptor. */ HIPSPARSE_EXPORT hipsparseFillMode_t hipsparseGetMatFillMode(const hipsparseMatDescr_t descrA); /*! \ingroup aux_module * \brief Specify the matrix diagonal type of a matrix descriptor. * * \details * \p hipsparseSetMatDiagType sets the matrix diagonal type of a matrix * descriptor. Valid diagonal types are \ref HIPSPARSE_DIAG_TYPE_UNIT or * \ref HIPSPARSE_DIAG_TYPE_NON_UNIT. */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseSetMatDiagType(hipsparseMatDescr_t descrA, hipsparseDiagType_t diagType); /*! \ingroup aux_module * \brief Get the matrix diagonal type of a matrix descriptor. * * \details * \p hipsparseGetMatDiagType returns the matrix diagonal type of a matrix * descriptor. */ HIPSPARSE_EXPORT hipsparseDiagType_t hipsparseGetMatDiagType(const hipsparseMatDescr_t descrA); /*! \ingroup aux_module * \brief Specify the index base of a matrix descriptor. * * \details * \p hipsparseSetMatIndexBase sets the index base of a matrix descriptor. Valid * options are \ref HIPSPARSE_INDEX_BASE_ZERO or \ref HIPSPARSE_INDEX_BASE_ONE. */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseSetMatIndexBase(hipsparseMatDescr_t descrA, hipsparseIndexBase_t base); /*! \ingroup aux_module * \brief Get the index base of a matrix descriptor. * * \details * \p hipsparseGetMatIndexBase returns the index base of a matrix descriptor. */ HIPSPARSE_EXPORT hipsparseIndexBase_t hipsparseGetMatIndexBase(const hipsparseMatDescr_t descrA); #if(!defined(CUDART_VERSION) || CUDART_VERSION < 11000) /*! \ingroup aux_module * \brief Create a \p HYB matrix structure. * * \details * \p hipsparseCreateHybMat creates a structure that holds the matrix in \p HYB * storage format. It should be destroyed at the end using hipsparseDestroyHybMat(). */ DEPRECATED_CUDA_10000("The routine will be removed in CUDA 11") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreateHybMat(hipsparseHybMat_t* hybA); /*! \ingroup aux_module * \brief Destroy a \p HYB matrix structure. * * \details * \p hipsparseDestroyHybMat destroys a \p HYB structure. */ DEPRECATED_CUDA_10000("The routine will be removed in CUDA 11") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroyHybMat(hipsparseHybMat_t hybA); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 14000) /* Info structures */ /*! \ingroup aux_module * \brief Create a bsrsv2 info structure. * * \details * \p hipsparseCreateBsrsv2Info creates a structure that holds the bsrsv2 info data * that is gathered during the analysis routines. It should be destroyed * at the end using hipsparseDestroyBsrsv2Info(). */ DEPRECATED_CUDA_12000("The routine will be removed in a future CUDA release") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreateBsrsv2Info(bsrsv2Info_t* info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 14000) /*! \ingroup aux_module * \brief Destroy a bsrsv2 info structure. * * \details * \p hipsparseDestroyBsrsv2Info destroys a bsrsv2 info structure. */ DEPRECATED_CUDA_12000("The routine will be removed in a future CUDA release") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroyBsrsv2Info(bsrsv2Info_t info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 14000) /* Info structures */ /*! \ingroup aux_module * \brief Create a bsrsm2 info structure. * * \details * \p hipsparseCreateBsrsm2Info creates a structure that holds the bsrsm2 info data * that is gathered during the analysis routines. It should be destroyed * at the end using hipsparseDestroyBsrsm2Info(). */ DEPRECATED_CUDA_12000("The routine will be removed in a future CUDA release") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreateBsrsm2Info(bsrsm2Info_t* info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 14000) /*! \ingroup aux_module * \brief Destroy a bsrsm2 info structure. * * \details * \p hipsparseDestroyBsrsm2Info destroys a bsrsm2 info structure. */ DEPRECATED_CUDA_12000("The routine will be removed in a future CUDA release") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroyBsrsm2Info(bsrsm2Info_t info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 14000) /* Info structures */ /*! \ingroup aux_module * \brief Create a bsrilu02 info structure. * * \details * \p hipsparseCreateBsrilu02Info creates a structure that holds the bsrilu02 info data * that is gathered during the analysis routines. It should be destroyed * at the end using hipsparseDestroyBsrilu02Info(). */ DEPRECATED_CUDA_12000("The routine will be removed in a future CUDA release") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreateBsrilu02Info(bsrilu02Info_t* info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 14000) /*! \ingroup aux_module * \brief Destroy a bsrilu02 info structure * * \details * \p hipsparseDestroyBsrilu02Info destroys a bsrilu02 info structure. */ DEPRECATED_CUDA_12000("The routine will be removed in a future CUDA release") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroyBsrilu02Info(bsrilu02Info_t info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 14000) /* Info structures */ /*! \ingroup aux_module * \brief Create a bsric02 info structure. * * \details * \p hipsparseCreateBsric02Info creates a structure that holds the bsric02 info data * that is gathered during the analysis routines. It should be destroyed * at the end using hipsparseDestroyBsric02Info(). */ DEPRECATED_CUDA_12000("The routine will be removed in a future CUDA release") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreateBsric02Info(bsric02Info_t* info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 14000) /*! \ingroup aux_module * \brief Destroy a bsric02 info structure. * * \details * \p hipsparseDestroyBsric02Info destroys a bsric02 info structure. */ DEPRECATED_CUDA_12000("The routine will be removed in a future CUDA release") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroyBsric02Info(bsric02Info_t info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 12000) /* Info structures */ /*! \ingroup aux_module * \brief Create a csrsv2 info structure. * * \details * \p hipsparseCreateCsrsv2Info creates a structure that holds the csrsv2 info data * that is gathered during the analysis routines. It should be destroyed * at the end using hipsparseDestroyCsrsv2Info(). */ DEPRECATED_CUDA_11000("The routine will be removed in CUDA 12") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreateCsrsv2Info(csrsv2Info_t* info); /*! \ingroup aux_module * \brief Destroy a csrsv2 info structure. * * \details * \p hipsparseDestroyCsrsv2Info destroys a csrsv2 info structure. */ DEPRECATED_CUDA_11000("The routine will be removed in CUDA 12") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroyCsrsv2Info(csrsv2Info_t info); /* Info structures */ /*! \ingroup aux_module * \brief Create a csrsm2 info structure. * * \details * \p hipsparseCreateCsrsm2Info creates a structure that holds the csrsm2 info data * that is gathered during the analysis routines. It should be destroyed * at the end using hipsparseDestroyCsrsm2Info(). */ DEPRECATED_CUDA_11000("The routine will be removed in CUDA 12") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreateCsrsm2Info(csrsm2Info_t* info); /*! \ingroup aux_module * \brief Destroy a csrsm2 info structure. * * \details * \p hipsparseDestroyCsrsm2Info destroys a csrsm2 info structure. */ DEPRECATED_CUDA_11000("The routine will be removed in CUDA 12") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroyCsrsm2Info(csrsm2Info_t info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 14000) /* Info structures */ /*! \ingroup aux_module * \brief Create a csrilu02 info structure. * * \details * \p hipsparseCreateCsrilu02Info creates a structure that holds the csrilu02 info data * that is gathered during the analysis routines. It should be destroyed * at the end using hipsparseDestroyCsrilu02Info(). */ DEPRECATED_CUDA_12000("The routine will be removed in a future CUDA release") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreateCsrilu02Info(csrilu02Info_t* info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 14000) /*! \ingroup aux_module * \brief Destroy a csrilu02 info structure. * * \details * \p hipsparseDestroyCsrilu02Info destroys a csrilu02 info structure. */ DEPRECATED_CUDA_12000("The routine will be removed in a future CUDA release") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroyCsrilu02Info(csrilu02Info_t info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 14000) /* Info structures */ /*! \ingroup aux_module * \brief Create a csric02 info structure. * * \details * \p hipsparseCreateCsric02Info creates a structure that holds the csric02 info data * that is gathered during the analysis routines. It should be destroyed * at the end using hipsparseDestroyCsric02Info(). */ DEPRECATED_CUDA_12000("The routine will be removed in a future CUDA release") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreateCsric02Info(csric02Info_t* info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 14000) /*! \ingroup aux_module * \brief Destroy a csric02 info structure. * * \details * \p hipsparseDestroyCsric02Info destroys a csric02 info structure. */ DEPRECATED_CUDA_12000("The routine will be removed in a future CUDA release") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroyCsric02Info(csric02Info_t info); #endif /* Info structures */ /*! \ingroup aux_module * \brief Create a csru2csr info structure. * * \details * \p hipsparseCreateCsru2csrInfo creates a structure that holds the csru2csr info data * that is gathered during the analysis routines. It should be destroyed * at the end using hipsparseDestroyCsru2csrInfo(). */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreateCsru2csrInfo(csru2csrInfo_t* info); /*! \ingroup aux_module * \brief Destroy a csru2csr info structure. * * \details * \p hipsparseDestroyCsru2csrInfo destroys a csru2csr info structure. */ HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroyCsru2csrInfo(csru2csrInfo_t info); #if(!defined(CUDART_VERSION) || CUDART_VERSION < 13000) /* Info structures */ /*! \ingroup aux_module * \brief Create a color info structure. * * \details * \p hipsparseCreateColorInfo creates a structure that holds the color info data * that is gathered during the analysis routines. It should be destroyed * at the end using hipsparseDestroyColorInfo(). */ DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreateColorInfo(hipsparseColorInfo_t* info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 13000) /*! \ingroup aux_module * \brief Destroy a color info structure. * * \details * \p hipsparseDestroyColorInfo destroys a color info structure. */ DEPRECATED_CUDA_12000("The routine will be removed in CUDA 13") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroyColorInfo(hipsparseColorInfo_t info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 12000) /* Info structures */ /*! \ingroup aux_module * \brief Create a csrgemm2 info structure. * * \details * \p hipsparseCreateCsrgemm2Info creates a structure that holds the csrgemm2 info data * that is gathered during the analysis routines. It should be destroyed * at the end using hipsparseDestroyCsrgemm2Info(). */ DEPRECATED_CUDA_11000("The routine will be removed in CUDA 12") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreateCsrgemm2Info(csrgemm2Info_t* info); /*! \ingroup aux_module * \brief Destroy a csrgemm2 info structure. * * \details * \p hipsparseDestroyCsrgemm2Info destroys a csrgemm2 info structure. */ DEPRECATED_CUDA_11000("The routine will be removed in CUDA 12") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroyCsrgemm2Info(csrgemm2Info_t info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 14000) /* Info structures */ /*! \ingroup aux_module * \brief Create a prune info structure. * * \details * \p hipsparseCreatePruneInfo creates a structure that holds the prune info data * that is gathered during the analysis routines. It should be destroyed * at the end using hipsparseDestroyPruneInfo(). */ DEPRECATED_CUDA_12000("The routine will be removed in a future CUDA release") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseCreatePruneInfo(pruneInfo_t* info); #endif #if(!defined(CUDART_VERSION) || CUDART_VERSION < 14000) /*! \ingroup aux_module * \brief Destroy a prune info structure * * \details * \p hipsparseDestroyPruneInfo destroys a prune info structure. */ DEPRECATED_CUDA_12000("The routine will be removed in a future CUDA release") HIPSPARSE_EXPORT hipsparseStatus_t hipsparseDestroyPruneInfo(pruneInfo_t info); #endif #ifdef __cplusplus } #endif #endif /* HIPSPARSE_AUXILIARY_H */