14. mcSPARSE通用API参考

mcSPARSE通用API允许以灵活的方式进行最常见的稀疏线性代数运算，例如稀疏矩阵-向量乘法(SpMV)和稀疏矩阵-矩阵乘法(SpMM)。这些新的API具有以下功能和特点：

设置矩阵的数据布局、批次数和存储格式(例如CSR、COO等)
设置输入/输出/计算数据类型。这还允许混合数据类型计算。
设置稀疏矩阵索引的类型。
选择计算的算法。
提供用于内部操作的外部设备内存。
对于给定的例程，提供广泛的输入矩阵和向量的一致性检查。这包括验证矩阵的大小、数据类型、布局、允许的操作等。

14.1. 通用类型参考

本章节描述了mcSPARSE通用类型的参考。

14.1.1. macaDataType_t

本节描述了多个 MXMACA 库共享并在头文件 library_types.h 中定义的类型。其中 macaDataType 类型是一个用于指定数据的精度枚举类型。当数据引用本身不携带类型（例如 void* 类型）时，就会使用它。例如，在例程 mcsparseSpMM() 中使用了这个类型。

值	含义	数据类型	头文件
`MACA_R_32F`	数据类型是32位 IEEE-754浮点数	`float`
`MACA_C_32F`	数据类型是32位 IEEE-754复数浮点数	`mcComplex`	mcComplex.h
`MACA_R_64F`	数据类型是64位 IEEE-754浮点数点数	`double`
`MACA_C_64F`	数据类型是64位 IEEE-754复数浮点数	`mcDouble Complex`	mcComplex.h
`MACA_R_8I`	数据类型是8位整数	`int8_t`	stdint.h
`MACA_R_32I`	数据类型是32位整数	`int32_t`	stdint.h

重要提示：

通用API例程仅允许在有原生支持的 GPU 架构上使用文档相应章节中报告的所有数据类型。如果特定的GPU型号没有提供对给定数据类型的原生支持，则例程将返回 MCSPARSE_STATUS_ARCH_MISMATCH 错误。

14.1.2. mcsparseFormat_t

此类型指示稀疏矩阵的格式。

值	含义
`MCSPARSE_FORMAT_COO`	矩阵以坐标格式(COO)存储，并采用结构数组(SoA)布局。
`MCSPARSE_FORMAT_COO_AOS`	矩阵以坐标格式(COO)存储，并采用结构数组(SoA)布局。
`MCSPARSE_FORMAT_CSR`	矩阵以压缩稀疏行(CSR)格式存储。
`MCSPARSE_FORMAT_CSC`	矩阵以压缩稀疏列(CSC)格式存储。
`MCSPARSE_FORMAT_BLOCKED_ELL`	矩阵以块-ELL(Blocked-Ell) 格式存储。

14.1.3. mcsparseOrder_t

此类型表示稠密矩阵的内存布局。

相关值	含义
`MCSPARSE_ORDER_ROW`	矩阵按行主序存储。
`MCSPARSE_ORDER_COL`	矩阵按列主序存储。

14.1.4. mcsparseIndexType_t

用于表示稀疏矩阵索引的索引类型。

相关值	含义
`MCSPARSE_INDEX_16U`	16位无符号整数。 [1, 65535]
`MCSPARSE_INDEX_32I`	32位有符号整数。 [1, 2^31 - 1]
`MCSPARSE_INDEX_64I`	64位有符号整数。 [1, 2^63 - 1]

14.2. 稀疏向量 API

该部分描述了用于稀疏向量描述符的 mcSPARSE 辅助函数。

14.2.1. mcsparseCreateSpVec()

mcsparseStatus_t
mcsparseCreateSpVec(mcsparseSpVecDescr_t* spVecDescr,
                     int64_t               size,
                     int64_t               nnz,
                     void*                 indices,
                     void*                 values,
                     mcsparseIndexType_t   idxType,
                     mcsparseIndexBase_t   idxBase,
                     macaDataType          valueType)

此函数用于初始化稀疏矩阵描述符 spVecDescr。

参数

内存

输入/输出

含义

spVecDescr

主机

输出

稀疏向量描述符

size

主机

输入

稀疏向量的大小

nnz

主机

输入

稀疏向量中非零条目的数量

indices

设备

输入

稀疏向量的索引数组大小为 nnz

values

设备

输入

稀疏向量的索引数组大小为 nnz

idxType

主机

输入

枚举器，用于指定 indices 的数据类型

idxBase

主机

输入

枚举器，用于指定 indices 的基索引

valueType

主机

输入

枚举器，用于指定 values 的数据类型

备注

如果描述符不会被用作例程的输出参数(例如转换函数)，则可以安全地对输入指针进行去除const属性性变换(使用 const_cast) 。

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.2.2. mcsparseDestroySpVec()

mcsparseStatus_t
mcsparseDestroySpVec(mcsparseSpVecDescr_t spVecDescr)

此函数释放为稀疏向量描述符 spVecDescr 分配的主机内存。

参数

内存

输入/输出

含义

spVecDescr

主机

输入

稀疏向量描述符

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.2.3. mcsparseSpVecGet()

mcsparseStatus_t
mcsparseSpVecGet(mcsparseSpVecDescr_t spVecDescr,
                  int64_t*             size,
                  int64_t*             nnz,
                  void**               indices,
                  void**               values,
                  mcsparseIndexType_t* idxType,
                  mcsparseIndexBase_t* idxBase,
                  macaDataType*        valueType)

此函数返回稀疏向量描述符 spVecDescr 的字段。

参数

内存

输入/输出

含义

spVecDescr

主机

输入

稀疏向量描述符

size

主机

输出

稀疏向量的大小

nnz

主机

输出

稀疏向量的非零元素个数

indices

设备

输出

稀疏向量的索引。大小为 nnz 的数组

values

设备

输出

稀疏向量的值。大小为 nnz 的数组

idxType

主机

输出

枚举器指定 indices 的数据类型

idxBase

主机

输出

枚举器指定 indices 的基索引

valueType

主机

输出

枚举器指定 values 的数据类型

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.2.4. mcsparseSpVecGetIndexBase()

mcsparseStatus_t
mcsparseSpVecGetIndexBase(mcsparseSpVecDescr_t spVecDescr,
                           mcsparseIndexBase_t* idxBase)

此函数返回稀疏向量描述符 spVecDescr 的 idxBase 字段。

参数

内存

输入/输出

含义

spVecDescr

主机

输入

稀疏向量描述符

idxBase

主机

输出

枚举器，指定 indices 的基准索引

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.2.5. mcsparseSpVecGetValues()

mcsparseStatus_t
mcsparseSpVecGetValues(mcsparseSpVecDescr_t spVecDescr,
                        void**               values)

此函数返回稀疏向量描述符 spVecDescr 的 values 字段。

参数

内存

输入/输出

含义

spVecDescr

主机

输入

稀疏向量描述符 descriptor

values

设备

输出

稀疏向量的值。大小为 nnz 的数组

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.2.6. mcsparseSpVecSetValues()

mcsparseStatus_t
mcsparseSpVecSetValues(mcsparseSpVecDescr_t spVecDescr,
                        void*                values)

此函数设置稀疏向量描述符 spVecDescr 的 values 字段。

参数

内存

输入/输出

含义

spVecDescr

主机

输入

稀疏向量描述符 descriptor

values

设备

输入

稀疏向量的值。大小为 nnz 的数组

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.3. 稀疏矩阵API

本节介绍用于稀疏矩阵描述符的mcSPARSE辅助函数。

14.3.1. mcsparseCreateCoo()

mcsparseStatus_t
mcsparseCreateCoo(mcsparseSpMatDescr_t* spMatDescr,
                  int64_t               rows,
                  int64_t               cols,
                  int64_t               nnz,
                  void*                 cooRowInd,
                  void*                 cooColInd,
                  void*                 cooValues,
                  mcsparseIndexType_t   cooIdxType,
                  mcsparseIndexBase_t   idxBase,
                  macaDataType          valueType)

此函数以COO格式(数组结构布局)初始化稀疏矩阵描述符spMatDescr。

参数

内存

输入/输出

含义

spMatDescr

主机

输出

稀疏矩阵描述符

rows

主机

输入

稀疏矩阵的行数

cols

主机

输入

稀疏矩阵的列数

nnz

主机

输入

稀疏矩阵的非零元素个数

cooRowInd

设备

输入

稀疏矩阵的行索引。大小为 nnz 的数组

cooColInd

设备

输入

稀疏矩阵的列索引。大小为 nnz 的数组

cooValues

设备

输入

稀疏矩阵的值。大小为 nnz 的数组

cooIdxType

主机

输入

cooRowInd 和 cooColInd 的数据类型

idxBase

主机

输入

cooRowInd 和 cooColInd 的基准索引

valueType

主机

输入

cooValues 的数据类型

备注

如果描述符不会被用作例程的输出参数(如转换函数)，则可以安全地去除输入指针的const属性(使用const_cast)。

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.3.2. mcsparseCreateCsr()

mcsparseStatus_t
mcsparseCreateCsr(mcsparseSpMatDescr_t* spMatDescr,
                  int64_t               rows,
                  int64_t               cols,
                  int64_t               nnz,
                  void*                 csrRowOffsets,
                  void*                 csrColInd,
                  void*                 csrValues,
                  mcsparseIndexType_t   csrRowOffsetsType,
                  mcsparseIndexType_t   csrColIndType,
                  mcsparseIndexBase_t   idxBase,
                  macaDataType          valueType)

