cuDSS 数据类型

不透明数据结构

cudssHandle_t

该结构体保存 cuDSS 库上下文（设备属性、系统信息、执行控制，如 cudaStream_t 等）。

在调用任何其他 cuDSS API 之前，必须使用 cudssCreate() 初始化句柄。在使用 cuDSS 后，必须使用 cudssDestroy() 销毁句柄以释放资源。

---

cudssMatrix_t

该结构体是围绕标准稠密/稀疏矩阵参数的轻量级封装器，不拥有任何数据数组。矩阵对象用于传递线性系统的矩阵，以及解和右手边（即使这些实际上是向量）。目前，cuDSS 矩阵对象可以具有以下两种底层矩阵格式之一：稠密和 3 数组 CSR（稀疏）。

矩阵对象应通过 cudssMatrixCreateDn()（对于稠密矩阵）或 cudssMatrixCreateBatchDn()（对于一批稠密矩阵）或 cudssMatrixCreateCsr()（对于 CSR 格式的稀疏矩阵）或 cudssMatrixCreateBatchCsr()（对于一批 CSR 格式的稀疏矩阵）创建。使用后，矩阵对象应通过 cudssMatrixDestroy() 销毁。

矩阵对象可以在创建后通过 cudssMatrixSetValues() 和 cudssMatrixSetCsrPointers() 修改。

可以通过调用 cudssMatrixGetFormat()，然后根据返回的格式调用 cudssMatrixGetDn() 或 cudssMatrixGetCsr()，从矩阵对象中检索信息。

---

cudssData_t

该结构体保存内部数据（例如，与因子相关的数据结构）以及指向用户提供数据的指针。此类型的单个对象应与求解特定的线性系统相关联。如果连续求解具有相同数据类型（！）的多个系统，则可以重复使用该对象（所有必要的内部缓冲区将根据需要重新创建）。

注意：默认情况下，库会分配执行 LU 分解并在内部存储 LU 因子所需的设备内存。所有此类数据缓冲区都保存在数据对象内部。要更改此默认行为，可以设置一个 cudssDeviceMemHandler_t，然后将使用该处理程序在求解器内部分配设备内存。

该对象应通过 cudssDataCreate() 创建，并通过 cudssDataDestroy() 销毁。

在执行任何阶段 cudssExecute() 期间，求解器的配置设置从 cudssConfig_t 读取，因此会影响存储在 cudssData_t 对象中的执行和内部数据。

可以通过分别调用 cudssDataSet() 或 cudssDataGet() 来更新或检索数据参数。

---

cudssConfig_t

该结构体存储求解器的配置设置。此对象是围绕常见求解器设置的轻量级（主机端）封装器。虽然它可以重复用于求解不同的线性系统，但建议每个线性系统使用一个。

该对象应通过 cudssConfigCreate() 创建，并通过 cudssConfigDestroy() 销毁。

在执行任何阶段 cudssExecute() 期间，求解器的配置设置从 cudssConfig_t 读取，因此会影响执行。

可以通过分别调用 cudssConfigSet() 或 cudssConfigGet() 来更新或检索配置设置。注意：某些设置需要在执行相应的求解器阶段之前设置（例如，重排序算法必须在 CUDSS_PHASE_ANALYSIS 阶段之前设置）。

---

非不透明数据结构

cudssDeviceMemHandler_t

此结构体保存有关用户提供的、流排序的设备内存池 (mempool) 的信息。

可以通过设置下面描述的结构体成员来创建对象。

创建后，可以通过 cudssSetDeviceMemhandler() 为 cuDSS 库句柄设置设备内存处理程序。

为 cuDSS 库句柄设置后，可以通过 cudssGetDeviceMemhandler() 检索有关已设置的设备内存处理程序的信息。

成员

void *ctx

指向用户拥有的 mempool/上下文对象的指针。

int (*device_alloc)(void *ctx, void **ptr, size_t size, cudaStream_t stream)

指向用户提供的例程的函数指针，用于在 stream 上分配大小为 size 的设备内存。

分配的内存应可供当前设备访问（或更准确地说，可供绑定到库句柄的当前 CUDA 上下文访问）。

此接口支持任何流排序的内存分配器 ctx。成功后，分配的内存可以立即在给定流上被任何在此调用之后在同一流上排队/排序的操作使用。

调用者有责任确保建立正确的流顺序。

分配的内存应至少为 256 字节对齐。

参数	输入/输出	描述
ctx	输入	指向用户拥有的 mempool 对象的指针。
ptr	输出	成功时，指向已分配缓冲区的指针。
size	输入	要分配的内存量（以字节为单位）。
stream	输入	在其上分配内存的 CUDA 流（并且建立了流顺序）

返回调用错误状态（作为 int）。成功时必须返回 0，否则返回任何非零整数。

