4. mcSPARSE类型参考

4.1. 数据类型

支持 float、 double、 mcComplex 和 mcDoubleComplex 数据类型。前两个是标准的C数据类型，而后两个是从 mcComplex.h 导出的。

4.2. mcsparseStatus_t

这种数据类型表示库函数返回的状态，其值如下：

值	含义
MCSPARSE_STATUS_SUCCESS	成功完成操作。
MCSPARSE_STATUS_NOT_INITIALIZED	mcSPARSE库未初始化。这通常是由于缺少先前调用、mcSPARSE例程调用 MXMACA Runtime API发生错误，或者硬件设置错误。纠正方法：在函数调用之前调用 `mcsparseCreate()`；并检查硬件、相应版本的驱动程序以及mcSPARSE库是否正确安装。该错误也适用于通用API，用于指示矩阵/向量描述符未初始化。
MCSPARSE_STATUS_ALLOC_FAILED	mcSPARSE库内部资源分配失败。通常是由于设备内存分配( `mcMalloc()`) 或主机内存分配失败。纠正方法：在函数调用之前，尽可能地释放以前分配的内存。
MCSPARSE_STATUS_INVALID_VALUE	传递了一个无效值或参数(例如负的向量大小)给函数。纠正方法：确保传递的所有参数都具有有效值。
MCSPARSE_STATUS_EXECUTION_FAILED	GPU程序执行失败。这通常是由于GPU 核启动失败，失败可能由多种原因导致。纠正方法：检查硬件、相应版本的驱动程序及mcSPARSE库是否正确安装
MCSPARSE_STATUS_INTERNAL_ERROR	mcSPARSE内部操作失败。纠正方法：检查硬件、相应版本的驱动程序以及mcSPARSE库是否正确安装。同时检查是否在例程完成之前释放作为参数传递给例程的内存。
MCSPARSE_STATUS_MATRIX_TYPE_NOT_ SUPPORTED	矩阵类型不受此函数支持。通常是由于向函数传递了无效的矩阵描述符。纠正方法：检查 `mcsparseMatDescr_t descrA` 中的字段是否设置正确。
MCSPARSE_STATUS_NOT_SUPPORTED	该操作或数据类型组合不受此函数支持。
MCSPARSE_STATUS_INSUFFICIENT_ RESOURCES	计算的资源。

4.3. mcsparseHandle_t

这是一个指向不透明mcSPARSE上下文的指针类型，用户必须在调用其他库函数之前通过调用 mcsparseCreate() 来初始化。 mcsparseCreate() 创建并返回的句柄必须传递给每个mcSPARSE函数。

4.4. mcsparsePointerMode_t

此类型指示标量值是在主机上还是设备上通过引用传递。需要指出的是，如果在函数调用中通过引用传递了多个标量值，则所有标量值都将符合相同的单指针模式。指针模式可以分别使用 mcsparseSetPointerMode() 和 mcsparseGetPointerMode() 例程进行设置和检索。

值	含义
`MCSPARSE_POINTER_MODE_HOST`	标量值是在主机上通过引用传递。
`MCSPARSE_POINTER_MODE_DEVICE`	标量值是在设备上通过引用传递。

4.5. mcsparseOperation_t

此类型指示需要对稀疏矩阵执行哪些操作。

值	含义
`MCSPARSE_OPERATION_NON_ TRANSPOSE`	选择了非转置操作。
`MCSPARSE_OPERATION_TRANSPOSE`	选择了转置操作。
`MCSPARSE_OPERATION_CONJUGATE_ TRANSPOSE`	选择了共轭转置操作。

4.6. mcsparseAction_t

此类型指示操作是仅对索引进行，还是对数据和索引同时进行。

值	含义
`MCSPARSE_ACTION_SYMBOLIC`	操作仅在索引上执行。
`MCSPARSE_ACTION_NUMERIC`	操作同时在数据和索引上执行。

4.7. mcsparseDirection_t

此类型指示在函数 mcsparse[S|D|C|Z]nnz 中，稠密矩阵的元素是按行解析，还是按列解析（假设稠密矩阵按列主序存储在内存中）。此外，BSR格式中块的存储格式也受此类型控制。

值	含义
`MCSPARSE_DIRECTION_ROW`	矩阵应该按行解析。
`MCSPARSE_DIRECTION_COLUMN`	矩阵应该按列解析。

4.8. mcsparseMatDescr_t

此结构体用于描述矩阵的形状和特性。

typedef struct {
      mcsparseMatrixType_t MatrixType;
      mcsparseFillMode_t FillMode;
      mcsparseDiagType_t DiagType;
      mcsparseIndexBase_t IndexBase;
} mcsparseMatDescr_t;

4.8.1. mcsparseDiagType_t

此类型指示矩阵的对角元素是否为1。假定对角元素始终存在。如果将 MCSPARSE_DIAG_TYPE_UNIT 传递给API例程，则例程就会假定所有对角线元素都为1，并且不会读取或修改这些元素。请注意，在这种情况下，例程假定对角线元素等于1，而不管这些元素在内存中实际上被设置为何值。