此函数以CSR格式初始化稀疏矩阵的描述符 spMatDescr。

参数

内存

输入/输出

含义

spMatDescr

主机

输出

稀疏矩阵描述符。

rows

主机

输入

稀疏矩阵的行数

cols

主机

输入

稀疏矩阵的列数

nnz

主机

输入

稀疏矩阵的非零元素数量

csrRowOffsets

设备

输入

稀疏矩阵的行偏移量。大小为 rows + 1 的数组。

csrColInd

设备

输入

稀疏矩阵的列索引。大小为 nnz 的数组。

csrValues

设备

输入

稀疏矩阵的值。大小为 nnz 的数组。

csrRowOffsetsType

主机

输入

数据类型为 csrRowOffsets

csrColIndType

主机

输入

数据类型为 csrColInd

idxBase

主机

输入

基础索引的类型为 csrRowOffsets 和 csrColInd

valueType

主机

输入

数据类型为 csrValues

备注

如果描述符不会用作程序的输出参数(例如转换函数)，则可以安全地去除输入指针的常量性(使用 const_cast )。

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.3.3. mcsparseCreateCsc()

mcsparseStatus_t
mcsparseCreateCsc(mcsparseSpMatDescr_t* spMatDescr,
                  int64_t               rows,
                  int64_t               cols,
                  int64_t               nnz,
                  void*                 cscColOffsets,
                  void*                 cscRowInd,
                  void*                 cscValues,
                  mcsparseIndexType_t   cscColOffsetsType,
                  mcsparseIndexType_t   cscRowIndType,
                  mcsparseIndexBase_t   idxBase,
                  macaDataType          valueType)

此函数用于初始化用CSC格式表示的稀疏矩阵描述符 spMatDescr。

参数

内存

输入/输出

含义

spMatDescr

主机

输出

稀疏矩阵描述符

rows

主机

输入

稀疏矩阵的行数

cols

主机

输入

稀疏矩阵的列数

nnz

主机

输入

稀疏矩阵的非零项数

cscColOffsets

设备

输入

稀疏矩阵的列偏移。大小为 cols + 1 的数组

cscRowInd

设备

输入

稀疏矩阵的行索引。大小为 nnz 的数组

cscValues

设备

输入

稀疏矩阵的值。大小为 nnz 的数组

cscColOffsetsType

主机

输入

cscColOffsets 的数据类

cscRowIndType

主机

输入

cscRowInd 的数据类型

idxBase

主机

输入

cscColOffsets 和 cscRowInd 基准索引

valueType

主机

输入

cscValues 的数据类型

备注

如果描述符不会被用作例程的输出参数(例如转换函数)，则可以安全地使用 const_cast 来移除输入指针的const限定。

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.3.4. mcsparseDestroySpMat()

mcsparseStatus_t
mcsparseDestroySpMat(mcsparseSpMatDescr_t spMatDescr)

此函数释放分配给稀疏矩阵描述符 spMatDescr 的内存。

参数

内存

输入/输出

含义

spMatDescr

主机

输入

稀疏矩阵描述符

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.3.5. mcsparseCooGet()

mcsparseStatus_t
mcsparseCooGet(mcsparseSpMatDescr_t spMatDescr,
               int64_t*             rows,
               int64_t*             cols,
               int64_t*             nnz,
               void**               cooRowInd,
               void**               cooColInd,
               void**               cooValues,
               mcsparseIndexType_t* idxType,
               mcsparseIndexBase_t* idxBase,
               macaDataType*        valueType)

此函数返回以COO格式(结构数组布局)存储的稀疏矩阵描述符 spMatDescr 的字段。

参数

内存

输入/输出

含义

spMatDescr

主机

输入

稀疏矩阵描述符

rows

主机

输出

稀疏矩阵的行数

cols

主机

输出

稀疏矩阵的列数

nnz

主机

输出

稀疏矩阵的非零元素数量

cooRowInd

设备

输出

稀疏矩阵的行索引。大小为 nnz 的数组

cooColInd

设备

输出

稀疏矩阵的列索引。大小为 nnz 的数组

cooValues

设备

输出

稀疏矩阵的非零元素大小为 nnz 的数组

cooIdxType

主机

输出

cooRowInd 和 cooColInd 的数据类型

idxBase

主机

输出

cooRowInd 和 cooColInd 的基准索引

valueType

主机

输出

cooValues 数据类型

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.3.6. mcsparseCsrGet()

mcsparseStatus_t
mcsparseCsrGet(mcsparseSpMatDescr_t spMatDescr,
               int64_t*             rows,
               int64_t*             cols,
               int64_t*             nnz,
               void**               csrRowOffsets,
               void**               csrColInd,
               void**               csrValues,
               mcsparseIndexType_t* csrRowOffsetsType,
               mcsparseIndexType_t* csrColIndType,
               mcsparseIndexBase_t* idxBase,
               macaDataType*        valueType)

此函数返回以CSR格式存储的稀疏矩阵描述符的 spMatDescr 字段。

参数

内存

输入/输出

含义

spMatDescr

主机

输入

稀疏矩阵描述符

rows

主机

输出

稀疏矩阵的行数

cols

主机

输出

稀疏矩阵的列数

nnz

主机

输出

稀疏矩阵的非零元素数量

csrRowOffsets

设备

输出

稀疏矩阵的行偏移。大小为 rows + 1 的数组

csrColInd

设备

输出

稀疏矩阵的列索引。大小为 nnz 的数组

csrValues

设备

输出

稀疏矩阵的非零元素 nnz

csrRowOffsetsType

主机

输出

csrRowOffsets 的数据类型

csrColIndType

主机

输出

csrColInd 的数据类型

idxBase

主机

输出

csrRowOffsets 和 csrColInd 的基准索引

valueType

主机

输出

csrValues 的数据类型

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.3.7. mcsparseCsrSetPointers()

mcsparseStatus_t
mcsparseCsrSetPointers(mcsparseSpMatDescr_t spMatDescr,
                        void*                csrRowOffsets,
                        void*                csrColInd,
                        void*                csrValues)

此函数设置稀疏矩阵描述符 spMatDescr 的指针。

参数

内存

输入/输出

含义

spMatDescr

主机

输入

稀疏矩阵描述符

csrRowOffsets

设备

输入

稀疏矩阵的行偏移。大小为 rows + 1 的数组

csrColInd

设备

输入

稀疏矩阵的列索引。大小为 nnz 的数组

csrValues

设备

输入

稀疏矩阵的非零元素大小为 nnz 的数组

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.3.8. mcsparseCscSetPointers()

mcsparseStatus_t
mcsparseCscSetPointers(mcsparseSpMatDescr_t spMatDescr,
                        void*                cscColOffsets,
                        void*                cscRowInd,
                        void*                cscValues)

此函数设置稀疏矩阵描述符 spMatDescr 的指针。

参数

内存

输入/输出

含义

spMatDescr

主机

输入

稀疏矩阵描述符

cscColOffsets

设备

输入

稀疏矩阵的列偏移。大小为 cols + 1 的数组

cscRowInd

设备

输入

稀疏矩阵的行索引。大小为 nnz 的数组

cscValues

设备

输入

稀疏矩阵的非零元素大小为 nnz 的数组

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.3.9. mcsparseCooSetPointers()

mcsparseStatus_t
mcsparseCooSetPointers(mcsparseSpMatDescr_t spMatDescr,
                        void*                cooRows,
                        void*                cooColumns,
                        void*                cooValues)

此函数设置稀疏矩阵描述符 spMatDescr 的指针。

参数

内存

输入/输出

描述

spMatDescr

主机

输入

稀疏矩阵描述符

cooRows

设备

输入

稀疏矩阵的行索引。大小为 nnz 的数组

cooColumns

设备

输入

稀疏矩阵的列索引。大小为 nnz 的数组

cooValues

设备

输入

稀疏矩阵的值。大小为 nnz 的数组

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.3.10. mcsparseSpMatGetSize()

mcsparseStatus_t
mcsparseSpMatGetSize(mcsparseSpMatDescr_t spMatDescr,
                     int64_t*             rows,
                     int64_t*             cols,
                     int64_t*             nnz)

此函数返回稀疏矩阵 spMatDescr 的大小。

参数

内存

输入/输出

描述

spMatDescr

主机

输入

稀疏矩阵描述符

rows

主机

输出

稀疏矩阵的行数

cols

主机

输出

稀疏矩阵的列数

nnz

主机

输出

稀疏矩阵的非零元素的个数

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.3.11. mcsparseSpMatGetFormat()

mcsparseStatus_t
mcsparseSpMatGetFormat(mcsparseSpMatDescr_t spMatDescr,
                        mcsparseFormat_t*    format)

此函数返回稀疏矩阵描述符 spMatDescr 的 format 字段。

参数

内存

输入/输出

含义

spMatDescr

主机

输入

稀疏矩阵描述符

format

主机

输出

稀疏矩阵的存储格式

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.3.12. mcsparseSpMatGetIndexBase()

mcsparseStatus_t
mcsparseSpMatGetIndexBase(mcsparseSpMatDescr_t spMatDescr,
                           mcsparseIndexBase_t* idxBase)

此函数返回稀疏矩阵描述符 spMatDescr 的 idxBase 字段。

参数

内存

输入/输出

含义

spMatDescr

主机

输入

稀疏矩阵描述符