int (*device_free)(void *ctx, void *ptr, size_t size, cudaStream_t stream)

指向用户提供的例程的函数指针，用于在 stream 上释放大小为 size 的设备内存。

此接口支持任何流排序的内存分配器。成功后，在此调用之后排序的任何后续访问（由指针 ptr 指向的内存）都是未定义的行为。

调用者有责任确保建立正确的流顺序。

如果参数 ctx 和 size 与传递给 device_alloc 以分配指针 ptr 指向的内存的参数不同，则行为是未定义的。

参数 stream 不需要与用于分配 ptr 的流相同，只要正确建立流顺序即可。如果未满足此假设，则行为是未定义的。

参数	输入/输出	描述
ctx	输入	指向用户拥有的 mempool 对象的指针。
ptr	输入	指向已分配缓冲区的指针。
size	输入	已分配内存的大小。
stream	输入	在其上释放内存的 CUDA 流（并且建立了流顺序）。

返回调用错误状态（作为 int）。成功时必须返回 0，否则返回任何非零整数。

char name[CUDSS_ALLOCATOR_NAME_LEN]

提供的 mempool 的名称（不得超过 64 个字符）。

---

枚举器

cudssStatus_t

枚举器指定可能的状态值（在主机上），这些值可以从对 cuDSS 例程的调用中返回。

注意：设备端故障通过 cudssDataParam_t 中的 CUDSS_DATA_INFO 返回。

值	描述
CUDSS_STATUS_SUCCESS	操作已成功完成。
CUDSS_STATUS_NOT_INITIALIZED	其中一个输入操作数在调用 cuDSS 例程之前未正确初始化。这通常是诸如 cudssHandle_t、cudssData_t 或其他不透明对象之一。
CUDSS_STATUS_ALLOC_FAILED	cuDSS 库内部资源分配失败。这通常是由设备内存分配 (cudaMalloc()) 或主机内存分配失败引起的
CUDSS_STATUS_INVALID_VALUE	向函数传递了不正确的值或参数（例如，负向量大小，或必备缓冲区的 NULL 指针）
CUDSS_STATUS_NOT_SUPPORTED	向函数传递了不受支持的（但其他方面合理的参数）
CUDSS_STATUS_EXECUTION_FAILED	GPU 程序执行失败。这通常是由 GPU 上内核启动失败引起的，这可能是由多种原因造成的
CUDSS_STATUS_INTERNAL_ERROR	内部 cuDSS 操作失败

cudssConfigParam_t

枚举器指定求解器配置设置的可能名称。对于每个设置，都有一个匹配的类型用于 cudssConfigSet() 或 cudssConfigGet()。