值	含义
`MCSPARSE_DIAG_TYPE_NON_UNIT`	矩阵的对角线上具有非单位元素。
`MCSPARSE_DIAG_TYPE_UNIT`	矩阵的对角线上具有单位元素。

4.8.2. mcsparseFillMode_t

此类型指示矩阵的下部分还是上部分存储在稀疏存储中。

值	含义
`MCSPARSE_FILL_MODE_LOWER`	存储了矩阵的下三角部分。
`MCSPARSE_FILL_MODE_UPPER`	存储了矩阵的上三角部分。

4.8.3. mcsparseIndexBase_t

此类型指示矩阵索引的基数是0还是1。

值	含义
`MCSPARSE_INDEX_BASE_ZERO`	基准索引是0。
`MCSPARSE_INDEX_BASE_ONE`	基准索引是1。

4.8.4. mcsparseMatrixType_t

此类型指示稀疏存储中所存储的矩阵类型。请注意，对于对称矩阵、厄米矩阵（Hermitian Matrix）和三角矩阵，只假定存储它们的下部分或上部分。

矩阵类型和填充模式的整体思想是为对称/厄米矩阵保持最小的存储，并利用 SpMV（稀疏矩阵向量乘）的对称属性。当 A 是对称矩阵且只存储下三角部分时，计算 y=A*x 需要两个步骤。第一步是计算 y=(L+D)*x，第二步是计算 y=L^T*x + y。考虑到转置操作 y=L^T*x 比非转置版本 y=L*x 慢10倍，对称特性并未表现出任何性能提升。对用户来说，最好将对称矩阵扩展为一般矩阵，并使用矩阵类型 MCSPARSE_MATRIX_TYPE_GENERAL 来计算 y=A*x。

一般来说，SpMV、预处理器（不完全Cholesky或不完全LU）和三角求解器通常会在迭代求解器中结合使用，例如PCG和GMRES。如果用户总是使用一般矩阵，而不是对称矩阵，则在预处理器中无需支持除一般矩阵外的其他矩阵类型。因此，新的例程 [bsr|csr]sv2 （三角求解器）、 [bsr|csr]ilu02 （不完全LU）和 [bsr|csr]ic02 （不完全Cholesky）只支持矩阵类型 MCSPARSE_MATRIX_TYPE_GENERAL。

值	含义
`MCSPARSE_MATRIX_TYPE_GENERAL`	矩阵是一般矩阵。
`MCSPARSE_MATRIX_TYPE_SYMMETRIC`	矩阵是对称矩阵。
`MCSPARSE_MATRIX_TYPE_HERMITIAN`	矩阵是厄米矩阵。
`MCSPARSE_MATRIX_TYPE_TRIANGULAR`	矩阵是三角矩阵。

4.9. mcsparseAlgMode_t

用于表示 mcsparseCsrmvEx() 和 mcsparseCsrmvEx_bufferSize() 函数的算法参数类型。

值	含义
`MCSPARSE_ALG_MERGE_PATH`	使用适用于不规则非零模式的负载平衡算法

4.10. mcsparseColorInfo_t

指向不透明结构体的指针类型，该结构体包含 csrcolor() 中使用的信息。

4.11. mcsparseSolvePolicy_t

此类型指示在使用 csrsv2, csric02, csrilu02, bsrsv2, bsric02 和 bsrilu02 时是否生成和使用层级信息。

值	含义
`MCSPARSE_SOLVE_POLICY_NO_LEVEL`	没有生成和使用层级信息。
`MCSPARSE_SOLVE_POLICY_USE_LEVEL`	生成和使用层级信息。

4.12. mcsparseBsrsv2Info_t

指向不透明结构体的指针类型，该结构体包含在 bsrsv2_bufferSize()、 bsrsv2_analysis() 和 bsrsv2_solve() 中使用的信息。

4.13. mcsparseCsrgemm2Info_t

指向不透明结构体的指针类型，该结构体包含在 csrgemm2_bufferSizeExt() 和 csrgemm2() 中使用的信息。

4.14. mcsparseCsric02Info_t

指向不透明结构体的指针类型，该结构体包含在 csric02_bufferSize()、 csric02_analysis() 和 csric02() 中使用的信息。

4.15. mcsparseCsrilu02Info_t

指向不透明结构体的指针类型，该结构体包含在 csrilu02_bufferSize()、 csrilu02_analysis() 和 csrilu02() 中使用的信息。

4.16. mcsparseCsrsm2Info_t

指向不透明结构体的指针类型，该结构体包含在 csrsm2_bufferSize()、 csrsm2_analysis() 和 csrsm2_solve() 中使用的信息。

4.17. mcsparseCsrsv2Info_t

指向不透明结构体的指针类型，该结构体包含在 csrsv2_bufferSize()、 csrsv2_analysis() 和 csrsv2_solve() 中使用的信息。