idxBase

主机

输出

稀疏矩阵的基准索引

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.3.13. mcsparseSpMatGetValues()

mcsparseStatus_t
mcsparseSpMatGetValues(mcsparseSpMatDescr_t spMatDescr,
                        void**               values)

此函数返回稀疏矩阵描述符 spMatDescr 的 values 字段。

参数

内存

输入/输出

含义

spMatDescr

主机

输入

稀疏矩阵描述符

values

设备

输出

稀疏矩阵的值。大小为 nnz 的数组

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.3.14. mcsparseSpMatSetValues()

mcsparseStatus_t
mcsparseSpMatSetValues(mcsparseSpMatDescr_t spMatDescr,
                        void*                values)

此函数设置稀疏矩阵描述符 spMatDescr 的 values 字段。

参数

内存

输入/输出

含义

spMatDescr

主机

输入

稀疏矩阵描述符

values

设备

输入

稀疏矩阵的值。大小为 nnz 的数组

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.4. 稠密向量APIs

本节将描述稠密向量描述符的 mcSPARSE 帮助函数。

14.4.1. mcsparseCreateDnVec()

mcsparseStatus_t
mcsparseCreateDnVec(mcsparseDnVecDescr_t* dnVecDescr,
                     int64_t               size,
                     void*                 values,
                     macaDataType          valueType)

此函数初始化稠密向量描述符 dnVecDescr。

参数

内存

输入/输出

含义

dnVecDescr

主机

输出

稠密向量描述符

size

主机

输入

稠密向量的大小

values

设备

输入

稠密向量的值。大小为 nnz 的数组

valueType

主机

输入

枚举符，指定 values 数据类型

备注

如果描述符不会被用作例程的输出参数(例如转换函数)，则可以安全地使用 const_cast 来移除输入指针的const限定。

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.4.2. mcsparseDestroyDnVec()

mcsparseStatus_t
mcsparseDestroyDnVec(mcsparseDnVecDescr_t dnVecDescr)

此函数释放了为稠密向量描述符 dnVecDescr 分配的主机内存。

参数

内存

输入/输出

含义

dnVecDescr

主机

输入

稠密向量描述符

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.4.3. mcsparseDnVecGet()

mcsparseStatus_t
mcsparseDnVecGet(mcsparseDnVecDescr_t dnVecDescr,
                  int64_t*             size,
                  void**               values,
                  macaDataType*        valueType)

此函数返回稠密向量描述符 dnVecDescr 的字段。

参数

内存

输入/输出

含义

dnVecDescr

主机

输入

稠密向量描述符

size

主机

输出

稠密向量的大小

values

设备

输出

稠密向量的值。大小为 nnz 的数组

valueType

主机

输出

枚举符，指定 values 数据类型

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.4.4. mcsparseDnVecGetValues()

mcsparseStatus_t
mcsparseDnVecGetValues(mcsparseDnVecDescr_t dnVecDescr,
                        void**               values)

此函数返回稠密向量描述符 dnVecDescr 的 values 字段。

参数

内存

输入/输出

描述

dnVecDescr

主机

输入

稠密向量描述符

values

设备

输出

稠密向量的值

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.4.5. mcsparseDnVecSetValues()

mcsparseStatus_t
mcsparseDnVecSetValues(mcsparseDnVecDescr_t dnVecDescr,
                        void*                values)

此函数设置了稠密向量描述符 dnVecDescr 的 values 字段。

参数

内存

输入/输出

含义

dnVecDescr

主机

输入

稠密向量描述符

values

设备

输入

稠密向量的值。大小为 size 的数组

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.5. 稠密矩阵APIs

这个部分描述了用于稠密矩阵描述符的mcSPARSE辅助函数。

14.5.1. mcsparseCreateDnMat()

mcsparseStatus_t
mcsparseCreateDnMat(mcsparseDnMatDescr_t* dnMatDescr,
                     int64_t               rows,
                     int64_t               cols,
                     int64_t               ld,
                     void*                 values,
                     macaDataType          valueType,
                     mcsparseOrder_t       order)

此函数初始化了稠密矩阵描述符 dnMatDescr。

参数

内存

输入/输出

含义

dnMatDescr

主机

输出

稠密矩阵描述符

rows

主机

输入

稠密矩阵的行数

cols

主机

输入

稠密矩阵的列数

ld

主机

输入

稠密矩阵的主维度

values

设备

输入

稠密矩阵的值。大小为 size 的数组

valueType

主机

输入

指定 values 数据类型的枚举类型

order

主机

输入

指定稠密矩阵的内存布局的枚举类型

备注

如果描述符不会用作例行程序(例如转换函数)的输出参数，则可以安全地将输入指针的constness(const_cast)去除。

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.5.2. mcsparseDestroyDnMat()

mcsparseStatus_t
mcsparseDestroyDnMat(mcsparseDnMatDescr_t dnMatDescr)

此函数释放了为稠密矩阵描述符 dnMatDescr 分配的主机内存。

参数

内存

输入/输出

含义

dnMatDescr

主机

输入

稠密矩阵描述符

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.5.3. mcsparseDnMatGet()

mcsparseStatus_t
mcsparseDnMatGet(mcsparseDnMatDescr_t dnMatDescr,
                  int64_t*             rows,
                  int64_t*             cols,
                  int64_t*             ld,
                  void**               values,
                  macaDataType*        type,
                  mcsparseOrder_t*     order)

此函数返回了稠密矩阵描述符 dnMatDescr 的字段。

参数

内存

输入/输出

含义

dnMatDescr

主机

输入

稠密矩阵描述符

rows

主机

输出

稠密矩阵的行数

cols

主机

输出

稠密矩阵的列数

ld

主机

输出

稠密矩阵的主维度

values

设备

输出

稠密矩阵的值。大小为 ld * cols 的数组

valueType

主机

输出

指定 values 数据类型的枚举类型

order

主机

输出

指定稠密矩阵的内存布局的枚举类型

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.5.4. mcsparseDnMatGetValues()

mcsparseStatus_t
mcsparseDnMatGetValues(mcsparseDnMatDescr_t dnMatDescr,
                        void**               values)

此函数返回了稠密矩阵描述符 dnMatDescr 的字段。

参数

内存

输入/输出

含义

dnMatDescr

主机

输入

稠密矩阵描述符

values

设备

输出

稠密矩阵的值。大小为 ld * cols 的数组

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.5.5. mcsparseDnSetValues()

mcsparseStatus_t
mcsparseDnMatSetValues(mcsparseDnMatDescr_t dnMatDescr,
                        void*                values)

此函数设置了稠密矩阵描述符 dnMatDescr 的 values 字段。

参数

内存

输入/输出

含义

dnMatDescr

主机

输入

稠密矩阵描述符

values

设备

输入

稠密矩阵的值。大小为 ld * cols 的数组

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.5.6. mcsparseDnMatGetStridedBatch()

mcsparseStatus_t
mcsparseDnMatGetStridedBatch(mcsparseDnMatDescr_t dnMatDescr,
                              int*                 batchCount,
                              int64_t*             batchStride)

此函数返回了稠密矩阵描述符 dnMatDescr 的批次数和批次步长。

参数

内存

输入/输出

含义

dnMatDescr

主机

输入

稠密矩阵描述符

batchCount

主机

输出

稠密矩阵的批次数

batchStride

主机

输出

一个矩阵与批次中下一个矩阵之间的地址偏移量

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.5.7. mcsparseDnMatSetStridedBatch()

mcsparseStatus_t
mcsparseDnMatSetStridedBatch(mcsparseDnMatDescr_t dnMatDescr,
                              int                  batchCount,
                              int64_t              batchStride)

此函数设置了稠密矩阵描述符 dnMatDescr 的批次数和批次步长。

参数

内存

输入/输出

含义

dnMatDescr

主机

输入

稠密矩阵描述符

batchCount

主机

输入

稠密矩阵的批次数

batchStride

主机

输入

一个矩阵与批次中下一个矩阵之间的的地址偏移量。

如果矩阵使用列优先布局，则 batchStride >= ld * cols

如果不是，则 batchStride >= ld * rows

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.6. 通用 API 函数

14.6.1. mcsparseSparseToDense()

mcsparseStatus_t
mcsparseSparseToDense_bufferSize(mcsparseHandle_t           handle,
                                 mcsparseSpMatDescr_t       matA,
                                 mcsparseDnMatDescr_t       matB,
                                 mcsparseSparseToDenseAlg_t alg,
                                 size_t*                    bufferSize)

mcsparseStatus_t
mcsparseSparseToDense(mcsparseHandle_t           handle,
                        mcsparseSpMatDescr_t       matA,
                        mcsparseDnMatDescr_t       matB,
                        mcsparseSparseToDenseAlg_t alg,
                        void*                      buffer)

此函数将稀疏矩阵 matA 从CSR、CSC或COO格式转换为其密集表示 matB。目前不支持Blocked-ELL格式。

函数 mcsparseSparseToDense_bufferSize() 返回 mcsparseSparseToDense() 函数所需的工作空间大小。

参数

内存

输入/输出

含义

handle

主机

输入

处理mcSPARSE库上下文的句柄

matA

主机

输入

稀疏矩阵 A

matB

主机

输出

稠密矩阵 B

alg

主机

输入

计算的算法

bufferSize

主机

输出

mcsparseSparseTo Dense() 函数所需的工作空间字节数。

buffer

设备

输入