值	描述
CUDSS_CONFIG_REORDERING_ALG	重排序阶段的算法 关联的参数类型：cudssAlgType_t 注意：CUDSS_ALG_1 和 CUDSS_ALG_2 仅支持通用（非对称或非埃尔米特）矩阵。 注意：CUDSS_ALG_1 使用因子中非零条目数的上限。如果在分解阶段发现此上限不足，则会返回运行时设备错误（可以通过同步流并调用 cudssDataGet() 和 CUDSS_DATA_INFO 来检查该错误，这将输出设备错误）。为了设置非默认上限，应调用 cudssConfigSet() 和 CUDSS_CONFIG_MAX_LU_NNZ 设置。 默认值：CUDSS_ALG_DEFAULT
CUDSS_CONFIG_FACTORIZATION_ALG	分解阶段的算法 关联的参数类型：cudssAlgType_t 默认值：CUDSS_ALG_DEFAULT
CUDSS_CONFIG_SOLVE_ALG	求解阶段的算法 关联的参数类型：cudssAlgType_t 默认值：CUDSS_ALG_DEFAULT
CUDSS_CONFIG_PIVOT_EPSILON_ALG	主元 epsilon 计算的算法 关联的参数类型：cudssAlgType_t CUDSS_ALG_DEFAULT - 幅值小于 epsilon 的主元将被适当符号的 epsilon 替换。 CUDSS_ALG_1 - 幅值小于 epsilon 的主元将被适当符号和缩放的 epsilon 替换。比例将计算为预处理矩阵的相应行和列中的最大元素。 注意：当 CUDSS_CONFIG_REORDERING_ALG 设置为 CUDSS_ALG_1 或 CUDSS_ALG_2 时，不支持用于 CUDSS_CONFIG_PIVOT_EPSILON_ALG 的 CUDSS_ALG_1 默认值：CUDSS_ALG_DEFAULT
CUDSS_CONFIG_MATCHING_TYPE	匹配类型（开/关） 关联的参数类型：int 默认值：0。不支持其他值。
CUDSS_CONFIG_SOLVE_MODE	系统矩阵的潜在修改器（例如，转置或共轭转置） 关联的参数类型：int 默认值：0（无修改器）。不支持其他值。
CUDSS_CONFIG_IR_N_STEPS	迭代细化期间的步数 关联的参数类型：int 默认值：0
CUDSS_CONFIG_IR_N_TOL	迭代细化容差 关联的参数类型：double 目前它被忽略（恰好执行 CUDSS_CONFIG_IR_N_STEPS 步）
CUDSS_CONFIG_PIVOT_TYPE	主元类型 此参数的确切含义取决于重排序算法的选择，可以通过 CUDSS_CONFIG_REORDERING_ALG 更改。对于 CUDSS_ALG_1 和 CUDSS_ALG_2，该参数指的是全局主元，而对于 CUDSS_ALG_DEFAULT 和其他算法，它指的是部分 1x1 主元过程。 请注意，在后一种情况下，如果矩阵类型是对称的但不是正定的，则主元也是对称的，并且仅当主元类型不等于 CUDSS_PIVOT_NONE 时，才在块的对角线上搜索主元。 关联的参数类型：cudssPivotType_t 默认值：CUDSS_PIVOT_COL。
CUDSS_CONFIG_PIVOT_THRESHOLD	主元阈值 \(p_{threshold}\)，用于确定对角元素是否需要进行主元操作，并将根据 主元类型 与行（或列）中的最大元素交换。 如果满足以下条件，则将交换对角元素： \(p_{threshold} \cdot max_{(sub)row \, or \, col} |a_{ij}| \geq |a_{ii}|\) 关联的参数类型：double 默认值：1.0f。 目前仅支持 CUDSS_ALG_1 和 CUDSS_ALG_2 重排序算法。
CUDSS_CONFIG_PIVOT_EPSILON	主元 epsilon，用于替换奇异对角元素的绝对值 关联的参数类型：double 默认值：单精度为 1e-5，双精度为 1e-13。
CUDSS_CONFIG_MAX_LU_NNZ	LU 因子中非零条目数的上限。这仅与非对称矩阵和设置为 CUDSS_ALG_1 或 CUDSS_ALG_2 的重排序算法相关。如果 L 和 U 中的非零条目数超过设置的限制，则会发生运行时错误。另请参阅 CUDSS_CONFIG_REORDERING_ALG 表条目中 CUDSS_ALG_1 的注释。 关联的参数类型：int64_t 默认值：-1（然后忽略该值）。
CUDSS_CONFIG_HYBRID_MODE	内存模式：0（默认 = 仅设备）或 1（混合 = 主机/设备）。 注意：应在分析阶段（cudssExecute() 和 CUDSS_PHASE_ANALYSIS）之前启用混合内存模式。如果在分析阶段之后决定使用混合模式，则应启用混合内存模式，并且必须重新执行分析阶段（这是次优的）。 注意：与控制计算内核执行位置的混合执行模式（请参阅 CUDSS_CONFIG_HYBRID_EXECUTE_MODE）不同，混合内存模式（‘CUDSS_CONFIG_HYBRID_MODE’）仅允许 cuDSS 将部分因子值（内部数据）保留在主机上，并且始终使用 GPU 进行分解和求解。 有关混合内存模式的更多详细信息，请参阅 混合模式特性。 关联的参数类型：int 默认值：0（禁用）。当 CUDSS_ALG_1 或 CUDSS_ALG_2 用于重排序，或者当 CUDSS_ALG_1 用于分解时，当前不支持。
CUDSS_CONFIG_HYBRID_DEVICE_MEMORY_LIMIT	混合内存模式的用户定义设备内存限制（字节数）。 此设置仅在启用混合内存模式时影响执行。 有关混合内存模式的更多详细信息，请参阅 混合模式特性。 关联的参数类型：int64_t 默认值：-1（使用内部默认启发式）。
CUDSS_CONFIG_USE_CUDA_REGISTER_MEMORY	一个标志，用于启用或禁用 cuDSS 混合内存模式对 cudaHostRegister() 的使用。 由于 cuDSS 的混合内存模式使用主机内存来存储因子，因此它可以（在硬件支持的情况下）使用 cudaHostRegister() 来加速相关的主机到设备和设备到主机内存传输。但是，注册主机内存具有局限性，在某些情况下可能会导致速度减慢。如果标志未设置为 0，则 cuDSS 将在硬件支持的情况下使用 cudaHostRegister()。如果标志设置为 0，即使硬件支持，cuDSS 也不会尝试使用 cudaHostRegister()。 此设置仅在启用混合内存模式时影响执行。 有关混合内存模式的更多详细信息，请参阅 混合模式特性。 关联的参数类型：int 默认值：1（如果设备支持，则使用 cudaHostRegister()）
CUDSS_CONFIG_HOST_NTHREADS	cuDSS 在 MT 模式 中使用的线程数。 此设置仅在启用多线程模式时影响执行。 关联的参数类型：int 默认值：-1（使用 cudssGetMaxThreads() 返回的线程数）
CUDSS_CONFIG_HYBRID_EXECUTE_MODE	执行模式：0（默认 = 仅设备）或 1（混合 = 主机/设备）。 混合执行模式允许 cuDSS 在 GPU 和 CPU 上执行计算。目前，它用于加速并行化能力低的执行部分。 注意：分析步骤的重排序部分在 CPU 上执行，而与执行模式值无关。 注意：应在分析阶段（cudssExecute() 和 CUDSS_PHASE_ANALYSIS）之前启用混合执行模式。 注意：与控制计算内核执行位置（并允许输入数据放置具有更大灵活性）的混合执行模式（CUDSS_CONFIG_HYBRID_EXECUTE_MODE）不同，混合内存模式（CUDSS_CONFIG_HYBRID_MODE）仅允许 cuDSS 将部分因子值（内部数据）保留在主机上，而仅使用 GPU 进行分解和求解。 注意：如果启用混合执行模式，则输入矩阵、右手边和解可以是主机内存指针。有关混合执行模式的更多详细信息，请参阅 混合执行模式特性。 注意：主机内存数据仅支持 nrhs = 1。 关联的参数类型：int 默认值：0（禁用）。 当使用 CUDSS_CONFIG_HYBRID_MODE 或 MGMN 模式，或者当 batchCount 大于 1 时，当前不支持。

