【免费下载链接】ops-sparse本项目是CANN提供的高性能稀疏矩阵计算的算子库专注于优化稀疏矩阵的计算效率。项目地址: https://gitcode.com/cann/ops-sparsename: sparse-lib-rules description: ops-sparse 库规范技能定义接口命名、参数约定、描述符规范、错误码规范等。同时支持 Generic API 和 Legacy API 两种体系。ops-sparse 库规范ops-sparse 对齐 cuSPARSE支持两种 API 体系。开发新算子时按照目标 cuSPARSE 接口的归属选择对应规范API 体系适用场景特征Generic APIcuSPARSE Generic API 中的算子SpMV/SpMM/SpGEMM/SDDMM/SpSM 等Descriptor 模式 三阶段执行Legacy APIcuSPARSE Legacy API 中的算子gtsv/gtsv2 三对角、格式转换、排序等尚未迁移到 Generic直传扁平参数 MatDescr 矩阵描述符一、Generic API 规范1.1 命名模式aclsparse{Operation}分类命名模式示例矩阵-向量运算aclsparseSp{MV/SV}aclsparseSpMV矩阵-矩阵运算aclsparseSp{MM/SM/GEMM}aclsparseSpMM描述符管理aclsparseCreate/Destroy{Type}aclsparseCreateCsr资源管理aclsparseCreate/DestroyaclsparseCreateSDDMMaclsparseSDDMMaclsparseSDDMM1.2 前缀规范aclsparse库前缀小写无空格SpMVSparse Matrix-Vector multiplicationSpMMSparse Matrix-Matrix multiplicationSpSVSparse triangular Solve (Vector)SpSMSparse triangular Solve (Matrix)SpGEMMSparse General Matrix-Matrix multiplicationSDDMMSampled Dense-Dense Matrix Multiplication1.3 Generic 描述符规范描述符用途关键字段aclsparseSpMatDescr_t稀疏矩阵format, rows, cols, nnz, ptrs, idxs, values, baseType, ptrType, IdxType, valueTypeaclsparseDnVecDescr_t稠密向量nums, values, valueTypeaclsparseDnMatDescr_t稠密矩阵rows, cols, ld, order, values, valueType生命周期创建aclsparseCreateXxx(descr, ...)— host 侧分配描述符结构体填充字段使用描述符作为 opaque pointer 传入计算函数销毁aclsparseDestroyXxx(descr)— 释放描述符结构体注意 const 转换规范Create 函数参数中的指针类型描述符必须校验 nullptrDestroy 函数必须安全处理 nullptr 输入直接返回 SUCCESSConst 描述符aclsparseConstXxxDescr_t表示只读访问aclsparseConstSpMatDescr_t用于 SpMV/SpMM 等计算函数中的稀疏矩阵输入aclsparseConstDnVecDescr_t用于计算函数中的输入稠密向量非 const 描述符用于输出如 SpMV 的输出向量vecY1.4 Generic 参数顺序aclsparseStatus_t aclsparseXxx( aclsparseHandle_t handle, // 1. Handle aclsparseOperation_t op, // 2. 操作类型转置等 const void *alpha, // 3. 标量 alphaHost 指针 aclsparseConstSpMatDescr_t matA, // 4. 稀疏矩阵描述符 aclsparseConstDnVecDescr_t vecX, // 5. 输入向量 const void *beta, // 6. 标量 beta aclsparseDnVecDescr_t vecY, // 7. 输出向量 aclDataType computeType, // 8. 计算类型 XxxAlg_t alg, // 9. 算法选择 void *buffer // 10. 外部 buffer可选 );标量传递alpha/beta为const void *类型实际数据类型由computeType决定。1.5 Generic 三阶段执行阶段函数作用1. 询问 bufferaclsparseXxxGetBufferSize(...)返回 workspace 所需大小2. 预处理aclsparseXxxPreprocess(...)一次性预处理格式转换/重排写入 buffer3. 执行aclsparseXxx(...)实际计算复用 buffer可多次调用预处理阶段是可选的。如果算子不需要预处理阶段 1 返回 bufferSize0阶段 2 不存在。二、Legacy API 规范2.1 命名模式aclsparse{Type}{Operation}按 cuSPARSE Legacy 命名{Type}表示精度前缀精度前缀数据类型示例SFP32 (float)aclsparseSgtsv2DFP64 (double)aclsparseDgtsv2Ccomplex FP32aclsparseCgtsv2Zcomplex FP64aclsparseZgtsv2HFP16aclsparseSgtsv2_half扩展特殊前缀操作特定而与类型无关前缀用途示例X与类型无关的辅助函数aclsparseXcsrsortcusparse部分管理函数沿用 cuSPARSE 名称aclsparseSetMatType2.2 Legacy 函数分类分类说明示例Level 2稀疏矩阵-向量运算aclsparseSbsrmv已 DEPRECATED由 SpMV 替代Level 3稀疏矩阵-矩阵运算aclsparseSbsrmm已 DEPRECATED由 SpMM 替代Preconditioners预条件子IC/ILUcsric02/csrilu02已 DEPRECATEDTridiagonal Solve三对角求解aclsparseSgtsv2 / aclsparseSgtsv2StridedBatchPentadiagonal Solve五对角求解aclsparseSgpsvInterleavedBatchFormat Conversion格式转换aclsparseSgebsr2gebsc / aclsparseSnnz / aclsparse{t}coo2csr / aclsparse{t}csr2cooReorderings / Sort排序aclsparseXcsrsort / aclsparseXcoosortExtra扩展如 csrgeam2aclsparseScsrgeam22.3 Legacy MatDescr 矩阵描述符Legacy 不使用 SpMatDescr而是使用MatDescr矩阵描述符标注格式属性typedef struct aclsparseMatDescr *aclsparseMatDescr_t; aclsparseStatus_t aclsparseCreateMatDescr(aclsparseMatDescr_t *descr); aclsparseStatus_t aclsparseDestroyMatDescr(aclsparseMatDescr_t descr); void aclsparseSetMatType(aclsparseMatDescr_t descr, aclsparseMatrixType_t type); void aclsparseSetMatIndexBase(aclsparseMatDescr_t descr, aclsparseIndexBase_t base); void aclsparseSetMatDiagType(aclsparseMatDescr_t descr, aclsparseDiagType_t diagType); void aclsparseSetMatFillMode(aclsparseMatDescr_t descr, aclsparseFillMode_t fillMode); aclsparseMatrixType_t aclsparseGetMatType(aclsparseMatDescr_t descr); aclsparseIndexBase_t aclsparseGetMatIndexBase(aclsparseMatDescr_t descr);MatDescr 关键字段字段类型说明typeaclsparseMatrixType_tGENERAL / SYMMETRIC / HERMITIAN / TRIANGULARindexBaseaclsparseIndexBase_tZERO / ONEdiagTypeaclsparseDiagType_tNON_UNIT / UNITfillModeaclsparseFillMode_tLOWER / UPPER2.4 Legacy 参数顺序遵循 Sparse BLAS 风格aclsparseStatus_t aclsparseSgtsv2( aclsparseHandle_t handle, // 1. Handle int m, // 2. 矩阵行数 const float *dl, // 3. 下对角线 (m-1 元素) const float *d, // 4. 主对角线 (m 元素) const float *du, // 5. 上对角线 (m-1 元素) float *x, // 6. 解向量 / 右端项 (m × nrhs) int nrhs, // 7. 右端项个数列数 int ldx, // 8. 解向量 leading dimension≥ m size_t *pBufferSizeInBytes // 9. workspace 大小输入输出 );参数顺序通用规则handle永远第一维度参数m, n, k, nnz, nrhs紧随其后数据指针带 const 修饰输入leading dimension / stride 参数工作区大小可选输出参数2.5 Legacy Buffer 模式两种Legacy 算子的 buffer 管理不如 Generic 的三阶段清晰常见两种模式模式 A内联 bufferSize 参数aclsparseStatus_t aclsparseSgtsv2_bufferSize(handle, m, dl, d, du, x, nrhs, ldx, bufferSize); aclsparseStatus_t aclsparseSgtsv2(handle, m, dl, d, du, x, nrhs, ldx, bufferSize);bufferSize 作为独立函数返回也可嵌入主函数参数。模式 B无 buffer一次性计算aclsparseStatus_t aclsparseS{t}coo2csr( handle, cooRowInd, nnz, m, csrRowPtr, idxBase);格式转换类常见。三、公共规范两种体系共用3.1 枚举类型aclsparseOperation_ttypedef enum { ACL_SPARSE_OP_NON_TRANSPOSE 0, ACL_SPARSE_OP_TRANSPOSE, ACL_SPARSE_OP_CONJUGATE_TRANSPOSE } aclsparseOperation_t;aclsparseStatus_ttypedef enum { ACL_SPARSE_STATUS_SUCCESS 0, ACL_SPARSE_STATUS_NOT_INITIALIZED, ACL_SPARSE_STATUS_ALLOC_FAILED, ACL_SPARSE_STATUS_INVALID_VALUE, ACL_SPARSE_STATUS_ARCH_MISMATCH, ACL_SPARSE_STATUS_EXECUTION_FAILED, ACL_SPARSE_STATUS_INTERNAL_ERROR, ACL_SPARSE_STATUS_MATRIX_TYPE_NOT_SUPPORTED, ACL_SPARSE_STATUS_NOT_SUPPORTED, ACL_SPARSE_STATUS_INSUFFICIENT_RESOURCES, ACL_SPARSE_STATUS_HANDLE_IS_NULLPTR } aclsparseStatus_t;aclsparseFormat_ttypedef enum { ACL_SPARSE_FORMAT_COO 0, ACL_SPARSE_FORMAT_CSR, ACL_SPARSE_FORMAT_CSC, ACL_SPARSE_FORMAT_BLOCKED_ELL, ACL_SPARSE_FORMAT_SLICED_ELL, ACL_SPARSE_FORMAT_BSR } aclsparseFormat_t;aclsparseIndexType_t / aclsparseIndexBase_ttypedef enum { ACL_SPARSE_INDEX_32I 0, ACL_SPARSE_INDEX_64I } aclsparseIndexType_t; typedef enum { ACL_SPARSE_INDEX_BASE_ZERO 0, ACL_SPARSE_INDEX_BASE_ONE } aclsparseIndexBase_t;aclsparseMatrixType_t仅 Legacytypedef enum { ACL_SPARSE_MATRIX_TYPE_GENERAL 0, ACL_SPARSE_MATRIX_TYPE_SYMMETRIC, ACL_SPARSE_MATRIX_TYPE_HERMITIAN, ACL_SPARSE_MATRIX_TYPE_TRIANGULAR } aclsparseMatrixType_t;aclsparseDiagType_t / aclsparseFillMode_t仅 Legacytypedef enum { ACL_SPARSE_DIAG_TYPE_NON_UNIT 0, ACL_SPARSE_DIAG_TYPE_UNIT } aclsparseDiagType_t; typedef enum { ACL_SPARSE_FILL_MODE_LOWER 0, ACL_SPARSE_FILL_MODE_UPPER } aclsparseFillMode_t;3.2 Handle 管理共用aclsparseStatus_t aclsparseCreate(aclsparseHandle_t *handle); aclsparseStatus_t aclsparseDestroy(aclsparseHandle_t handle); aclsparseStatus_t aclsparseSetStream(aclsparseHandle_t handle, aclrtStream stream);3.3 稀疏格式索引结构共用CSR数组长度说明csrRowOffsetsrows 1行偏移csrColIndnnz列索引csrValuesnnz非零元素值COO数组长度说明cooRowIndnnz行索引cooColIndnnz列索引cooValuesnnz非零元素值CSC数组长度说明cscColOffsetscols 1列偏移cscRowIndnnz行索引cscValuesnnz非零元素值3.4 状态码使用规范场景状态码正常完成ACL_SPARSE_STATUS_SUCCESShandle 为 nullptrACL_SPARSE_STATUS_HANDLE_IS_NULLPTR描述符/指针为 nullptrACL_SPARSE_STATUS_INVALID_VALUE维度为负数或不合法ACL_SPARSE_STATUS_INVALID_VALUE内存分配失败ACL_SPARSE_STATUS_ALLOC_FAILED不支持的稀疏格式ACL_SPARSE_STATUS_NOT_SUPPORTED仅 Generic不支持的数据类型ACL_SPARSE_STATUS_NOT_SUPPORTED不支持的算法ACL_SPARSE_STATUS_NOT_SUPPORTED仅 Generic芯片不支持ACL_SPARSE_STATUS_ARCH_MISMATCHKernel 执行失败ACL_SPARSE_STATUS_EXECUTION_FAILEDUB 容量不足ACL_SPARSE_STATUS_INSUFFICIENT_RESOURCES内部错误ACL_SPARSE_STATUS_INTERNAL_ERROR四、常见错误示例命名错误❌ 错误✅ 正确说明aclsparse_spmvaclsparseSpMV禁止下划线分隔aclsparseSPMVaclsparseSpMV禁止全大写aclsparseSpMvaclsparseSpMVMV 是缩写应全大写描述符使用错误Generic API❌ 错误✅ 正确说明传入aclsparseSpMatDescr_t给只读参数传入aclsparseConstSpMatDescr_t输入描述符必须用 const 版本跳过GetBufferSize直接调用算子先GetBufferSize→ 分配 buffer → 再调用三阶段不可跳过忘记DestroySpMatCreate/Destroy 配对描述符必须释放Legacy API 错误❌ 错误✅ 正确说明aclsparseGtsv2(...)aclsparseSgtsv2(...)Legacy 必须带精度前缀传入未初始化的pBufferSize指针先声明size_t bufSize 0;再传bufSize指针必须有效const 修饰错误❌ 错误✅ 正确说明void *alphaconst void *alpha标量输入必须 constaclsparseDnVecDescr_t vecX输入aclsparseConstDnVecDescr_t vecX输入向量用 const 描述符五、参考资源资源链接说明cuSPARSE 官方文档https://docs.nvidia.com/cuda/cusparse/Generic API Legacy API 完整参考cuSPARSE Generic APIhttps://docs.nvidia.com/cuda/cusparse/#cusparse-generic-apisDescriptor 模式、三阶段执行cuSPARSE Legacy APIhttps://docs.nvidia.com/cuda/cusparse/#cusparse-legacy-apis已弃用接口仅用于对标尚未迁移的算子Sparse BLAS 标准https://www.netlib.org/blas/Legacy API 命名和参数顺序参考【免费下载链接】ops-sparse本项目是CANN提供的高性能稀疏矩阵计算的算子库专注于优化稀疏矩阵的计算效率。项目地址: https://gitcode.com/cann/ops-sparse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考