指向工作空间缓冲区的指针

mcsparseSparseToDense() 支持以下索引类型来表示稀疏矩阵 matA：

32位索引(MCSPARSE_INDEX_32I)
64位索引 (MCSPARSE_INDEX_64I)

mcsparseSparseToDense() 支持以下数据类型：

A/B

MACA_R_16F

MACA_R_16BF

MACA_R_32F

MACA_R_64F

MACA_C_16F

MACA_C_16BF

MACA_C_32F

MACA_C_64F

mcsparseSparse2Dense() 支持以下算法：

算法

说明

MCSPARSE_SPARSETODENSE_ALG_DEFAULT

默认算法

mcsparseSparseToDense() 具有以下特性：

这个例程不需要额外的存储空间
这个例程支持异步执行
对于每次运行都提供确定(位级相同)的结果

mcsparseSparseToDense() 支持以下优化：

硬件内存压缩

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.6.2. mcsparseDenseToSparse()

mcsparseStatus_t
mcsparseDenseToSparse_bufferSize(mcsparseHandle_t           handle,
                                 mcsparseDnMatDescr_t       matA,
                                 mcsparseSpMatDescr_t       matB,
                                 mcsparseDenseToSparseAlg_t alg,
                                 size_t*                    bufferSize)

mcsparseStatus_t
mcsparseDenseToSparse_analysis(mcsparseHandle_t           handle,
                                 mcsparseDnMatDescr_t       matA,
                                 mcsparseSpMatDescr_t       matB,
                                 mcsparseDenseToSparseAlg_t alg,
                                 void*                      buffer)

mcsparseStatus_t
mcsparseDenseToSparse_convert(mcsparseHandle_t           handle,
                              mcsparseDnMatDescr_t       matA,
                              mcsparseSpMatDescr_t       matB,
                              mcsparseDenseToSparseAlg_t alg,
                              void*                      buffer)

此函数将稠密矩阵 matA 转换为稀疏矩阵 matB，可以选择转换为CSR、CSC、COO或Blocked-ELL格式。

函数 mcsparseDenseToSparse_bufferSize() 返回 mcsparseDenseToSparse_bufferSize() 所需的工作空间大小。

函数 mcsparseDenseToSparse_analysis() 更新稀疏矩阵描述符 matB 中的非零元素数量。用户负责分配稀疏矩阵所需的内存：

分别为 CSC 和 CSR 的行/列索引以及值数组。
COO 格式的行、列和值数组。
Blocked-ELL 格式的列索引(ellColInd)和值数组(ellValue)。

最后，我们调用 mcsparseDenseToSparse_convert() 来填充在前一步骤中分配的数组。

参数

内存

输入/输出

含义

handle

主机

输入

处理mcSPARSE库上下文的句柄

matA

主机

输入

稠密矩阵 A

matB

主机

输出

稀疏矩阵 B

alg

主机

输入

计算的算法

bufferSize

主机

输出

mcsparseDens eToSparse_analysis() 函数所需的工作空间字节数

buffer

设备

输入

指向工作空间缓冲区的指针

mcsparseDenseToSparse() 支持以下索引类型来表示稀疏向量 matB：

32位索引 (MCSPARSE_INDEX_32I)
64位索引 (MCSPARSE_INDEX_64I)

mcsparseDenseToSparse() 支持以下数据类型：

A/B

MACA_R_16F

MACA_R_16BF

MACA_R_32F

MACA_R_64F

MACA_C_16F

MACA_C_16BF

MACA_C_32F

MACA_C_64F

mcsparseDense2Sparse() 支持以下算法：

算法

说明

MCSPARSE_DENSETOSPARSE_ALG_DEFAULT

默认算法

mcsparseDenseToSparse() 具有以下特性：

这个例程不需要额外的存储空间
这个例程支持异步执行
对于每次运行都提供确定(位级相同)的结果

mcsparseDenseToSparse() 支持以下优化：

硬件内存压缩

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.6.3. mcsparseAxpby()

mcsparseStatus_t
mcsparseAxpby(mcsparseHandle_t     handle,
               const void*          alpha,
               mcsparseSpVecDescr_t vecX,
               const void*          beta,
               mcsparseDnVecDescr_t vecY)

此函数计算稀疏向量 vecX 和稠密向量 vecY 的和

Y=αX+βY

即，

for i=0 to n-1
   Y[i] = beta * Y[i] for i=0 to nnz-1 Y[X_indices[i]] += alpha * X_values[i]

参数	内存	输入/输出	含义
`handle`	主机	输入	处理mcSPARSE库上下文的句柄
`alpha`	主机或设备	输入	用于乘法计算类型的标量
`vecX`	主机	输入	稀疏矩阵 `X`
`beta`	主机或设备	输入	用于乘法计算类型的标量
`vecY`	主机	输入/输出	稠密向量 `Y`

mcsparseAxpby 支持以下索引类型来表示稀疏向量 vecX ：

32位索引 (MCSPARSE_INDEX_32I)
64位索引 (MCSPARSE_INDEX_64I)

mcsparseAxpby 支持以下数据类型：

统一精度计算：

X/Y/compute

MACA_R_32F

MACA_R_64F

MACA_C_32F

MACA_C_64F

混合精度计算：

X/ Y

compute

MACA_R_16F

MACA_R_32F

MACA_R_16BF

MACA_C_16F

MACA_C_32F

MACA_C_16BF

mcsparseAxpby() 有以下的约束条件：

表示稀疏向量 vecX 的数组必须对齐到 16 字节

mcsparseAxpby() 有以下特性：

这个例程不需要额外的存储空间
这个例程支持异步执行
如果稀疏向量 vecX 的索引是显著不同的，对于每次运行都提供确定(位级相同)的结果

mcsparseAxpby() 支持以下优化：

硬件内存压缩

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.6.4. mcsparseGather()

mcsparseStatus_t
mcsparseGather(mcsparseHandle_t     handle,
               mcsparseDnVecDescr_t vecY,
               mcsparseSpVecDescr_t vecX)

此函数将稠密向量 vecY 的元素存储到稀疏向量 vecX 中。

即，

for i=0 to nnz-1
   X_values[i] = Y[X_indices[i]]

参数	内存	输入/输出	含义
`handle`	主机	输入	mcSPARSE库上下文的句柄
`vecX`	主机	输出	稀疏向量 `X`
`vecY`	主机	输入	稠密向量 `Y`

mcsparseGather 支持以下索引类型来表示稀疏向量 vecX ：

32位索引 (MCSPARSE_INDEX_32I)
64位索引 (MCSPARSE_INDEX_64I)

mcsparseGather 支持以下数据类型：

X/ Y

MACA_R_16F

MACA_R_16BF

MACA_R_32F

MACA_R_64F

MACA_C_16F

MACA_C_16BF

MACA_C_32F

MACA_C_64F

mcsparseGather() 有以下约束条件：

表示稀疏向量 vecX 的数组必须按照16字节对齐

mcsparseGather() 具有以下特性：

此函数不需要额外的存储空间
此函数支持异步执行
如果稀疏向量 vecX 的索引是显著不同的，每次运行都会得到确定性(逐位)的结果

mcsparseGather() 支持以下优化：

硬件内存压缩(Hardware Memory Compression)

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.6.5. mcsparseScatter()

mcsparseStatus_t
mcsparseScatter(mcsparseHandle_t     handle,
                  mcsparseSpVecDescr_t vecX,
                  mcsparseDnVecDescr_t vecY)

函数将稀疏向量 vecX 的元素散布到稠密向量 vecY 中。

即，

for i=0 to nnz-1
   Y[X_indices[i]] = X_values[i]

参数	内存	输入/输出	含义
`handle`	主机	输入	mcSPARSE库上下文的句柄
`vecX`	主机	输入	稀疏向量 `X`
`vecY`	主机	输出	稠密向量 `Y`

mcsparseScatter 支持以下索引类型来表示稀疏向量 vecX：

32位索引 (MCSPARSE_INDEX_32I)
64位索引 (MCSPARSE_INDEX_64I)

mcsparseScatter 支持以下数据类型：

X/Y

MACA_R_16F

MACA_R_16BF

MACA_R_32F

MACA_R_64F

MACA_C_16F

MACA_C_16BF

MACA_C_32F

MACA_C_64F

mcsparseScatter() 有以下约束条件：

表示稀疏向量 vecX 的数组必须按照16字节对齐

mcsparseScatter() 具有以下特性：

此函数不需要额外的存储空间
此函数支持异步执行
如果稀疏向量 vecX 的索引是显著不同的，每次运行都会得到确定性(逐位)的结果

mcsparseScatter() 支持以下优化：

硬件内存压缩(Hardware Memory Compression)

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.6.6. mcsparseRot()

mcsparseStatus_t
mcsparseRot(mcsparseHandle_t     handle,
            const void*          c_coeff,
            const void*          s_coeff,
            mcsparseSpVecDescr_t vecX,
            mcsparseDnVecDescr_t vecY)

此函数用于计算Givens旋转矩阵。

即，

for i=0 to nnz-1
   Y[X_indices[i]] = c * Y[X_indices[i]] - s * X_values[i] = c * X_values[i] + s * Y[X_indices[i]]

参数	内存	输入/输出	含义
`handle`	主机	输入	处理mcSPARSE库上下文的句柄
`c_coeff`	主机或设备	输入	旋转矩阵的余弦元素
`vecX`	主机	输入/输出	稀疏向量 `X`
`s_coeff`	主机或设备	输入	旋转矩阵的正弦元素
`vecY`	主机	输入/输出	稠密向量 `Y`