---

cudssDataParam_t

枚举器指定可以在 cudssData_t 对象中设置或获取的可能参数名称。对于每个参数名称，都有一个关联的类型用于 cudssDataSet() 或 cudssDataGet()。每个参数名称都标有“in”、“out”或“inout”，具体取决于参数是只能设置、获取还是两者都涉及。

值	描述
CUDSS_DATA_INFO	设备端错误代码。 一个明显的用例是，当传递系统矩阵时，mtype 用于正定矩阵，但它似乎具有非正主子式（至少在数值上）。在这种情况下，在分解阶段之后调用 cudssDataGet() 和 CUDSS_DATA_INFO 将返回第一个遇到的非正主子式的从 1 开始的索引。然后，可以通过 cudssDataSet() 将设备错误设置回零，并更改矩阵类型或调整矩阵值（使矩阵正定），然后再次调用分解阶段。请注意，返回的索引是从 1 开始的，并且用于重排序后的矩阵。要获取相应的原始索引，应将其与（逆）置换结合使用，可以通过 cudssDataGet() 获取 CUDSS_DATA_PERM_REORDER_ROW 的置换。 方向：输出 内存：主机 关联的参数类型：int
CUDSS_DATA_LU_NNZ	LU 因子中的非零条目数。 方向：输出 内存：主机 关联的参数类型：int64_t
CUDSS_DATA_NPIVOTS	分解期间遇到的主元数。 方向：输出 内存：主机 关联的参数类型：与系统稀疏矩阵的索引类型相同
CUDSS_DATA_INERTIA	系统矩阵 A 的正负惯性指数（两个整数值）。仅对对称/埃尔米特非正定矩阵类型有效。 方向：输出 内存：主机 关联的参数类型：与系统稀疏矩阵的索引类型相同
CUDSS_DATA_PERM_REORDER_ROW	重排序后的行置换 P，使得 A[P,Q] 被分解。 方向：输出 内存：主机或设备 关联的参数类型：与系统稀疏矩阵的索引类型相同
CUDSS_DATA_PERM_REORDER_COL	重排序后的列置换 Q，使得 A[P,Q] 被分解。 方向：输出 内存：主机或设备 关联的参数类型：与系统稀疏矩阵的索引类型相同
CUDSS_DATA_PERM_ROW	最终行置换 P（包括重排序和主元操作的效果），以 \(b_{new} = b_{old} \circ P\) 的形式应用于系统的原始右手边 方向：输出 内存：主机或设备 关联的参数类型：与系统稀疏矩阵的索引类型相同 当前仅在使用 CUDSS_ALG_1 或 CUDSS_ALG_2 进行重排序时受支持。
CUDSS_DATA_PERM_COL	最终列置换 Q（包括重排序和主元操作的效果），用于将置换系统的解转换为原始解 \(x_{old} = x_{new} \circ Q^{-1}\) 方向：输出 内存：主机或设备 关联的参数类型：与系统稀疏矩阵的索引类型相同 当前仅在使用 CUDSS_ALG_1 或 CUDSS_ALG_2 进行重排序时受支持。
CUDSS_DATA_DIAG	分解矩阵的对角线 方向：输出 内存：主机或设备 关联的参数类型：与系统稀疏矩阵的值类型相同 当前仅在使用 CUDSS_ALG_1 或 CUDSS_ALG_2 进行重排序时受支持。
CUDSS_DATA_USER_PERM	用户置换，用于代替运行重排序算法。 方向：输入 内存：主机或设备 关联的参数类型：与系统稀疏矩阵的索引类型相同 当前在使用 CUDSS_ALG_1 或 CUDSS_ALG_2 进行重排序时不受支持。
CUDSS_DATA_MEMORY_ESTIMATES	所选内存模式所需的主机和设备内存的内存估计值（以字节为单位）。 所选内存模式定义为当前 cudssData_t 对象和调用期间相应 cudssConfigParam_t 对象状态的上次执行分析阶段期间检测到的内存模式。有关更多详细信息，请参阅 cudssConfigParam_t。 注意：返回的内存估计值不仅取决于 cudssConfig_t 对象中的设置，还取决于输入矩阵和 rhs（特别是 nrhs）。有关输入和右手边矩阵的信息在分析阶段检索，因此如果在分析阶段之后对象（或配置）发生更改，则内存估计可能不再准确。 在输出数组中的位置返回的值 0 - 永久设备内存 1 - 峰值设备内存 2 - 永久主机内存 3 - 峰值主机内存 4 - （如果在混合内存模式下）混合内存模式的最小设备内存 5 - （如果在混合内存模式下）混合内存模式的最大主机内存 6, … 15 - 保留供将来使用 此查询必须在分析阶段之后完成，如果无法处理，将返回状态 CUDSS_STATUS_NOT_SUPPORTED。 方向：输出 内存：主机 关联的参数类型：int64_t[16]
CUDSS_DATA_HYBRID_DEVICE_MEMORY_MIN	混合内存模式下所需的最小设备内存量（字节数）。 此查询必须在分析阶段之后完成，如果无法处理，将返回状态 CUDSS_STATUS_NOT_SUPPORTED。 方向：输出 内存：主机 关联的参数类型：int64_t 有关混合内存模式的更多详细信息，请参阅 混合模式特性。
CUDSS_DATA_COMM	用于 MGMN 模式 的通信器。 通信器的实际类型必须与 通信层 匹配，通信层必须通过调用 cudssSetCommLayer() 为 cuDSS 库句柄设置 cudssSetCommLayer()。 方向：输入 内存：主机 关联的参数类型：void* 有关 MGMN 模式的更多详细信息，请参阅 MGMN 模式。

