/home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-hipsparselt/checkouts/latest/projects/hipsparselt/library/include/hipsparselt.h Source File

/home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-hipsparselt/checkouts/latest/projects/hipsparselt/library/include/hipsparselt.h Source File#

hipSPARSELt: /home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-hipsparselt/checkouts/latest/projects/hipsparselt/library/include/hipsparselt.h Source File
Go to the documentation of this file.
 /*******************************************************************************
  *
  * MIT License
  *
  * Copyright (c) 2022-2026 Advanced Micro Devices, Inc.
  *
  * 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.
  *
  *******************************************************************************/
  
 //
  
 #pragma once
 #ifndef _HIPSPARSELT_H_
 #define _HIPSPARSELT_H_
  
 #include <hipsparse/hipsparse.h>
 #include <hipsparselt/hipsparselt-export.h>
 #include <hipsparselt/hipsparselt-version.h>
  
 #include <hip/hip_complex.h>
 #include <hip/hip_runtime_api.h>
  
 #if defined(__HIP_PLATFORM_AMD__)
 #include <hip/hip_bfloat16.h>
 #include <hip/hip_fp16.h>
 #include <hip/hip_fp8.h>
 #include <hip/library_types.h>
 #else
 #include <cuda_bf16.h>
 #include <cuda_fp16.h>
 #include <cuda_fp8.h>
 #include <library_types.h>
 #endif
  
 /* Opaque structures holding information */
 // clang-format off
  
 // Zero-initialize opaque struct data in C++ (= {} is a C++11 feature, invalid in C).
 // Guarantees is_init=0 on every declaration, eliminating uninitialized-struct false positives.
 #ifdef __cplusplus
 #  define HIPSPARSELT_STRUCT_ZERO_INIT = {}
 #else
 #  define HIPSPARSELT_STRUCT_ZERO_INIT
 #endif
  
 #if defined(__HIP_PLATFORM_AMD__)
 typedef struct hipsparseLtHandle_t           { alignas(16) uint8_t data[512] HIPSPARSELT_STRUCT_ZERO_INIT; } hipsparseLtHandle_t;
  
 typedef struct hipsparseLtMatDescriptor_t    { alignas(16) uint8_t data[512] HIPSPARSELT_STRUCT_ZERO_INIT; } hipsparseLtMatDescriptor_t;
  
 typedef struct hipsparseLtMatmulDescriptor_t { alignas(16) uint8_t data[512] HIPSPARSELT_STRUCT_ZERO_INIT; } hipsparseLtMatmulDescriptor_t;
  
 typedef struct hipsparseLtMatmulAlgSelection_t { alignas(16) uint8_t data[512] HIPSPARSELT_STRUCT_ZERO_INIT; } hipsparseLtMatmulAlgSelection_t;
  
 typedef struct hipsparseLtMatmulPlan_t       { alignas(16) uint8_t data[512] HIPSPARSELT_STRUCT_ZERO_INIT; } hipsparseLtMatmulPlan_t;
 #elif defined(__HIP_PLATFORM_NVIDIA__)
 typedef __nv_bfloat16 hip_bfloat16;
 typedef struct { alignas(16) uint8_t data[512]; } hipsparseLtHandle_t;
 typedef struct { alignas(16) uint8_t data[512]; } hipsparseLtMatDescriptor_t;
 typedef struct { alignas(16) uint8_t data[512]; } hipsparseLtMatmulDescriptor_t;
 typedef struct { alignas(16) uint8_t data[512]; } hipsparseLtMatmulAlgSelection_t;
 typedef struct { alignas(16) uint8_t data[512]; } hipsparseLtMatmulPlan_t;
 #endif
  
 typedef enum {
    HIPSPARSELT_SPARSITY_50_PERCENT 
 } hipsparseLtSparsity_t;
  
 typedef enum {
    HIPSPARSELT_MAT_NUM_BATCHES,     
    HIPSPARSELT_MAT_BATCH_STRIDE,    
 } hipsparseLtMatDescAttribute_t;
  
 typedef enum {
    HIPSPARSELT_COMPUTE_16F = 0,     
    HIPSPARSELT_COMPUTE_32I,         
    HIPSPARSELT_COMPUTE_32F,         
    HIPSPARSELT_COMPUTE_TF32,        
    HIPSPARSELT_COMPUTE_TF32_FAST    
 } hipsparseLtComputetype_t;
  
 typedef enum {
    HIPSPARSELT_MATMUL_ACTIVATION_RELU = 0,             
    HIPSPARSELT_MATMUL_ACTIVATION_RELU_UPPERBOUND = 1,  
    HIPSPARSELT_MATMUL_ACTIVATION_RELU_THRESHOLD = 2,   
    HIPSPARSELT_MATMUL_ACTIVATION_GELU = 3,             
    HIPSPARSELT_MATMUL_ACTIVATION_GELU_SCALING = 4,     
    HIPSPARSELT_MATMUL_ALPHA_VECTOR_SCALING = 5,        
    HIPSPARSELT_MATMUL_BETA_VECTOR_SCALING = 6,         
    HIPSPARSELT_MATMUL_BIAS_STRIDE = 7,                 
    HIPSPARSELT_MATMUL_BIAS_POINTER = 8,                
    HIPSPARSELT_MATMUL_ACTIVATION_ABS = 9,              
    HIPSPARSELT_MATMUL_ACTIVATION_LEAKYRELU = 10,       
    HIPSPARSELT_MATMUL_ACTIVATION_LEAKYRELU_ALPHA = 11, 
    HIPSPARSELT_MATMUL_ACTIVATION_SIGMOID = 12,         
    HIPSPARSELT_MATMUL_ACTIVATION_TANH = 13,            
    HIPSPARSELT_MATMUL_ACTIVATION_TANH_ALPHA = 14,      
    HIPSPARSELT_MATMUL_ACTIVATION_TANH_BETA = 15,       
    HIPSPARSELT_MATMUL_BIAS_TYPE = 16,                  
    HIPSPARSELT_MATMUL_SPARSE_MAT_POINTER = 17,         
    HIPSPARSELT_MATMUL_GATE_RESIDUAL_MAT_POINTER = 18,  
    HIPSPARSELT_MATMUL_GATE_RESIDUAL_DESC = 19,         
 } hipsparseLtMatmulDescAttribute_t;
  
 typedef enum {
    HIPSPARSELT_MATMUL_ALG_DEFAULT
 } hipsparseLtMatmulAlg_t;
  
 typedef enum {
    HIPSPARSELT_MATMUL_ALG_CONFIG_ID = 0,     // READ/WRITE
    HIPSPARSELT_MATMUL_ALG_CONFIG_MAX_ID = 1, // READ-ONLY
    HIPSPARSELT_MATMUL_SEARCH_ITERATIONS = 2,  // READ/WRITE
    HIPSPARSELT_MATMUL_SPLIT_K = 3,
    HIPSPARSELT_MATMUL_SPLIT_K_MODE = 4,
    HIPSPARSELT_MATMUL_SPLIT_K_BUFFERS = 5,
 } hipsparseLtMatmulAlgAttribute_t;
  
 typedef enum {
    HIPSPARSELT_PRUNE_SPMMA_TILE  = 0, 
    HIPSPARSELT_PRUNE_SPMMA_STRIP = 1, 
 } hipsparseLtPruneAlg_t;
  
 typedef enum {
    HIPSPARSELT_SPLIT_K_MODE_ONE_KERNEL = 0,  
    HIPSPARSELT_SPLIT_K_MODE_TWO_KERNELS = 1, 
 } hipsparseLtSplitKMode_t;
  
 // clang-format on
  
 #ifdef __cplusplus
 extern "C" {
 #endif
  
 HIPSPARSELT_EXPORT
 void hipsparseLtInitialize();
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtGetVersion(const hipsparseLtHandle_t* handle, int* version);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtGetProperty(hipLibraryPropertyType propertyType, int* value);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtGetGitRevision(hipsparseLtHandle_t handle, char* rev);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtGetArchName(char** archName);
  
 /* hipSPARSE initialization and management routines */
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtInit(hipsparseLtHandle_t* handle);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtDestroy(const hipsparseLtHandle_t* handle);
  
 /* matrix descriptor */
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtDenseDescriptorInit(const hipsparseLtHandle_t*  handle,
                                                  hipsparseLtMatDescriptor_t* matDescr,
                                                  int64_t                     rows,
                                                  int64_t                     cols,
                                                  int64_t                     ld,
                                                  uint32_t                    alignment,
                                                  hipDataType                 valueType,
                                                  hipsparseOrder_t            order);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtStructuredDescriptorInit(const hipsparseLtHandle_t*  handle,
                                                       hipsparseLtMatDescriptor_t* matDescr,
                                                       int64_t                     rows,
                                                       int64_t                     cols,
                                                       int64_t                     ld,
                                                       uint32_t                    alignment,
                                                       hipDataType                 valueType,
                                                       hipsparseOrder_t            order,
                                                       hipsparseLtSparsity_t       sparsity);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtMatDescriptorDestroy(const hipsparseLtMatDescriptor_t* matDescr);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtMatDescSetAttribute(const hipsparseLtHandle_t*    handle,
                                                  hipsparseLtMatDescriptor_t*   matDescr,
                                                  hipsparseLtMatDescAttribute_t matAttribute,
                                                  const void*                   data,
                                                  size_t                        dataSize);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtMatDescGetAttribute(const hipsparseLtHandle_t*        handle,
                                                  const hipsparseLtMatDescriptor_t* matDescr,
                                                  hipsparseLtMatDescAttribute_t     matAttribute,
                                                  void*                             data,
                                                  size_t                            dataSize);
  
 /* matmul descriptor */
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtMatmulDescriptorInit(const hipsparseLtHandle_t*        handle,
                                                   hipsparseLtMatmulDescriptor_t*    matmulDescr,
                                                   hipsparseOperation_t              opA,
                                                   hipsparseOperation_t              opB,
                                                   const hipsparseLtMatDescriptor_t* matA,
                                                   const hipsparseLtMatDescriptor_t* matB,
                                                   const hipsparseLtMatDescriptor_t* matC,
                                                   const hipsparseLtMatDescriptor_t* matD,
                                                   hipsparseLtComputetype_t          computeType);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t
     hipsparseLtMatmulDescSetAttribute(const hipsparseLtHandle_t*       handle,
                                       hipsparseLtMatmulDescriptor_t*   matmulDescr,
                                       hipsparseLtMatmulDescAttribute_t matmulAttribute,
                                       const void*                      data,
                                       size_t                           dataSize);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t
     hipsparseLtMatmulDescGetAttribute(const hipsparseLtHandle_t*           handle,
                                       const hipsparseLtMatmulDescriptor_t* matmulDescr,
                                       hipsparseLtMatmulDescAttribute_t     matmulAttribute,
                                       void*                                data,
                                       size_t                               dataSize);
  
 /* algorithm selection */
 HIPSPARSELT_EXPORT
 hipsparseStatus_t
     hipsparseLtMatmulAlgSelectionInit(const hipsparseLtHandle_t*           handle,
                                       hipsparseLtMatmulAlgSelection_t*     algSelection,
                                       const hipsparseLtMatmulDescriptor_t* matmulDescr,
                                       hipsparseLtMatmulAlg_t               alg);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t
     hipsparseLtMatmulAlgSelectionDestroy(const hipsparseLtMatmulAlgSelection_t* algSelection);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtMatmulAlgSetAttribute(const hipsparseLtHandle_t*       handle,
                                                    hipsparseLtMatmulAlgSelection_t* algSelection,
                                                    hipsparseLtMatmulAlgAttribute_t  attribute,
                                                    const void*                      data,
                                                    size_t                           dataSize);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t
     hipsparseLtMatmulAlgGetAttribute(const hipsparseLtHandle_t*             handle,
                                      const hipsparseLtMatmulAlgSelection_t* algSelection,
                                      hipsparseLtMatmulAlgAttribute_t        attribute,
                                      void*                                  data,
                                      size_t                                 dataSize);
  
 /* matmul plan */
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtMatmulGetWorkspace(const hipsparseLtHandle_t*     handle,
                                                 const hipsparseLtMatmulPlan_t* plan,
                                                 size_t*                        workspaceSize);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtMatmulPlanInit(const hipsparseLtHandle_t*             handle,
                                             hipsparseLtMatmulPlan_t*               plan,
                                             const hipsparseLtMatmulDescriptor_t*   matmulDescr,
                                             const hipsparseLtMatmulAlgSelection_t* algSelection);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtMatmulPlanDestroy(const hipsparseLtMatmulPlan_t* plan);
  
 /* matmul execution */
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtMatmul(const hipsparseLtHandle_t*     handle,
                                     const hipsparseLtMatmulPlan_t* plan,
                                     const void*                    alpha,
                                     const void*                    d_A,
                                     const void*                    d_B,
                                     const void*                    beta,
                                     const void*                    d_C,
                                     void*                          d_D,
                                     void*                          workspace,
                                     hipStream_t*                   streams,
                                     int32_t                        numStreams);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtMatmulSearch(const hipsparseLtHandle_t* handle,
                                           hipsparseLtMatmulPlan_t*   plan,
                                           const void*                alpha,
                                           const void*                d_A,
                                           const void*                d_B,
                                           const void*                beta,
                                           const void*                d_C,
                                           void*                      d_D,
                                           void*                      workspace,
                                           hipStream_t*               streams,
                                           int32_t                    numStreams);
  
 /* helper */
 // prune
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtSpMMAPrune(const hipsparseLtHandle_t*           handle,
                                         const hipsparseLtMatmulDescriptor_t* matmulDescr,
                                         const void*                          d_in,
                                         void*                                d_out,
                                         hipsparseLtPruneAlg_t                pruneAlg,
                                         hipStream_t                          stream);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtSpMMAPruneCheck(const hipsparseLtHandle_t*           handle,
                                              const hipsparseLtMatmulDescriptor_t* matmulDescr,
                                              const void*                          d_in,
                                              int*                                 d_valid,
                                              hipStream_t                          stream);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtSpMMAPrune2(const hipsparseLtHandle_t*        handle,
                                          const hipsparseLtMatDescriptor_t* sparseMatDescr,
                                          int                               isSparseA,
                                          hipsparseOperation_t              op,
                                          const void*                       d_in,
                                          void*                             d_out,
                                          hipsparseLtPruneAlg_t             pruneAlg,
                                          hipStream_t                       stream);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtSpMMAPruneCheck2(const hipsparseLtHandle_t*        handle,
                                               const hipsparseLtMatDescriptor_t* sparseMatDescr,
                                               int                               isSparseA,
                                               hipsparseOperation_t              op,
                                               const void*                       d_in,
                                               int*                              d_valid,
                                               hipStream_t                       stream);
  
 // compression
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtSpMMACompressedSize(const hipsparseLtHandle_t*     handle,
                                                  const hipsparseLtMatmulPlan_t* plan,
                                                  size_t*                        compressedSize,
                                                  size_t*                        compressBufferSize);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtSpMMACompress(const hipsparseLtHandle_t*     handle,
                                            const hipsparseLtMatmulPlan_t* plan,
                                            const void*                    d_dense,
                                            void*                          d_compressed,
                                            void*                          d_compressBuffer,
                                            hipStream_t                    stream);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtSpMMACompressedSize2(const hipsparseLtHandle_t*        handle,
                                                   const hipsparseLtMatDescriptor_t* sparseMatDescr,
                                                   size_t*                           compressedSize,
                                                   size_t* compressBufferSize);
  
 HIPSPARSELT_EXPORT
 hipsparseStatus_t hipsparseLtSpMMACompress2(const hipsparseLtHandle_t*        handle,
                                             const hipsparseLtMatDescriptor_t* sparseMatDescr,
                                             int                               isSparseA,
                                             hipsparseOperation_t              op,
                                             const void*                       d_dense,
                                             void*                             d_compressed,
                                             void*                             d_compressBuffer,
                                             hipStream_t                       stream);
  
 #ifdef __cplusplus
 }
 #endif
  
 #endif // _HIPSPARSELT_H_