mcsparseRot 支持以下索引类型来表示稀疏向量 vecX ：

32位索引 (MCSPARSE_INDEX_32I)
64位索引 (MCSPARSE_INDEX_64I)

mcsparseRot 支持以下数据类型：

统一精度计算：

X/Y/compute

MACA_R_32F

MACA_R_64F

MACA_C_32F

MACA_C_64F

混合精度计算：

X/ Y

compute

MACA_R_16F

MACA_R_32F

MACA_R_16BF

MACA_C_16F

MACA_C_32F

MACA_C_16BF

mcsparseRot() 有以下约束条件：

表示稀疏向量 vecX 的数组必须按照16字节对齐

mcsparseRot() 具有以下特性：

此函数不需要额外的存储空间
此函数支持异步执行
如果稀疏向量 vecX 的索引是显著不同的，每次运行都会得到确定性(逐位)的结果

mcsparseRot() 支持以下优化：

硬件内存压缩(Hardware Memory Compression)

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.6.7. mcsparseSpVV()

mcsparseStatus_t
mcsparseSpVV_bufferSize(mcsparseHandle_t     handle,
                        mcsparseOperation_t  opX,
                        mcsparseSpVecDescr_t vecX,
                        mcsparseDnVecDescr_t vecY,
                        void*                result,
                        macaDataType         computeType,
                        size_t*              bufferSize)

mcsparseStatus_t
mcsparseSpVV(mcsparseHandle_t     handle,
               mcsparseOperation_t  opX,
               mcsparseSpVecDescr_t vecX,
               mcsparseDnVecDescr_t vecY,
               void*                result,
               macaDataType         computeType,
               void*                externalBuffer)

此函数计算稀疏向量 vecX 和稠密向量 vecY 的内积。

result = 0;
for i=0 to nnz-1
      result += X_values[i] * Y[X_indices[i]]

mcsparseSpVV_bufferSize() 函数返回 mcsparseSpVV() 所需的工作空间大小。

参数

内存

输入/输出

含义

handle

主机

输入

处理mcSPARSE库上下文的句柄

opX

主机

输入

操作类型 op(X) 可选非转置或共轭转置

vecX

主机

输入

稀疏向量 X

vecY

主机

输入

稠密向量 Y

result

主机或设备

输出

计算结果的点积

computeType

主机

输入

计算数据类型执行计算的类型

bufferSize

主机

输出

mcsparseSpVV 所需工作空间的字节数

externalBuffer

设备

输入

外部缓冲区的指针，至少为 bufferSize 字节大小的工作空间缓冲区

mcsparseSpVV 支持以下索引类型来表示稀疏向量 vecX ：

32位索引 (MCSPARSE_INDEX_32I)
64位索引 (MCSPARSE_INDEX_64I)

mcsparseSpVV 当前支持以下数据类型的组合：

统一精度计算：

X/Y/computeType

MACA_R_32F

MACA_R_64F

MACA_C_32F

MACA_C_64F

混合精度计算：

X/Y

computeType/ result

MACA_R_8I

MACA_R_32I

MACA_R_8I

MACA_R_32F

MACA_R_16F

MACA_R_16BF

MACA_C_16F

MACA_C_32F

MACA_C_16BF

mcsparseSpVV() 有以下约束条件：

表示稀疏向量 vecX 的数组必须按照16字节对齐

mcsparseSpVV() 具有以下特性：

此函数不需要额外的存储空间
此函数支持异步执行
如果稀疏向量 vecX 的索引是显著不同的，每次运行都会得到确定性(逐位)的结果

mcsparseSpVV() 支持以下优化：

硬件内存压缩(Hardware Memory Compression)

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.6.8. mcsparseSpMV()

mcsparseStatus_t
mcsparseSpMV_bufferSize(mcsparseHandle_t     handle,
                        mcsparseOperation_t  opA,
                        const void*          alpha,
                        mcsparseSpMatDescr_t matA,
                        mcsparseDnVecDescr_t vecX,
                        const void*          beta,
                        mcsparseDnVecDescr_t vecY,
                        macaDataType         computeType,
                        mcsparseSpMVAlg_t    alg,
                        size_t*              bufferSize)

mcsparseStatus_t
mcsparseSpMV(mcsparseHandle_t     handle,
               mcsparseOperation_t  opA,
               const void*          alpha,
               mcsparseSpMatDescr_t matA,
               mcsparseDnVecDescr_t vecX,
               const void*          beta,
               mcsparseDnVecDescr_t vecY,
               macaDataType         computeType,
               mcsparseSpMVAlg_t    alg,
               void*                externalBuffer)

此函数用于计算稀疏矩阵 matA 与稠密向量 vecX 的乘积。

函数 mcsparseSpMV_bufferSize() 返回 mcsparseSpMV() 所需的工作空间大小。

参数

内存

输入/输出

含义

handle

主机

输入

处理mcSPARSE库上下文的句柄

opA

主机

输入

操作符 op(A)

alpha

主机或设备

输入

用于 computeType 类型乘法的标量

matA

主机

输入

稀疏矩阵 A

vecX

主机

输入

稠密向量 X

beta

主机或设备

输入

用于 computeType 类型乘法的标量

vecY

主机

输入/输出

稠密向量 Y

computeType

主机

输入

计算执行的数据类型

alg

主机

输入

用于计算的算法

bufferSize

主机

输出

mcsparseSpMV 所需的工作空间大小以字节为单位

externalBuffer

设备

输入

指向至少大小为 bufferSize 字节的工作空间缓冲区的指针

目前支持的稀疏矩阵格式如下：

MCSPARSE_FORMAT_COO
MCSPARSE_FORMAT_CSR

mcsparseSpMV 支持以下索引类型来表示稀疏矩阵 matA ：

32位索引 (MCSPARSE_INDEX_32I)
64位索引 (MCSPARSE_INDEX_64I)

mcsparseSpMV 支持以下数据类型：

统一精度计算：

A/X/ Y/computeType

MACA_R_32F

MACA_R_64F

MACA_C_16F

MACA_C_16BF

MACA_C_32F

MACA_C_64F

混合精度计算：

A/ X

Y

computeType

MACA_R_8I

MACA_R_32I

MACA_R_32I

MACA_R_8I

MACA_R_32F

MACA_R_32F

MACA_R_16F

MACA_R_16BF

MACA_R_16F

MACA_R_16F

MACA_R_16BF

MACA_R_16BF

混合常规/复数计算：

A

X/ Y/ computeType

MACA_R_32F

MACA_C_32F

MACA_R_64F

MACA_C_64F

mcsparseSpMV() 支持以下算法:

Algorithm

Notes

MCSPARSE_MV_ALG_DEFAULT MCSPARSE_SPMV_ALG_DEFAULT

适用于任何稀疏矩阵格式的默认算法

MCSPARSE_COOMV_ALG MCSPARSE_SPMV_COO_ALG1

COO稀疏矩阵格式的默认算法可能在相同输入参数下，不同运行产生稍微不同的结果

MCSPARSE_SPMV_COO_ALG2

每次运行提供确定性(逐位)结果如果 opA != MCSPARSE_ OPERATION_NON_TRANSPOSE，则与 MCSPARSE_SPMV_COO_ALG1 相同

MCSPARSE_CSRMV_ALG1 MCSPARSE_SPMV_CSR_ALG1

CSR稀疏矩阵格式的默认算法可能在相同输入参数下，不同运行产生稍微不同的结果

MCSPARSE_CSRMV_ALG2 MCSPARSE_SPMV_CSR_ALG2

每次运行提供确定性(逐位)结果如果 opA != MCSPARSE_ OPERATION_NON_TRANSPOSE，则与 MCSPARSE_SPMV_COO_ALG1 相同

性能注意事项：

MCSPARSE_SPMV_COO_ALG1 和 MCSPARSE_SPMV_CSR_ALG1 比 MCSPARSE_SPMV_COO_ALG2 和 MCSPARSE_SPMV_CSR_ALG2 具有更高的性能。
一般而言， opA == MCSPARSE_OPERATION_NON_TRANSPOSE 相对于 opA != MCSPARSE_OPERATION_NON_TRANSPOSE 具有3倍的速度优势。

mcsparseSpMV() 具有以下特性：

该例程在CSR格式(所有算法)和COO格式中需要额外的存储空间，其中COO格式使用 MCSPARSE_SPMM_COO_ALG2 算法。
仅对于 MCSPARSE_SPMM_COO_ALG2 和 MCSPARSE_SPMM_CSR_ALG2 算法，以及 opA == MCSPARSE_OPERATION_NON_TRANSPOSE 情况下，提供每次运行的确定性(按位)结果。
该例程支持异步执行。

mcsparseSpMV() 支持以下优化：

硬件内存压缩(Hardware Memory Compression)

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.6.9. mcsparseSpSV()

mcsparseStatus_t
mcsparseSpSV_createDescr(mcsparseSpSVDescr_t* spsvDescr);

mcsparseStatus_t
mcsparseSpSV_destroyDescr(mcsparseSpSVDescr_t spsvDescr);