注意：在 batchCount > 1 的情况下（参见 cudssMatrixCreateBatchDn() 和 cudssMatrixCreateBatchCsr()），对于 CUDSS_DATA_LU_NNZ、CUDSS_DATA_LU_NNZ、CUDSS_DATA_INERTIA、CUDSS_DATA_DIAG，cudssDataGet() 返回批次中所有矩阵的累积数。

注意：如果 batchCount > 1 (参见 cudssMatrixCreateBatchDn() 和 cudssMatrixCreateBatchCsr()) ，则不支持 CUDSS_DATA_USER_PERM、 CUDSS_DATA_PERM_COL、 CUDSS_DATA_PERM_ROW、 CUDSS_DATA_PERM_REORDER_COL 和 CUDSS_DATA_PERM_REORDER_ROW。

---

cudssPhase_t

此枚举器指定要在主 cuDSS 例程 cudssExecute() 中执行的求解器阶段。

值	描述
CUDSS_PHASE_ANALYSIS	重排序和符号分解
CUDSS_PHASE_FACTORIZATION	数值分解
CUDSS_PHASE_REFACTORIZATION	数值重分解。 注意：目前仅当重排序算法设置为 CUDSS_ALG_1 或 CUDSS_ALG_2 时使用。否则，它与 FACTORIZATION 阶段相同。
CUDSS_PHASE_SOLVE	完整求解阶段（前向替换 + 对角求解 + 后向替换）和（可选）迭代精化 注意：如果为此阶段提供新的稀疏矩阵作为输入，它将用于计算残差（因此求解器可以是基于 LU 的预处理器的一部分）
CUDSS_PHASE_SOLVE_FWD	求解阶段的前向替换子步骤 目前不支持。
CUDSS_PHASE_SOLVE_DIAG	求解阶段的对角求解子步骤 目前不支持。
CUDSS_PHASE_SOLVE_BWD	求解阶段的后向替换子步骤 目前不支持。

注意：未来可能会将不同阶段组合起来，例如调用 cudssExecute() 并使用 CUDSS_PHASE_FACTORIZATION | CUDSS_PHASE_SOLVE 以从额外的优化中获益。目前不支持这种使用模式。

---

cudssMatrixFormat_t

此枚举器指定 cuDSS 矩阵对象内部的底层矩阵格式。

值	描述
CUDSS_MFORMAT_DENSE	矩阵是稠密的（同样适用于单个矩阵和批处理）
CUDSS_MFORMAT_CSR	矩阵采用 CSR 格式（同样适用于单个矩阵和批处理） 注意：仅支持 3 数组 CSR。
CUDSS_MFORMAT_BATCH	矩阵对象表示一批矩阵