mcsparseStatus_t
mcsparseSpSV_bufferSize(mcsparseHandle_t     handle,
                        mcsparseOperation_t  opA,
                        const void*          alpha,
                        mcsparseSpMatDescr_t matA,
                        mcsparseDnVecDescr_t vecX,
                        mcsparseDnVecDescr_t vecY,
                        macaDataType         computeType,
                        mcsparseSpSVAlg_t    alg,
                        mcsparseSpSVDescr_t  spsvDescr,
                        size_t*              bufferSize)

mcsparseStatus_t
mcsparseSpSV_analysis(mcsparseHandle_t     handle,
                        mcsparseOperation_t  opA,
                        const void*          alpha,
                        mcsparseSpMatDescr_t matA,
                        mcsparseDnVecDescr_t vecX,
                        mcsparseDnVecDescr_t vecY,
                        macaDataType         computeType,
                        mcsparseSpSVAlg_t    alg,
                        mcsparseSpSVDescr_t  spsvDescr
                        void*                externalBuffer)

mcsparseStatus_t
mcsparseSpSV_solve(mcsparseHandle_t     handle,
                     mcsparseOperation_t  opA,
                     const void*          alpha,
                     mcsparseSpMatDescr_t matA,
                     mcsparseDnVecDescr_t vecX,
                     mcsparseDnVecDescr_t vecY,
                     macaDataType         computeType,
                     mcsparseSpSVAlg_t    alg,
                     mcsparseSpSVDescr_t  spsvDescr)

此函数用于求解一个线性方程组，其系数用稀疏三角形矩阵表示。

函数 mcsparseSpSV_bufferSize() 返回 mcsparseSpSV_analysis() 和 mcsparseSpSV_solve() 所需的工作空间大小。函数 mcsparseSpSV_analysis() 执行分析阶段，而 mcsparseSpSV_solve() 执行稀疏三角形线性系统的求解阶段。不透明数据结构 spsvDescr 用于在所有函数之间共享信息。

该例程支持输入矩阵的任意稀疏性，但计算时只考虑上三角或下三角部分。

mcsparseSpSV API 调用中的所有参数必须一致，并且不得在 mcsparseSpSV_analysis() 和 mcsparseSpSV_solve() 之间修改矩阵描述。

参数

内存

输入/输出

含义

handle

主机

输入

处理MCSPARSE库上下文句柄

opA

主机

输入

操作 op(A)

alpha

主机或设备

输入

用于 computeType 类型乘法的标量

matA

主机

输入

稀疏矩阵 A

vecX

主机

输入

稠密矢量 X

vecY

主机

输入/输出

密集矢量 Y

computeType

主机

输入

执行计算的数据类型

alg

主机

输入

计算算法

bufferSize

主机

输出

mcsparseSpSV_ analysis() 和 mcsparseSpSV _solve() 所需的工作空间字节数

ex ternalBuffer

设备

输入

工作区缓冲区的指针，其大小至少为 bufferSize 字节。它被 mcsparse SpSV_analysis 和 mcsparse SpSV_solve() 使用。

spsvDescr

主机

输入/输出

不透明描述符，用于存储三个步骤中使用的内部数据

目前支持的稀疏矩阵格式如下：

MCSPARSE_FORMAT_CSR
MCSPARSE_FORMAT_COO

mcsparseSpSV() 支持以下类型和属性：

MCSPARSE_FILL_MODE_LOWER 和 MCSPARSE_FILL_MODE_UPPER 填充模式
MCSPARSE_DIAG_TYPE_NON_UNIT 和 MCSPARSE_DIAG_TYPE_UNIT 对角线类型

mcsparseSpSV() 支持以下索引类型来表示稀疏矩阵 matA：

32-bit indices (MCSPARSE_INDEX_32I)
64-bit indices (MCSPARSE_INDEX_64I)

mcsparseSpSV() 支持以下数据类型：

统一精度计算：

A/X/ Y/computeType

MACA_R_32F

MACA_R_64F

MACA_C_32F

MACA_C_64F

mcsparseSpSV() 支持以下算法：

算法注记

MCSPARSE_SPSV_ALG_DEFAULT

默认算法

mcsparseSpSV() 具有以下属性：

该例程在分析阶段需要额外的存储空间，该存储空间大小与稀疏矩阵的非零条目数量成正比
为求解阶段 mcsparseSpSV_solve() 的每次运行提供确定性(按位)结果
该例程支持异步执行

mcsparseSpSV() 支持以下优化：

硬件内存压缩

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.6.10. mcsparseSpMM()

mcsparseStatus_t
mcsparseSpMM_bufferSize(mcsparseHandle_t     handle,
                        mcsparseOperation_t  opA,
                        mcsparseOperation_t  opB,
                        const void*          alpha,
                        mcsparseSpMatDescr_t matA,
                        mcsparseDnMatDescr_t matB,
                        const void*          beta,
                        mcsparseDnMatDescr_t matC,
                        macaDataType         computeType,
                        mcsparseSpMMAlg_t    alg,
                        size_t*              bufferSize)

mcsparseStatus_t
mcsparseSpMM_preprocess(mcsparseHandle_t      handle,
                        mcsparseOperation_t   opA,
                        mcsparseOperation_t   opB,
                        const void*           alpha,
                        mcsparseSpMatDescr_t  matA,
                        mcsparseDnMatDescr_t  matB,
                        const void*           beta,
                        mcsparseDnMatDescr_t  matC,
                        macaDataType          computeType,
                        mcsparseSpMMAlg_t     alg,
                        void*                 externalBuffer)

mcsparseStatus_t
mcsparseSpMM(mcsparseHandle_t     handle,
               mcsparseOperation_t  opA,
               mcsparseOperation_t  opB,
               const void*          alpha,
               mcsparseSpMatDescr_t matA,
               mcsparseDnMatDescr_t matB,
               const void*          beta,
               mcsparseDnMatDescr_t matC,
               macaDataType         computeType,
               mcsparseSpMMAlg_t    alg,
               void*                externalBuffer)

此函数执行稀疏矩阵 matA 和稠密矩阵 matB 的乘法运算。

通过切换稠密矩阵的布局，该例程还可用于执行稠密矩阵 matB 和稀疏矩阵 matA 的乘法运算。

函数 mcsparseSpMM_bufferSize() 返回 mcsparseSpMM() 所需的工作空间大小。 mcsparseSpMM_preprocess() 函数可以在 mcsparseSpMM 之前调用，以加快实际计算速度。当使用相同的稀疏性模式( matA)多次调用 mcsparseSpMM 时，它非常有用。稠密矩阵( matB, matC)的值可以任意变化。它需要 MCSPARSE_SPMM_CSR_ALG3。所有其他格式和算法均无效。

参数

内存

输入

含义

handle

主机

输入

处理MCSPARSE库上下文句柄

opA

主机

输入

操作 op(A)

opB

主机

输入

操作 op(A)

alpha

主机或设备

输入输入

用于 computeType 类型乘法的标量

matA

主机

输入

稀疏矩阵 A

matB

主机

输入

稠密矩阵 B

beta

主机或设备

输入

用于 computeType 类型乘法的标量

matC

主机

输入/输出

稠密矩阵 C

computeType

主机

输入

执行计算的数据类型

alg

主机

输入

计算算法

bufferSize

主机

输出

mcsparseSpMM 需要的工作空间字节数

ex ternalBuffer

设备

输入

工作区缓冲区的指针，其大小至少为 bufferSize 字节。

14.6.11. mcsparseSpSM()

mcsparseStatus_t
mcsparseSpSM_createDescr(mcsparseSpSMDescr_t* spsmDescr);

mcsparseStatus_t
mcsparseSpSM_destroyDescr(mcsparseSpSMDescr_t spsmDescr);

mcsparseStatus_t
mcsparseSpSM_bufferSize(mcsparseHandle_t     handle,
                        mcsparseOperation_t  opA,
                        mcsparseOperation_t  opB,
                        const void*          alpha,
                        mcsparseSpMatDescr_t matA,
                        mcsparseDnMatDescr_t matB,
                        mcsparseDnMatDescr_t matC,
                        macaDataType         computeType,
                        mcsparseSpSMAlg_t    alg,
                        mcsparseSpSMDescr_t  spsmDescr,
                        size_t*              bufferSize)

mcsparseStatus_t
mcsparseSpSM_analysis(mcsparseHandle_t     handle,
                        mcsparseOperation_t  opA,
                        mcsparseOperation_t  opB,
                        const void*          alpha,
                        mcsparseSpMatDescr_t matA,
                        mcsparseDnMatDescr_t matB,
                        mcsparseDnMatDescr_t matC,
                        macaDataType         computeType,
                        mcsparseSpSMAlg_t    alg,
                        mcsparseSpSMDescr_t  spsmDescr,
                        void*                externalBuffer)

mcsparseStatus_t
mcsparseSpSM_solve(mcsparseHandle_t     handle,
                     mcsparseOperation_t  opA,
                     mcsparseOperation_t  opB,
                     const void*          alpha,
                     mcsparseSpMatDescr_t matA,
                     mcsparseDnMatDescr_t matB,
                     mcsparseDnMatDescr_t matC,
                     macaDataType         computeType,
                     mcsparseSpSMAlg_t    alg,
                     mcsparseSpSMDescr_t  spsmDescr)

此函数求解一个线性方程组，该方程组的系数用稀疏三角矩阵表示。

函数 mcsparseSpSM_bufferSize() 返回 mcsparseSpSM_analysis() 和 mcsparseSpSM_solve() 所需工作空间的大小。函数 mcsparseSpSM_analysis() 执行分析阶段，而 mcsparseSpSM_solve() 执行稀疏三角线性系统的求解阶段。不透明数据结构 spsmDescr 用于在所有函数之间共享信息。