注意：格式标志可以组合使用。例如，通过 cudssMatrixCreateBatchCsr() 创建 cudssMatrix_t 将同时设置 CUDSS_MFORMAT_CSR 和 CUDSS_MFORMAT_BATCH 标志。可以通过按位运算检查标志的混合，例如 CUDSS_MFORMAT_CSR | CUDSS_MFORMAT_BATCH 表示 CSR 矩阵批处理。

---

cudssMatrixType_t

此枚举器指定稀疏矩阵的可用矩阵类型。矩阵类型应用于描述底层矩阵存储的属性。矩阵类型会影响求解器计算哪种类型的分解的决策。例如，当矩阵类型是正定类型之一时，不会检查对角线上的奇异值。

值	描述
CUDSS_MTYPE_GENERAL	通用矩阵 [默认] 将计算带有可选局部或全局旋转的 LDU 分解
CUDSS_MTYPE_SYMMETRIC	实对称矩阵。将计算带有可选局部旋转的 LDL^T 分解
CUDSS_MTYPE_HERMITIAN	复埃尔米特矩阵。将计算带有可选局部旋转的 LDL^H 分解
CUDSS_MTYPE_SPD	对称正定矩阵 将计算带有可选局部旋转的 Cholesky 分解 注意：如果以此矩阵类型传递的矩阵似乎具有零主子式（至少在数值上），则可以通过调用 cudssDataGet() 并使用 CUDSS_DATA_INFO 来获取第一个遇到的非正主子式的从 1 开始的索引。由于这将是设备端错误，因此调用 cudssExecute() 仍然可能返回 CUDSS_STATUS_SUCCESS。
CUDSS_MTYPE_HPD	埃尔米特正定矩阵 将计算复 Cholesky 分解，带有可选局部旋转 注意：如果以此矩阵类型传递的矩阵似乎具有零主子式（至少在数值上），则可以通过调用 cudssDataGet() 并使用 CUDSS_DATA_INFO 来获取第一个非正主子式的从 1 开始的索引。由于这将是设备端错误，因此调用 cudssExecute() 仍然可能返回 CUDSS_STATUS_SUCCESS。

---

cudssMatrixViewType_t

此枚举器指定稀疏矩阵的可用矩阵视图类型。矩阵视图定义了主 cuDSS 例程 cudssExecute() 如何处理矩阵。例如，要为对称矩阵仅提供上三角数据，可以使用 CUDSS_MTYPE_SYMMETRIC 作为矩阵类型，并结合 CUDSS_MVIEW_UPPER 作为矩阵视图。如果随附的矩阵类型为 CUDSS_MTYPE_GENERAL，则矩阵视图将被忽略。

值	描述
CUDSS_MVIEW_FULL	完整矩阵 [默认]
CUDSS_MVIEW_LOWER	下三角矩阵（包括对角线）主对角线以上的所有值都将被忽略。
CUDSS_MVIEW_UPPER	上三角矩阵（包括对角线）主对角线以下的所有值都将被忽略。

---

cudssIndexBase_t

此枚举器指定稀疏矩阵索引（行起始/结束偏移量和列索引）的索引基（0 或 1）。一旦为稀疏矩阵设置，cudssExecute() 将对所有与索引相关的数据使用来自输入稀疏矩阵的索引基（例如，从调用 cudssDataGet() 并使用 CUDSS_DATA_PERM_REORDER 获得的输出）。

值	描述
CUDSS_BASE_ZERO	从零开始的索引 [默认]
CUDSS_BASE_ONE	从一开始的索引

---

cudssLayout_t

此枚举器指定稠密矩阵布局。

值	描述
CUDSS_LAYOUT_COL_MAJOR	列优先布局 [默认]
CUDSS_LAYOUT_ROW_MAJOR	行优先布局。 目前不支持。

---

cudssAlgType_t

此枚举器指定求解器要使用的算法选择。

值	描述
CUDSS_ALG_DEFAULT	默认值 [默认] 对于重排序，此选项是基于 METIS 的自定义嵌套剖分算法。 对于分解，此选项根据重排序算法的选择及其产生的稀疏结构选择最合适的分解算法。
CUDSS_ALG_1	第一种算法 对于重排序，此选项是块三角重排序和 COLAMD 算法的自定义组合，可以与全局旋转一起使用，以提高非对称矩阵的求解精度，其中 CUDSS_ALG_DEFAULT 产生过多的扰动主元。当此选项用于重排序时，cuDSS 使用适当的自定义分解算法（无需更改分解设置 CUDSS_CONFIG_FACTORIZATION_ALG）。
CUDSS_ALG_2	第二种算法 对于重排序，此选项类似于 CUDSS_ALG_1，因为它暗示使用为块三角表示量身定制的特殊分解算法，但不像 CUDSS_ALG_1，此选项使用简单的块结构。
CUDSS_ALG_3	第三种算法 对于重排序，此选项是近似最小度 (AMD) 重排序。

不同的值代表不同的算法（用于重排序、分解等），并且可能导致精度和性能的显着差异。目前建议使用 CUDSS_ALG_DEFAULT，并且仅在精度或性能不足的情况下，才可以尝试其他值。

---

cudssPivotType_t

此枚举器指定要执行的主元类型。

值	描述
CUDSS_PIVOT_COL	基于列的主元 [默认]
CUDSS_PIVOT_ROW	基于行的主元
CUDSS_PIVOT_NONE	无主元

---

通信层（分布式接口）类型

cudssDistributedInterface_t

此结构定义了 cuDSS 通信层的（任何）实现中需要实现的所有通信原语，有关更多详细信息，请参见

在（任何）cuDSS 通信层的实现中，请参见更多详情

通信层 和 MGMN 模式。

注意：以下所有通信层 API 函数都采用 void * 类型的参数 comm。

此参数应在实现中根据要与特定通信层一起使用的底层通信进行解释

后端进行解释。例如，对于 OpenMPI，comm 应被

视为 OpenMPI 通信器。

注意：以下大多数 API 都采用类型为 cudaStream_t 的名为 stream 的参数

并且必须是流有序的。对于像 OpenMPI 这样的 GPU 感知通信后端，

这意味着需要在通信层实现中显式执行 cudaStreamSynchronize()。

成员

int (*cudssCommRank)(void *comm, int *rank)

指向例程的函数指针，该例程返回通信器中进程的秩。

参数	输入/输出	描述
comm	输入	指向通信器的指针。
rank	输出	调用进程在通信器中的秩。

返回调用错误状态（作为 int）。成功时必须返回 0，否则返回任何非零整数。

int (*cudssCommSize)(void *comm, int *size)

指向例程的函数指针，该例程返回通信器中进程的数量。

参数	输入/输出	描述
comm	输入	指向通信器的指针。
size	输出	通信器中进程的数量。

返回调用错误状态（作为 int）。成功时必须返回 0，否则返回任何非零整数。

int (*cudssSend)(const void *buffer, int count, cudaDataType_t datatype, int dest, int tag, void *comm, cudaStream_t stream)

指向执行阻塞发送的例程的函数指针。

参数	输入/输出	描述
buffer	输入	发送设备缓冲区的初始地址。
count	输入	要发送的元素数量（类型为 datatype）。
datatype	输入	要发送的元素的 CUDA 数据类型。
dest	输入	接收进程（目标）的秩。
tag	输入	消息标签。
comm	输入	指向通信器的指针。
stream	输入	CUDA 流。

返回调用错误状态（作为 int）。成功时必须返回 0，否则返回任何非零整数。

int (*cudssRecv)(void *buffer, int count, cudaDataType_t datatype, int source, int tag, void *comm, cudaStream_t stream)

指向执行消息阻塞接收的例程的函数指针。

参数	输入/输出	描述
buffer	输出	接收设备缓冲区的初始地址。
count	输入	要接收的元素数量（类型为 datatype）。
datatype	输入	要接收的元素的 CUDA 数据类型。
source	输入	发送进程（源）的秩。
tag	输入	消息标签。
comm	输入	指向通信器的指针。
stream	输入	CUDA 流。

返回调用错误状态（作为 int）。成功时必须返回 0，否则返回任何非零整数。

int (*cudssBcast)(void *buffer, int count, cudaDataType_t datatype, int root, void *comm, cudaStream_t stream)

指向例程的函数指针，该例程对来自 root 进程的消息执行广播

到通信器的所有其他进程。

参数	输入/输出	描述
buffer	输入/输出	要广播的设备缓冲区的地址。
count	输入	要接收的元素数量（类型为 datatype）。
datatype	输入	要接收的元素的 CUDA 数据类型。
root	输入	发送进程（源）的秩。
comm	输入	指向通信器的指针。
stream	输入	CUDA 流。

返回调用错误状态（作为 int）。成功时必须返回 0，否则返回任何非零整数。

int (*cudssReduce)(const void *sendbuf, void *recvbuf, int count, cudaDataType_t datatype, cudssOpType_t op, int root, void *comm, cudaStream_t stream)

指向例程的函数指针，该例程将所有进程上的值缩减为

root 进程上的单个值。

参数	输入/输出	描述
sendbuf	输入	发送缓冲区的地址
recvbuf	输出	接收缓冲区的地址
count	输入	要接收的元素数量（类型为 datatype）。
datatype	输入	要接收的元素的 CUDA 数据类型。
op	输入	要执行的归约操作的类型，有关支持的值，请参见 cudssOpType_t。
root	输入	根进程（源）的秩。
comm	输入	指向通信器的指针。
stream	输入	CUDA 流。