该例程支持输入矩阵的任意稀疏性，但在计算中只考虑上或下三角部分。 mcsparseSpSM_bufferSize() 要求分析阶段的缓冲区大小与稀疏矩阵的非零元素的数量成正比。

externalBuffer 被存储在 spsmDescr 中，并被 mcsparseSpSM_solve() 使用。因此，只有在 mcsparseSpSM_solve() 之后才能释放设备内存缓冲区。

备注

所有参数必须在 mcsparseSpSM API调用中保持一致，并且不得在 mcsparseSpSM_analysis() 和 mcsparseSpSM_solve() 之间之间不得修改矩阵描述。

参数	存储	输入/输出	含义
`handle`	主机	输入	处理mcSPARSE库上下文的句柄
`opA`	主机	输入	操作 `op(A)`
`opB`	主机	输入	操作 `op(B)`
`alpha`	主机或设备	输入	用于 `computeType` 类型乘法的标量
`matA`	主机	输入	稀疏矩阵 `A`
`matB`	主机	输入	稠密矩阵 `B`
`matC`	主机	输入/输出	稠密矩阵 `C`
`computeType`	主机	输入	执行计算的数据类型
`alg`	主机	输入	计算算法
`bufferSize`	主机	输出	`mcsparseSp SM_analysis()` 和 `mcsparse SpSM_solve()` 所需工作空间的字节数
`externalBuffer`	设备	输入	指向至少为 `bufferSize` 字节的工作区缓冲区的指针它由 `mcsparse SpSM_analysis` 和 `mcsparse SpSM_solve()` 使用
`spsmDescr`	主机	输入/输出	用于存储跨三个步骤使用的内部数据的不透明描述符

目前支持的稀疏矩阵格式如下：

MCSPARSE_FORMAT_CSR
MCSPARSE_FORMAT_COO

mcsparseSpSM() 支持以下形状和属性：

MCSPARSE_FILL_MODE_LOWER 和 MCSPARSE_FILL_MODE_UPPER 填充模式
MCSPARSE_DIAG_TYPE_NON_UNIT 和 MCSPARSE_DIAG_TYPE_UNIT 对角线类型

填充模式和对角线类型可以通过mcsparseSpMatSetAttribute()来设置

mcsparseSpSM() 支持以下索引类型表示稀疏矩阵 matA：

32位索引(MCSPARSE_INDEX_32I)
64位索引(MCSPARSE_INDEX_64I)

mcsparseSpSM() 支持以下数据类型：

统一精度计算：

A/B/ C/computeType

MACA_R_32F

MACA_R_64F

MACA_C_32F

MACA_C_64F

mcsparseSpSM() 支持以下算法：

算法注记

MCSPARSE_SPSM_ALG_DEFAULT

默认算法

mcsparseSpSM() 具有以下特性：

该例程不需要额外的存储空间
对于求解阶段的每次运行，提供确定性(按位)结果的 mcsparseSpSM_solve() 函数
该例程支持异步执行
硬件内存压缩

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.6.12. mcsparseSDDMM()

mcsparseStatus_t
mcsparseSDDMM_bufferSize(mcsparseHandle_t     handle,
                           mcsparseOperation_t  opA,
                           mcsparseOperation_t  opB,
                           const void*          alpha,
                           mcsparseDnMatDescr_t matA,
                           mcsparseDnMatDescr_t matB,
                           const void*          beta,
                           mcsparseSpMatDescr_t matC,
                           macaDataType         computeType,
                           mcsparseSDDMMAlg_t   alg,
                           size_t*              bufferSize)

mcsparseStatus_t
mcsparseSDDMM_preprocess(mcsparseHandle_t     handle,
                           mcsparseOperation_t  opA,
                           mcsparseOperation_t  opB,
                           const void*          alpha,
                           mcsparseDnMatDescr_t matA,
                           mcsparseDnMatDescr_t matB,
                           const void*          beta,
                           mcsparseSpMatDescr_t matC,
                           macaDataType         computeType,
                           mcsparseSDDMMAlg_t   alg,
                           void*                externalBuffer)

mcsparseStatus_t
mcsparseSDDMM(mcsparseHandle_t     handle,
               mcsparseOperation_t  opA,
               mcsparseOperation_t  opB,
               const void*          alpha,
               mcsparseDnMatDescr_t matA,
               mcsparseDnMatDescr_t matB,
               const void*          beta,
               mcsparseSpMatDescr_t matC,
               macaDataType         computeType,
               mcsparseSDDMMAlg_t   alg,
               void*                externalBuffer)

此函数执行 matA 和 matB 的乘法运算，然后执行 matC 的稀疏模式的元素乘法。

函数 mcsparseSDDMM_bufferSize() 返回 mcsparseSDDMM 或 mcsparseSDDMM_preprocess 所需工作空间的大小。

mcsparseSDDMM_preprocess() 函数可以在 mcsparseSDDMM 之前被调用来加速实际计算。当使用相同的稀疏模式(matC)多次调用 mcsparseSDDMM 时，这将非常有用。稠密矩阵(matA， matB)的值可以任意更改。

参数

存储

输入/输出

含义

handle

主机

输入

处理mcSPARSE库上下文的句柄

opA

主机

输入

操作 op(A)

opB

主机

输入

操作 op(B)

alpha

主机 or 设备

输入

用于 computeType 类型乘法的标量。

matA

主机

输入

稠密矩阵 matA

matB

主机

输入

稠密矩阵 matB

beta

主机 or 设备

输入

用于 computeType 类型乘法的标量。

matC

主机

输入/输出

稀疏矩阵 matC

computeType

主机

输入

执行计算的数据类型。

alg

主机

输入

计算算法

bufferSize

主机

输出

mcsparseSDDMM所需工作空间的字节数。

ex ternalBuffer

设备

输入

指向至少为 bufferSize 字节的工作区缓冲区的指针

目前支持的稀疏矩阵格式：

MCSPARSE_FORMAT_CSR

mcsparseSpSV() 支持以下索引类型来表示稀疏矩阵 matA ：

32位索引(MCSPARSE_INDEX_32I)
64位索引(MCSPARSE_INDEX_64I)

mcsparseSDDMM 目前支持的数据类型组合如下：

统一精度计算：

A/X/ Y/computeType

MACA_R_32F

MACA_R_64F

MACA_C_32F

MACA_C_64F

mcsparseSpSV() 支持以下算法：

算法注记

MCSPARSE_SDDMM_ALG_DEFAULT

默认算法

mcsparseSDDMM() 具有以下属性：

该例程不需要额外的存储空间
为每次运行提供确定的(按位)结果
例程支持异步执行

mcsparseSDDMM() 支持以下优化：

硬件内存压缩

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.6.13. mcsparseSpGEMM()

mcsparseStatus_t
mcsparseSpGEMM_createDescr(mcsparseSpGEMMDescr_t* descr)

mcsparseStatus_t
mcsparseSpGEMM_destroyDescr(mcsparseSpGEMMDescr_t descr)

mcsparseStatus_t
mcsparseSpGEMM_workEstimation(mcsparseHandle_t      handle,
                              mcsparseOperation_t   opA,
                              mcsparseOperation_t   opB,
                              const void*           alpha,
                              mcsparseSpMatDescr_t  matA,
                              mcsparseSpMatDescr_t  matB,
                              const void*           beta,
                              mcsparseSpMatDescr_t  matC,
                              macaDataType          computeType,
                              mcsparseSpGEMMAlg_t   alg,
                              mcsparseSpGEMMDescr_t spgemmDescr,
                              size_t*               bufferSize1,
                              void*                 externalBuffer1)

mcsparseStatus_t
mcsparseSpGEMM_compute(mcsparseHandle_t      handle,
                        mcsparseOperation_t   opA,
                        mcsparseOperation_t   opB,
                        const void*           alpha,
                        mcsparseSpMatDescr_t  matA,
                        mcsparseSpMatDescr_t  matB,
                        const void*           beta,
                        mcsparseSpMatDescr_t  matC,
                        macaDataType          computeType,
                        mcsparseSpGEMMAlg_t   alg,
                        mcsparseSpGEMMDescr_t spgemmDescr,
                        void*                 externalBuffer1,
                        size_t*               bufferSize2,
                        void*                 externalBuffer2)

mcsparseStatus_t
mcsparseSpGEMM_copy(mcsparseHandle_t      handle,
                     mcsparseOperation_t   opA,
                     mcsparseOperation_t   opB,
                     const void*           alpha,
                     mcsparseSpMatDescr_t  matA,
                     mcsparseSpMatDescr_t  matB,
                     const void*           beta,
                     mcsparseSpMatDescr_t  matC,
                     macaDataType          computeType,
                     mcsparseSpGEMMAlg_t   alg,
                     mcsparseSpGEMMDescr_t spgemmDescr)

此函数执行两个稀疏矩阵 matA 和 matB 的乘法运算。

函数 mcsparseSpGEMM_workEstimation() 和 mcsparseSpGEMM_compute() 被用于确定缓冲区大小和执行实际计算。

参数

内存

输入/输出

含义

handle

主机

输入

处理mcSPARSE库上下文句柄

opA

主机

输入

操作 op(A)

opB

主机

输入

操作 op(B)

alpha

主机或设备

输入

用于乘法的标量

matA

主机