返回调用错误状态（作为 int）。成功时必须返回 0，否则返回任何非零整数。

int (*cudssAllreduce)(const void *sendbuf, void *recvbuf, int count, cudaDataType_t datatype, cudssOpType_t op, void *comm, cudaStream_t stream)

指向例程的函数指针，该例程将所有进程上的值归约到单个值，并将

结果分发回所有进程。

参数	输入/输出	描述
sendbuf	输入	发送缓冲区的地址。
recvbuf	输出	接收缓冲区的地址。
count	输入	要接收的元素数量（类型为 datatype）。
datatype	输入	要接收的元素的 CUDA 数据类型。
op	输入	要执行的归约操作的类型，有关支持的值，请参见 cudssOpType_t。
comm	输入	指向通信器的指针。
stream	输入	CUDA 流。

返回调用错误状态（作为 int）。成功时必须返回 0，否则返回任何非零整数。

int (*cudssScatterv)(const void *sendbuf, const int *sendcounts, const int *displs, cudaDataType_t sendtype, void *recvbuf, int recvcount, cudaDataType_t recvtype, int root, void *comm, cudaStream_t stream)

指向例程的函数指针，该例程对通信器中所有进程的部分缓冲区执行分散操作。

参数	输入/输出	描述
sendbuf	输入	发送缓冲区的地址。
sendcounts	输入	非负整数数组（长度为通信器大小），指定要发送到每个秩的元素数。
displs	输入	长度为通信器大小的整数数组。条目 i 指定从 sendbuf 到进程 i 的传出数据的位移（相对于 sendbuf）。
sendtype	输入	要发送的元素的 CUDA 数据类型。
recvbuf	输出	接收缓冲区的地址。
recvcount	输入	接收缓冲区中的元素数（非负整数）。
recvtype	输入	要接收的元素的 CUDA 数据类型。
root	输入	发送进程（源）的秩。
comm	输入	指向通信器的指针。
stream	输入	CUDA 流。

返回调用错误状态（作为 int）。成功时必须返回 0，否则返回任何非零整数。

int (*cudssCommSplit)(const void *comm, int color, int key, void *new_comm)

指向例程的函数指针，该例程基于颜色和键创建新的通信器。

参数	输入/输出	描述
comm	输入	要拆分的通信器的指针。
color	输入	子集分配的控制。具有相同颜色的进程被分组在一起。
key	输入	秩分配的控制。新通信器中的进程根据键排序。
new_comm	输出	指向根据颜色定义的新通信器的指针。

返回调用错误状态（作为 int）。成功时必须返回 0，否则返回任何非零整数。

int (*cudssCommFree)(void *comm)

指向例程的函数指针，该例程释放通信器的资源。

参数	输入/输出	描述
comm	输入/输出	要释放的通信器的指针。

返回调用错误状态（作为 int）。成功时必须返回 0，否则返回任何非零整数。

---

cudssOpType_t

此枚举器指定调用

通信层 API cudssReduce() 或 cudssAllreduce() 时要使用的归约操作。

值	描述
CUDSS_SUM	归约元素相加。
CUDSS_MAX	在归约元素中找到最大元素。
CUDSS_MIN	在归约元素中找到最小元素。

---

线程层类型

cudssThreadingInterface_t

此结构定义了 cuDSS 线程层的（任何）实现中需要实现的所有线程原语，有关更多详细信息，请参见

在（任何）cuDSS 线程层的实现中，请参见更多详情

线程层 和 MT 模式。

成员

int (*cudssGetMaxThreads)()

指向例程的函数指针，该例程返回（作为 int）CPU 上 cuDSS 可用于并行执行的最大线程数。

void (*cudssParallelFor)(int nthr_requested, int ntasks, void *ctx, cudss_thr_func_t f)

指向例程的函数指针，该例程打开一个具有请求的线程数的 parallel for 部分，并在具有 ntasks 次迭代的 for 循环中调用 cudss_thr_func_t（有关详细信息，请参见 cudss_threading_interface.h） f。

参数	输入/输出	描述
nthr_requested	输入	并行部分请求的线程数。
ntasks	输入	并行 for 循环中的任务数。
ctx	输入	指向 cudss_thr_func_t f 的输入数据的指针
f	输入	指向要在并行 for 循环中调用的 cudss_thr_func_t 函数的指针

线程接口结构使用以下任务函数的 typedef 声明，该函数定义了并行工作单元，也称为任务： typedef void (*cudss_thr_func_t)(int task, void *ctx)

参数	输入/输出	描述
task	输入	任务编号（或并行循环的迭代计数）。
ctx	输入	指向输入数据的指针。