输入

稀疏矩阵 A

matB

主机

输入

稀疏矩阵 B

beta

主机或设备

输入

用于乘法的标量

matC

主机

输入/输出

稀疏矩阵 C

computeType

主机

输入

枚举器，指定计算执行时使用的数据类型

alg

主机

输入

枚举器，指定计算所用算法。

spgemmDescr

主机

输入/输出

不透明描述符，用于存储在三个步骤之间使用的内部数据。

bufferSize1

主机

输入/输出

由 mcsparseSpGEMM_workEstimation 请求的工作空间字节数。

bufferSize2

主机

输入/输出

由 mcsparseS pGEMM_compute 请求的工作空间字节数。

ex ternalBuffer1

设备

输入

mcsparseSpGEMM_workEstimation 和 mcsparseSpGEMM_compute 需要的工作空间缓冲区指针。

ex ternalBuffer2

设备

输入

mcsparseSpGEMM_compute 和 mcsparseSpGEMM_copy 需要的工作空间缓冲区指针。

内存需求：第一次调用 mcsparseSpGEMM_compute 时会提供计算所需内存的上限，通常是实际使用内存的几倍大。用户可以在第二次调用时提供任意大小的缓冲区 bufferSize2。如果内存大小不足，该例程将返回 MCSPARSE_STATUS_INSUFFICIENT_RESOURCES 状态。

目前，此函数具有以下限制：

只支持32位索引 MCSPARSE_INDEX_32I
只支持CSR格式 MCSPARSE_FORMAT_CSR
只支持 opA 和 opB 等于 MCSPARSE_OPERATION_NON_TRANSPOSE 的情况。

目前支持 mcsparseSpGEMM 函数的数据类型组合如下：

均匀精度计算：

A/B/ C/computeType

MACA_R_16F

MACA_R_16BF

MACA_R_32F

MACA_R_64F

MACA_C_16F

MACA_C_16BF

MACA_C_32F

MACA_C_64F

mcsparseSpGEMM 例程运行以下算法：

算法

注释

MCSPARSE_SPGEMM_DEFAULT

默认算法。为每次运行提供确定性(位级别)的结果。

mcsparseSpGEMM() 具有以下特性：

这个例程不需要额外的存储空间。
这个例程支持异步执行。

mcsparseSpGEMM() 支持以下优化：

硬件内存压缩。

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。

14.6.14. mcsparseSpGEMMreuse()

mcsparseStatus_t
mcsparseSpGEMM_createDescr(mcsparseSpGEMMDescr_t* descr)

mcsparseStatus_t
mcsparseSpGEMM_destroyDescr(mcsparseSpGEMMDescr_t descr)

mcsparseStatus_t
mcsparseSpGEMMreuse_workEstimation(mcsparseHandle_t      handle,
                                    mcsparseOperation_t   opA,
                                    mcsparseOperation_t   opB,
                                    mcsparseSpMatDescr_t  matA,
                                    mcsparseSpMatDescr_t  matB,
                                    mcsparseSpMatDescr_t  matC,
                                    mcsparseSpGEMMAlg_t   alg,
                                    mcsparseSpGEMMDescr_t spgemmDescr,
                                    size_t*               bufferSize1,
                                    void*                 externalBuffer1)

mcsparseStatus_t
mcsparseSpGEMMreuse_nnz(mcsparseHandle_t      handle,
                        mcsparseOperation_t   opA,
                        mcsparseOperation_t   opB,
                        mcsparseSpMatDescr_t  matA,
                        mcsparseSpMatDescr_t  matB,
                        mcsparseSpMatDescr_t  matC,
                        mcsparseSpGEMMAlg_t   alg,
                        mcsparseSpGEMMDescr_t spgemmDescr,
                        size_t*               bufferSize2,
                        void*                 externalBuffer2,
                        size_t*               bufferSize3,
                        void*                 externalBuffer3,
                        size_t*               bufferSize4,
                        void*                 externalBuffer4)

mcsparseStatus_t MCSPARSEAPI
mcsparseSpGEMMreuse_copy(mcsparseHandle_t      handle,
                           mcsparseOperation_t   opA,
                           mcsparseOperation_t   opB,
                           mcsparseSpMatDescr_t  matA,
                           mcsparseSpMatDescr_t  matB,
                           mcsparseSpMatDescr_t  matC,
                           mcsparseSpGEMMAlg_t   alg,
                           mcsparseSpGEMMDescr_t spgemmDescr,
                           size_t*               bufferSize5,
                           void*                 externalBuffer5)

mcsparseStatus_t MCSPARSEAPI
mcsparseSpGEMMreuse_compute(mcsparseHandle_t      handle,
                              mcsparseOperation_t   opA,
                              mcsparseOperation_t   opB,
                              const void*           alpha,
                              mcsparseSpMatDescr_t  matA,
                              mcsparseSpMatDescr_t  matB,
                              const void*           beta,
                              mcsparseSpMatDescr_t  matC,
                              macaDataType          computeType,
                              mcsparseSpGEMMAlg_t   alg,
                              mcsparseSpGEMMDescr_t spgemmDescr)

此函数执行两个稀疏矩阵 matA 和 matB 的乘法运算，其中输出矩阵 matC 的结构可重复用于不同值的多次计算。

函数 mcsparseSpGEMMreuse_workEstimation()， mcsparseSpGEMMreuse_nnz() 和 mcsparseSpGEMMreuse_copy() 用于确定缓冲区大小和执行实际计算。

参数	内存	输入/输出	描述
`handle`	主机	输入	处理mcSPARSE库上下文的句柄。
`opA`	主机	输入	操作 `op(A)`
`opB`	主机	输入	操作 `op(B)`
`alpha`	主机或设备	输入	用于乘法的标量
`matA`	主机	输入	稀疏矩阵 `A`
`matB`	主机	输入	稀疏矩阵 `B`
`beta`	主机或设备	输入	用于乘法的标量
`matC`	主机	输入/输出	稀疏矩阵 `C`
`computeType`	主机	输入	枚举器，指定计算执行的数据类型。
`alg`	主机	输入	枚举器，指定计算的算法。
`spgemmDescr`	主机	输入/输出	用于存储跨三个步骤使用的内部数据的不透明描述符。
`bufferSize1`	主机	输入/输出	`mcsparseSpGEMMreuse_workEstimation` 所需的工作空间字节数。
`bufferSize2` `bufferSize3` `bufferSize4`	主机	输入/输出	`mcsparseSpGEMMreuse_nnz` 所需的工作空间字节数。
`bufferSize5`	主机	输入/输出	`mcsparseSpGEMMreuse_copy` 所需的工作空间的字节数。
`externalBuffer1`	设备	输入	`mcsparseSpGEMMreuse_workEstimation` 和 `mcsparseSpGEMMreuse_nnz` 所需的工作空间的字节数。
`externalBuffer2`	设备	输入	`mcsparseSpGEMMreuse_nnz` 所需的工作空间的字节数。
`externalBuffer3`	设备	输入	`mcsparseSpGEMMreuse_nnz` 和 `mcsparseSpGEMMreuse_copy` 所需的工作空间的字节数。
`externalBuffer4`	设备	输入	`mcsparseSpGEMMreuse_nnz` 和 `mcsparseSpGEMMreuse_compute` 所需的工作空间的字节数。
`externalBuffer5`	设备	输入	指向 `mcsparseSpGEMMreuse_copy` 和 `mcsparseSpGEMMreuse_compute` 所需的工作空间缓冲区的指针。

内存需求： mcsparseSpGEMMreuse 需要将所有中间乘积保留在内存中，以便重复使用输出矩阵的结构。另一方面，一般情况下，中间乘积的数量比非零元素的数量高出几个数量级。为了最小化内存需求，该例程使用多个缓冲区，这些缓冲区可以在不再需要时可以释放。如果中间产品的数量超过 2^31-1，该例程将返回 MCSPARSE_STATUS_INSUFFICIENT_RESOURCES 状态。

目前，此函数有以下限制：

仅支持32位索引 MCSPARSE_INDEX_32I。
仅支持CSR格式 MCSPARSE_FORMAT_CSR。
仅支持 opA 和 opB 等于 MCSPARSE_OPERATION_NON_TRANSPOSE。

目前支持的 mcsparseSpGEMMreuse 的数据类型组合如下：

统一精度计算：

A/B/ C/computeType

MACA_R_32F

MACA_R_64F

MACA_C_16F

MACA_C_16BF

MACA_C_32F

MACA_C_64F

混合精度计算：

A/B

C

computeType

MACA_R_16F

MACA_R_16F

MACA_R_32F

MACA_R_16BF

MACA_R_16BF

MACA_R_32F

mcsparseSpGEMMreuse 例程运行以下算法：

Algorithm

注释

MCSPARSE_SPGEMM_DEFAULT

MCSPARSE_SPGEMM_CSR_ALG_ NONDETERMINITIC

默认算法。为每次运行提供确定性(位级) 的输出矩阵结构，但值的算不是确定性的。

MCSPARSE_SPGEMM_CSR_ALG_ DETERMINITIC

为每次运行提供确定性(位级)结构的输出矩阵和值计算。

mcsparseSpGEMMreuse() 具有以下特性：

该例程不需要额外的存储空间。
该例程支持异步执行。

mcsparseSpGEMMreuse() 支持以下优化：

硬件内存压缩。

有关返回状态的描述，请参见 4.2 mcsparseStatus_t。