cuTENSOR 函数¶

辅助函数¶

辅助函数用于初始化 cuTENSOR，创建张量描述符，检查错误代码，以及检索库和 CUDA 运行时版本。

`cutensorCreate()`¶

cutensorStatus_t cutensorCreate(cutensorHandle_t *handle)¶

初始化 cuTENSOR 库并为库上下文分配内存。

与特定 cuTENSOR 句柄关联的设备假定在调用 cutensorCreate 后保持不变。为了让 cuTENSOR 库使用不同的设备，应用程序必须通过调用 cudaSetDevice 设置要使用的新设备，然后创建另一个 cuTENSOR 句柄，该句柄将通过调用 cutensorCreate 与新设备关联。

此外，每个句柄默认都有一个 plan 缓存，可以存储最近最少使用的 cutensorPlan_t；其默认容量为 64，但如果存储空间太小，可以通过 cutensorHandleResizePlanCache 更改。有关更多信息，请参阅 Plan 缓存指南。

用户负责调用 cutensorDestroy 来释放与句柄关联的资源。

备注

阻塞，不可重入，线程安全

参数:: handle – [out] 指向 cutensorHandle_t 的指针
返回值:: CUTENSOR_STATUS_SUCCESS – 成功时返回，否则返回错误代码

`cutensorDestroy()`¶

cutensorStatus_t cutensorDestroy(cutensorHandle_t handle)¶

释放与提供的库句柄相关的所有资源。

备注

阻塞，不可重入，线程安全

参数:: handle – [inout] 指向 cutensorHandle_t 的指针
返回值:: CUTENSOR_STATUS_SUCCESS – 成功时返回，否则返回错误代码

`cutensorCreateTensorDescriptor()`¶

cutensorStatus_t cutensorCreateTensorDescriptor(const cutensorHandle_t handle, cutensorTensorDescriptor_t *desc, const uint32_t numModes, const int64_t extent[], const int64_t stride[], cutensorDataType_t dataType, uint32_t alignmentRequirement)¶

创建张量描述符。

这会分配少量主机内存。

用户负责调用 cutensorDestroyTensorDescriptor() 以在不再使用张量描述符时释放关联的资源。

备注

非阻塞，不可重入，线程安全

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
desc – [out] 指向将存储已分配的张量描述符对象地址的指针。
numModes – [in] 模式数量。
extent – [in] 每个模式的范围（必须大于零）。
stride – [in] stride[i] 表示第 i 个模式中两个连续元素之间的位移（也称为步幅）——以基本类型元素为单位。如果 stride 为 NULL，则假定为打包的广义列优先内存布局（即，步幅从左到右单调递增）。每个步幅必须大于零；准确地说，可以通过完全省略此模式来实现零步幅；例如，与其编写步幅 A(a) = 0 的 C[a,b] = A[b,a]，不如直接编写 C[a,b] = A[b]；然后 cuTENSOR 将自动推断 A 中的 a 模式应广播。
dataType – [in] 存储条目的数据类型。
alignmentRequirement – [in] 将与此张量描述符结合使用的基指针的对齐方式（以字节为单位）（例如，cudaMalloc 的默认对齐方式为 256 字节）。

返回值:

CUTENSOR_STATUS_SUCCESS – 操作成功完成。
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。
CUTENSOR_STATUS_NOT_SUPPORTED – 如果请求的描述符不受支持（例如，由于不支持的数据类型）。
CUTENSOR_STATUS_INVALID_VALUE – 如果某些输入数据无效（这通常表示用户错误）。

先决条件:

extent 和 stride 数组必须各自包含至少 sizeof(int64_t) * numModes 字节

`cutensorDestroyTensorDescriptor()`¶

cutensorStatus_t cutensorDestroyTensorDescriptor(cutensorTensorDescriptor_t desc)¶

释放与提供的张量描述符相关的所有资源。

备注

阻塞，不可重入，线程安全

参数:: desc – [inout] 将被释放的 cutensorTensorDescriptor_t 对象。
返回值:: CUTENSOR_STATUS_SUCCESS – 成功时返回，否则返回错误代码

`cutensorGetErrorString()`¶

const char *cutensorGetErrorString(const cutensorStatus_t error)¶

返回错误代码的描述字符串。

备注

非阻塞，不可重入，线程安全

参数:: error – [in] 要转换为字符串的错误代码。
返回值:: The – 以 null 结尾的错误字符串。

`cutensorGetVersion()`¶

size_t cutensorGetVersion()¶: 返回 CUTENSOR 库的版本号。

`cutensorGetCudartVersion()`¶

size_t cutensorGetCudartVersion()¶

返回 cuTENSOR 编译时所针对的 CUDA 运行时的版本号。

可以与 cudaRuntimeGetVersion() 中的 CUDA 运行时版本进行比较。

逐元素操作¶

以下函数执行张量之间的逐元素操作。

`cutensorCreateElementwiseTrinary()`¶

cutensorStatus_t cutensorCreateElementwiseTrinary(const cutensorHandle_t handle, cutensorOperationDescriptor_t *desc, const cutensorTensorDescriptor_t descA, const int32_t modeA[], cutensorOperator_t opA, const cutensorTensorDescriptor_t descB, const int32_t modeB[], cutensorOperator_t opB, const cutensorTensorDescriptor_t descC, const int32_t modeC[], cutensorOperator_t opC, const cutensorTensorDescriptor_t descD, const int32_t modeD[], cutensorOperator_t opAB, cutensorOperator_t opABC, const cutensorComputeDescriptor_t descCompute)¶

此函数创建一个操作描述符，用于编码逐元素三元运算。

所述三元运算具有以下一般形式

\[ D_{\Pi^C(i_0,i_1,...,i_n)} = \Phi_{ABC}(\Phi_{AB}(\alpha op_A(A_{\Pi^A(i_0,i_1,...,i_n)}), \beta op_B(B_{\Pi^B(i_0,i_1,...,i_n)})), \gamma op_C(C_{\Pi^C(i_0,i_1,...,i_n)})) \]

其中

A、B、C、D 是多模式张量（具有任意数据类型）。
\(\Pi^A, \Pi^B, \Pi^C \) 是分别置换 A、B 和 C 模式的置换运算符。
\(op_{A},op_{B},op_{C}\) 是单元逐元素运算符（例如，IDENTITY、CONJUGATE）。
\(\Phi_{ABC}, \Phi_{AB}\) 是二元逐元素运算符（例如，ADD、MUL、MAX、MIN）。

请注意，广播（模式）可以通过简单地从相应的张量中省略该模式来实现。

此外，模式可以以任何顺序出现，从而为用户提供更大的灵活性。唯一的限制是

出现在 A 或 B 中的模式必须也出现在输出张量中；仅出现在输入中的模式将被缩并，此类操作将由 cutensorContract 或 cutensorReduce 覆盖。
每个模式在每个张量中最多出现一次。

即使对应标量的值为零，也可以读取输入张量。

示例

\( D_{a,b,c,d} = A_{b,d,a,c}\)
\( D_{a,b,c,d} = 2.2 * A_{b,d,a,c} + 1.3 * B_{c,b,d,a}\)
\( D_{a,b,c,d} = 2.2 * A_{b,d,a,c} + 1.3 * B_{c,b,d,a} + C_{a,b,c,d}\)
\( D_{a,b,c,d} = min((2.2 * A_{b,d,a,c} + 1.3 * B_{c,b,d,a}), C_{a,b,c,d})\)

调用 cutensorElementwiseTrinaryExecute 以执行实际操作。

请使用 cutensorDestroyOperationDescriptor 在不再使用描述符时释放其分配的内存。

支持的数据类型组合为

typeA	typeB	typeC	descCompute
CUTENSOR_R_16F	CUTENSOR_R_16F	CUTENSOR_R_16F	CUTENSOR_COMPUTE_DESC_16F
CUTENSOR_R_16F	CUTENSOR_R_16F	CUTENSOR_R_16F	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_R_16BF	CUTENSOR_R_16BF	CUTENSOR_R_16BF	CUTENSOR_COMPUTE_DESC_16BF
CUTENSOR_R_16BF	CUTENSOR_R_16BF	CUTENSOR_R_16BF	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_R_64F	CUTENSOR_R_64F	CUTENSOR_R_64F	CUTENSOR_COMPUTE_DESC_64F
CUTENSOR_C_32F	CUTENSOR_C_32F	CUTENSOR_C_32F	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_C_64F	CUTENSOR_C_64F	CUTENSOR_C_64F	CUTENSOR_COMPUTE_DESC_64F
CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_R_16F	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_R_64F	CUTENSOR_R_64F	CUTENSOR_R_32F	CUTENSOR_COMPUTE_DESC_64F
CUTENSOR_C_64F	CUTENSOR_C_64F	CUTENSOR_C_32F	CUTENSOR_COMPUTE_DESC_64F

备注

调用异步函数，不可重入，线程安全

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
desc – [out] 此不透明结构体将被分配并填充用于编码请求的逐元素操作的信息。
descA – [in] 一个描述符，其中包含有关 A 的数据类型、模式和步幅的信息。
modeA – [in] 大小为 descA->numModes 的数组（在主机内存中），其中包含 A 的模式名称（例如，如果 \(A_{a,b,c}\) 则 modeA = {‘a’,’b’,’c’}）。modeA[i] 对应于 extent[i] 和 stride[i]，与提供给 cutensorCreateTensorDescriptor 的参数有关。
opA – [in] 在进一步处理之前将应用于 A 的每个元素的单元运算符。此张量的原始数据保持不变。
descB – [in] 一个描述符，其中包含有关 B 的数据类型、模式和步幅的信息。
modeB – [in] 大小为 descB->numModes 的数组（在主机内存中），其中包含 B 的模式名称。modeB[i] 对应于 cutensorCreateTensorDescriptor 的 extent[i] 和 stride[i]
opB – [in] 在进一步处理之前将应用于 B 的每个元素的单元运算符。此张量的原始数据保持不变。
descC – [in] 一个描述符，其中包含有关 C 的数据类型、模式和步幅的信息。
modeC – [in] 大小为 descC->numModes 的数组（在主机内存中），其中包含 C 的模式名称。modeC[i] 对应于 cutensorCreateTensorDescriptor 的 extent[i] 和 stride[i]。
opC – [in] 在进一步处理之前将应用于 C 的每个元素的单元运算符。此张量的原始数据保持不变。
descD – [in] 一个描述符，其中包含有关 D 的数据类型、模式和步幅的信息。请注意，我们目前要求 descD 和 descC 相同。
modeD – [in] 大小为 descD->numModes 的数组（在主机内存中），其中包含 D 的模式名称。modeD[i] 对应于 cutensorCreateTensorDescriptor 的 extent[i] 和 stride[i]。
opAB – [in] 逐元素二元运算符（参见上面的 \(\Phi_{AB}\)）。
opABC – [in] 逐元素二元运算符（参见上面的 \(\Phi_{ABC}\)）。
descCompute – [in] 确定执行此操作的精度。

返回值:

CUTENSOR_STATUS_SUCCESS – 操作成功完成。
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。
CUTENSOR_STATUS_INVALID_VALUE – 如果某些输入数据无效（这通常表示用户错误）。
CUTENSOR_STATUS_ARCH_MISMATCH – 如果设备未准备好，或者目标架构不受支持。

`cutensorElementwiseTrinaryExecute()`¶

cutensorStatus_t cutensorElementwiseTrinaryExecute(const cutensorHandle_t handle, const cutensorPlan_t plan, const void *alpha, const void *A, const void *beta, const void *B, const void *gamma, const void *C, void *D, cudaStream_t stream)¶

对三个输入张量执行逐元素张量运算（参见 cutensorCreateElementwiseTrinary）

此函数执行以下形式的逐元素张量运算

\[ D_{\Pi^C(i_0,i_1,...,i_n)} = \Phi_{ABC}(\Phi_{AB}(\alpha op_A(A_{\Pi^A(i_0,i_1,...,i_n)}), \beta op_B(B_{\Pi^B(i_0,i_1,...,i_n)})), \gamma op_C(C_{\Pi^C(i_0,i_1,...,i_n)})) \]

有关详细信息，请参见 cutensorCreateElementwiseTrinary()。

备注

调用异步函数，不可重入，线程安全

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
plan – [in] 不透明句柄，其中包含有关所需逐元素操作的所有信息（由 cutensorCreateElementwiseTrinary 后跟 cutensorCreatePlan 创建）。
alpha – [in] A 的缩放因子（请参阅 cutensorOperationDescriptorGetAttribute(desc, CUTENSOR_OPERATION_SCALAR_TYPE) 以查询预期的数据类型）。指向主机内存的指针。如果 alpha 为零，则不读取 A，并且不应用相应的单元运算符。
A – [in] 多模式张量（由 descA 在 cutensorCreateElementwiseTrinary 中描述）。指向 GPU 可访问内存的指针。通过此指针访问的数据不得与写入 D 的元素重叠。
beta – [in] B 的缩放因子（请参阅 cutensorOperationDescriptorGetAttribute(desc, CUTENSOR_OPERATION_SCALAR_TYPE) 以查询预期的数据类型）。指向主机内存的指针。如果 beta 为零，则不读取 B，并且不应用相应的单元运算符。
B – [in] 多模式张量（由 descB 在 cutensorCreateElementwiseTrinary 中描述）。指向 GPU 可访问内存的指针。通过此指针访问的数据不得与写入 D 的元素重叠。
gamma – [in] C 的缩放因子（请参阅 cutensorOperationDescriptorGetAttribute(desc, CUTENSOR_OPERATION_SCALAR_TYPE) 以查询预期的数据类型）。指向主机内存的指针。如果 gamma 为零，则不读取 C，并且不应用相应的单元运算符。
C – [in] 多模式张量（由 descC 在 cutensorCreateElementwiseTrinary 中描述）。指向 GPU 可访问内存的指针（如果且仅当 descC == descD 时，C 和 D 可以相同）。
D – [out] 多模式张量（由 descD 在 cutensorCreateElementwiseTrinary 中描述）。指向 GPU 可访问内存的指针（如果且仅当 descC == descD 时，C 和 D 可以相同）。
stream – [in] 用于执行操作的 CUDA 流。

返回值:

CUTENSOR_STATUS_NOT_SUPPORTED – 如果不支持数据类型或操作的组合
CUTENSOR_STATUS_INVALID_VALUE – 如果张量维度或模式具有非法值
CUTENSOR_STATUS_SUCCESS – 操作成功完成，没有错误
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。

`cutensorCreateElementwiseBinary()`¶

cutensorStatus_t cutensorCreateElementwiseBinary(const cutensorHandle_t handle, cutensorOperationDescriptor_t *desc, const cutensorTensorDescriptor_t descA, const int32_t modeA[], cutensorOperator_t opA, const cutensorTensorDescriptor_t descC, const int32_t modeC[], cutensorOperator_t opC, const cutensorTensorDescriptor_t descD, const int32_t modeD[], cutensorOperator_t opAC, const cutensorComputeDescriptor_t descCompute)¶

此函数为逐元素二元运算创建操作描述符。

二元运算具有以下通用形式

\[ D_{\Pi^C(i_0,i_1,...,i_n)} = \Phi_{AC}(\alpha \Psi_A(A_{\Pi^A(i_0,i_1,...,i_n)}), \gamma \Psi_C(C_{\Pi^C(i_0,i_1,...,i_n)})) \]

调用 cutensorElementwiseBinaryExecute 来执行实际操作。

支持的数据类型组合为

typeA	typeC	descCompute
CUTENSOR_R_16F	CUTENSOR_R_16F	CUTENSOR_COMPUTE_DESC_16F
CUTENSOR_R_16F	CUTENSOR_R_16F	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_R_16BF	CUTENSOR_R_16BF	CUTENSOR_COMPUTE_DESC_16BF
CUTENSOR_R_16BF	CUTENSOR_R_16BF	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_R_64F	CUTENSOR_R_64F	CUTENSOR_COMPUTE_DESC_64F
CUTENSOR_C_32F	CUTENSOR_C_32F	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_C_64F	CUTENSOR_C_64F	CUTENSOR_COMPUTE_DESC_64F
CUTENSOR_R_32F	CUTENSOR_R_16F	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_R_64F	CUTENSOR_R_32F	CUTENSOR_COMPUTE_DESC_64F
CUTENSOR_C_64F	CUTENSOR_C_32F	CUTENSOR_COMPUTE_DESC_64F

备注

调用异步函数，不可重入，线程安全

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
desc – [out] 此不透明结构体将被分配并填充用于编码请求的逐元素操作的信息。
descA – [in] 描述符，用于保存关于 A 的数据类型、模式和步幅的信息。
modeA – [in] 大小为 descA->numModes 的数组（在主机内存中），用于保存 A 的模式名称（例如，如果 A_{a,b,c} => modeA = {‘a’,’b’,’c’}）。 modeA[i] 对应于 extent[i] 和 stride[i]，与提供给 cutensorCreateTensorDescriptor 的参数相关。
opA – [in] 在进一步处理之前将应用于 A 的每个元素的单元运算符。此张量的原始数据保持不变。
descC – [in] 描述符，用于保存关于 C 的数据类型、模式和步幅的信息。
modeC – [in] 大小为 descC->numModes 的数组（在主机内存中），其中包含 C 的模式名称。modeC[i] 对应于 cutensorCreateTensorDescriptor 的 extent[i] 和 stride[i]。
opC – [in] 在进一步处理之前将应用于 C 的每个元素的单元运算符。此张量的原始数据保持不变。
descD – [in] 描述符，用于保存关于 D 的数据类型、模式和步幅的信息。请注意，目前我们要求 descD 和 descC 相同。
modeD – [in] 大小为 descD->numModes 的数组（在主机内存中），其中包含 D 的模式名称。modeD[i] 对应于 cutensorCreateTensorDescriptor 的 extent[i] 和 stride[i]。
opAC – [in] 逐元素二元运算符（参见上面的 \(\Phi_{AC}\)）。
descCompute – [in] 确定执行此操作的精度。

返回值:

CUTENSOR_STATUS_NOT_SUPPORTED – 如果不支持数据类型或操作的组合
CUTENSOR_STATUS_INVALID_VALUE – 如果张量维度或模式具有非法值
CUTENSOR_STATUS_SUCCESS – 操作成功完成，没有错误
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。

`cutensorElementwiseBinaryExecute()`¶

cutensorStatus_t cutensorElementwiseBinaryExecute(const cutensorHandle_t handle, const cutensorPlan_t plan, const void *alpha, const void *A, const void *gamma, const void *C, void *D, cudaStream_t stream)¶

对两个输入张量执行逐元素张量运算（参见 cutensorCreateElementwiseBinary）

此函数执行以下形式的逐元素张量运算

\[ D_{\Pi^C(i_0,i_1,...,i_n)} = \Phi_{AC}(\alpha \Psi_A(A_{\Pi^A(i_0,i_1,...,i_n)}), \gamma \Psi_C(C_{\Pi^C(i_0,i_1,...,i_n)})) \]

有关详细信息，请参见 cutensorCreateElementwiseBinary()。

备注

调用异步函数，不可重入，线程安全

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
plan – [in] 不透明句柄，其中包含关于所需逐元素运算的所有信息（由 cutensorCreateElementwiseBinary 后跟 cutensorCreatePlan 创建）。
alpha – [in] A 的缩放因子（请参阅 cutensorOperationDescriptorGetAttribute(desc, CUTENSOR_OPERATION_SCALAR_TYPE) 以查询预期的数据类型）。指向主机内存的指针。如果 alpha 为零，则不读取 A，并且不应用相应的单元运算符。
A – [in] 多模式张量（由 descA 作为 cutensorCreateElementwiseBinary 的一部分进行描述）。指向 GPU 可访问内存的指针。通过此指针访问的数据不得与写入 D 的元素重叠。
gamma – [in] C 的缩放因子（请参阅 cutensorOperationDescriptorGetAttribute(desc, CUTENSOR_OPERATION_SCALAR_TYPE) 以查询预期的数据类型）。指向主机内存的指针。如果 gamma 为零，则不读取 C，并且不应用相应的单元运算符。
C – [in] 多模式张量（由 descC 作为 cutensorCreateElementwiseBinary 的一部分进行描述）。指向 GPU 可访问内存的指针。通过此指针访问的数据不得与写入 D 的元素重叠。
D – [out] 多模式张量（由 descD 作为 cutensorCreateElementwiseBinary 的一部分进行描述）。指向 GPU 可访问内存的指针（如果且仅当 descC == descD 时，C 和 D 可以相同）。
stream – [in] 用于执行操作的 CUDA 流。

返回值:

CUTENSOR_STATUS_NOT_SUPPORTED – 如果不支持数据类型或操作的组合
CUTENSOR_STATUS_INVALID_VALUE – 如果张量维度或模式具有非法值
CUTENSOR_STATUS_SUCCESS – 操作成功完成，没有错误
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。

`cutensorCreatePermutation()`¶

cutensorStatus_t cutensorCreatePermutation(const cutensorHandle_t handle, cutensorOperationDescriptor_t *desc, const cutensorTensorDescriptor_t descA, const int32_t modeA[], cutensorOperator_t opA, const cutensorTensorDescriptor_t descB, const int32_t modeB[], const cutensorComputeDescriptor_t descCompute)¶

此函数为张量置换创建操作描述符。

张量置换具有以下通用形式

\[ B_{\Pi^B(i_0,i_1,...,i_n)} = \alpha op_A(A_{\Pi^A(i_0,i_1,...,i_n)}) \]

因此，此函数执行异地张量置换，并且是 cutensorCreateElementwiseBinary 的特化。

其中

A 和 B 是多模式张量（具有任意数据类型），
\(\Pi^A, \Pi^B\) 是分别置换 A、B 模式的置换运算符，
\(op_A\) 是一元逐元素运算符（例如，IDENTITY、SQR、CONJUGATE），并且
\(\Psi\) 在张量描述符 descA 中指定。

可以通过简单地从各自的张量中省略模式来实现（模式的）广播。

模式可以以任何顺序出现。唯一的限制是

出现在 A 中的模式必须也出现在输出张量中。
每个模式在每个张量中最多出现一次。

支持的数据类型组合为

typeA	typeB	descCompute
CUTENSOR_R_16F	CUTENSOR_R_16F	CUTENSOR_COMPUTE_DESC_16F
CUTENSOR_R_16F	CUTENSOR_R_16F	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_R_16F	CUTENSOR_R_32F	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_R_32F	CUTENSOR_R_16F	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_R_16BF	CUTENSOR_R_16BF	CUTENSOR_COMPUTE_DESC_16BF
CUTENSOR_R_16BF	CUTENSOR_R_16BF	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_R_64F	CUTENSOR_R_64F	CUTENSOR_COMPUTE_DESC_64F
CUTENSOR_R_32F	CUTENSOR_R_64F	CUTENSOR_COMPUTE_DESC_64F
CUTENSOR_R_64F	CUTENSOR_R_32F	CUTENSOR_COMPUTE_DESC_64F
CUTENSOR_C_32F	CUTENSOR_C_32F	CUTENSOR_COMPUTE_DESC_32F
CUTENSOR_C_64F	CUTENSOR_C_64F	CUTENSOR_COMPUTE_DESC_64F
CUTENSOR_C_32F	CUTENSOR_C_64F	CUTENSOR_COMPUTE_DESC_64F
CUTENSOR_C_64F	CUTENSOR_C_32F	CUTENSOR_COMPUTE_DESC_64F

备注

调用异步函数，不可重入，线程安全

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
desc – [out] 此不透明结构将被分配并填充用于编码所请求的置换的信息。
descA – [in] 描述符，用于保存关于 A 的数据类型、模式和步幅的信息。
modeA – [in] 大小为 descA->numModes 的数组，用于保存 A 的模式名称（例如，如果 A_{a,b,c} => modeA = {‘a’,’b’,’c’}）
opA – [in] 在进一步处理之前将应用于 A 的每个元素的单元运算符。此张量的原始数据保持不变。
descB – [in] 描述符，用于保存关于 B 的数据类型、模式和步幅的信息。
modeB – [in] 大小为 descB->numModes 的数组，用于保存 B 的模式名称
descCompute – [in] 确定执行此操作的精度。

返回值:

CUTENSOR_STATUS_NOT_SUPPORTED – 如果不支持数据类型或操作的组合
CUTENSOR_STATUS_INVALID_VALUE – 如果张量维度或模式具有非法值
CUTENSOR_STATUS_SUCCESS – 操作成功完成，没有错误
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。

`cutensorPermute()`¶

cutensorStatus_t cutensorPermute(const cutensorHandle_t handle, const cutensorPlan_t plan, const void *alpha, const void *A, void *B, const cudaStream_t stream)¶

执行由 plan 编码的张量置换（参见 cutensorCreatePermutation）。

此函数执行以下形式的逐元素张量运算

\[ B_{\Pi^B(i_0,i_1,...,i_n)} = \alpha \Psi(A_{\Pi^A(i_0,i_1,...,i_n)}) \]

因此，此函数执行异地张量置换。

其中

A 和 B 是多模式张量（具有任意数据类型），
\(\Pi^A, \Pi^B\) 是分别置换 A、B 模式的置换运算符，
\(\Psi\) 是一元逐元素运算符（例如，IDENTITY、SQR、CONJUGATE），并且
\(\Psi\) 在张量描述符 descA 中指定。

备注

调用异步函数，不可重入，线程安全

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
plan – [in] 不透明句柄，其中包含关于所需张量规约的所有信息（由 cutensorCreatePermutation 后跟 cutensorCreatePlan 创建）。
alpha – [in] A 的缩放因子（参见 cutensorOperationDescriptorGetAttribute(desc, CUTENSOR_OPERATION_SCALAR_TYPE)）。指向主机内存的指针。如果 alpha 为零，则不读取 A，并且不应用相应的运算符。
A – [in] 类型为 typeA 且具有 nmodeA 模式的多模式张量。指向 GPU 可访问内存的指针。通过此指针访问的数据不得与写入 D 的元素重叠。
B – [inout] 类型为 typeB 且具有 nmodeB 模式的多模式张量。指向 GPU 可访问内存的指针。
stream – [in] CUDA 流。

返回值:

CUTENSOR_STATUS_NOT_SUPPORTED – 如果不支持数据类型或操作的组合
CUTENSOR_STATUS_INVALID_VALUE – 如果张量维度或模式具有非法值
CUTENSOR_STATUS_SUCCESS – 操作成功完成，没有错误
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。

缩并运算¶

以下函数执行张量之间的缩并。

`cutensorCreateContraction()`¶

cutensorStatus_t cutensorCreateContraction(const cutensorHandle_t handle, cutensorOperationDescriptor_t *desc, const cutensorTensorDescriptor_t descA, const int32_t modeA[], cutensorOperator_t opA, const cutensorTensorDescriptor_t descB, const int32_t modeB[], cutensorOperator_t opB, const cutensorTensorDescriptor_t descC, const int32_t modeC[], cutensorOperator_t opC, const cutensorTensorDescriptor_t descD, const int32_t modeD[], const cutensorComputeDescriptor_t descCompute)¶

此函数分配一个 cutensorOperationDescriptor_t 对象，该对象编码 \( D = \alpha \mathcal{A} \mathcal{B} + \beta \mathcal{C} \) 形式的张量缩并。

分配 desc 的数据，用于执行以下形式的张量缩并

\[ \mathcal{D}_{{modes}_\mathcal{D}} \gets \alpha op_\mathcal{A}(\mathcal{A}_{{modes}_\mathcal{A}}) op_\mathcal{B}(B_{{modes}_\mathcal{B}}) + \beta op_\mathcal{C}(\mathcal{C}_{{modes}_\mathcal{C}}). \]

参见 cutensorCreatePlan （或 cutensorCreatePlanAutotuned）以创建计划（即，选择内核），然后调用 cutensorContract 以执行实际的缩并。

用户负责调用 cutensorDestroyOperationDescriptor 以释放与描述符关联的资源。

支持的数据类型组合为

typeA	typeB	typeC	descCompute	typeScalar	Tensor Core
CUTENSOR_R_16F	CUTENSOR_R_16F	CUTENSOR_R_16F	CUTENSOR_COMPUTE_DESC_32F	CUTENSOR_R_32F	Volta+
CUTENSOR_R_16BF	CUTENSOR_R_16BF	CUTENSOR_R_16BF	CUTENSOR_COMPUTE_DESC_32F	CUTENSOR_R_32F	Ampere+
CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_COMPUTE_DESC_32F	CUTENSOR_R_32F	否
CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_COMPUTE_DESC_TF32	CUTENSOR_R_32F	Ampere+
CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_COMPUTE_DESC_3XTF32	CUTENSOR_R_32F	Ampere+
CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_COMPUTE_DESC_16BF	CUTENSOR_R_32F	Ampere+
CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_R_32F	CUTENSOR_COMPUTE_DESC_16F	CUTENSOR_R_32F	Volta+
CUTENSOR_R_64F	CUTENSOR_R_64F	CUTENSOR_R_64F	CUTENSOR_COMPUTE_DESC_64F	CUTENSOR_R_64F	Ampere+
CUTENSOR_R_64F	CUTENSOR_R_64F	CUTENSOR_R_64F	CUTENSOR_COMPUTE_DESC_32F	CUTENSOR_R_64F	否
CUTENSOR_C_32F	CUTENSOR_C_32F	CUTENSOR_C_32F	CUTENSOR_COMPUTE_DESC_32F	CUTENSOR_C_32F	否
CUTENSOR_C_32F	CUTENSOR_C_32F	CUTENSOR_C_32F	CUTENSOR_COMPUTE_DESC_TF32	CUTENSOR_C_32F	Ampere+
CUTENSOR_C_32F	CUTENSOR_C_32F	CUTENSOR_C_32F	CUTENSOR_COMPUTE_DESC_3XTF32	CUTENSOR_C_32F	Ampere+
CUTENSOR_C_64F	CUTENSOR_C_64F	CUTENSOR_C_64F	CUTENSOR_COMPUTE_DESC_64F	CUTENSOR_C_64F	Ampere+
CUTENSOR_C_64F	CUTENSOR_C_64F	CUTENSOR_C_64F	CUTENSOR_COMPUTE_DESC_32F	CUTENSOR_C_64F	否
CUTENSOR_R_64F	CUTENSOR_C_64F	CUTENSOR_C_64F	CUTENSOR_COMPUTE_DESC_64F	CUTENSOR_C_64F	否
CUTENSOR_C_64F	CUTENSOR_R_64F	CUTENSOR_C_64F	CUTENSOR_COMPUTE_DESC_64F	CUTENSOR_C_64F	否

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
desc – [out] 此不透明结构将被分配并填充用于编码张量缩并运算的信息。
descA – [in] 描述符，用于保存关于 A 的数据类型、模式和步幅的信息。
modeA – [in] 具有 ‘nmodeA’ 条目的数组，表示 A 的模式。modeA[i] 对应于 extent[i] 和 stride[i]，与提供给 cutensorInitTensorDescriptor 的参数相关。
opA – [in] 在进一步处理之前将应用于 A 的每个元素的单元运算符。此张量的原始数据保持不变。
descB – [in] 描述符，用于保存关于 B 的数据类型、模式和步幅的信息。
modeB – [in] 具有 ‘nmodeB’ 条目的数组，表示 B 的模式。modeB[i] 对应于 extent[i] 和 stride[i]，与提供给 cutensorInitTensorDescriptor 的参数相关。
opB – [in] 在进一步处理之前将应用于 B 的每个元素的单元运算符。此张量的原始数据保持不变。
modeC – [in] 具有 ‘nmodeC’ 条目的数组，表示 C 的模式。modeC[i] 对应于 extent[i] 和 stride[i]，与提供给 cutensorInitTensorDescriptor 的参数相关。
descC – [in] 描述符，用于保存关于 C 的数据类型、模式和步幅的信息。
opC – [in] 在进一步处理之前将应用于 C 的每个元素的单元运算符。此张量的原始数据保持不变。
modeD – [in] 具有 ‘nmodeD’ 条目的数组，表示 D 的模式（目前必须与 modeC 相同）。modeD[i] 对应于 extent[i] 和 stride[i]，与提供给 cutensorInitTensorDescriptor 的参数相关。
descD – [in] 描述符，用于保存关于 D 的数据类型、模式和步幅的信息（目前必须与 descC 相同）。
typeCompute – [in] 用于 typeCompute T = A * B 的中间计算的数据类型。

返回值:

CUTENSOR_STATUS_NOT_SUPPORTED – 如果不支持数据类型或操作的组合
CUTENSOR_STATUS_INVALID_VALUE – 如果张量维度或模式具有非法值
CUTENSOR_STATUS_SUCCESS – 操作成功完成，没有错误
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。

`cutensorContract()`¶

cutensorStatus_t cutensorContract(const cutensorHandle_t handle, const cutensorPlan_t plan, const void *alpha, const void *A, const void *B, const void *beta, const void *C, void *D, void *workspace, uint64_t workspaceSize, cudaStream_t stream)¶

此例程计算张量缩并 \( D = alpha * A * B + beta * C \)。

\[ \mathcal{D}_{{modes}_\mathcal{D}} \gets \alpha * \mathcal{A}_{{modes}_\mathcal{A}} B_{{modes}_\mathcal{B}} + \beta \mathcal{C}_{{modes}_\mathcal{C}} \]

活动的 CUDA 设备必须与创建计划时活动的 CUDA 设备相匹配。

[示例]: 有关具体示例，请参见 https://github.com/NVIDIA/CUDALibrarySamples/tree/master/cuTENSOR/contraction.cu。

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
plan – [in] 不透明句柄，其中包含缩并执行计划（由 cutensorCreateContraction 后跟 cutensorCreatePlan 创建）。
alpha – [in] A*B 的缩放因子。其数据类型由 ‘descCompute’ 确定（参见 cutensorOperationDescriptorGetAttribute(desc, CUTENSOR_OPERATION_SCALAR_TYPE)）。指向主机内存的指针。
A – [in] 指向与 A 对应的数据的指针。指向 GPU 可访问内存的指针。通过此指针访问的数据不得与写入 D 的元素重叠。
B – [in] 指向与 B 对应的数据的指针。指向 GPU 可访问内存的指针。通过此指针访问的数据不得与写入 D 的元素重叠。
beta – [in] C 的缩放因子。其数据类型由 ‘descCompute’ 确定（参见 cutensorOperationDescriptorGetAttribute(desc, CUTENSOR_OPERATION_SCALAR_TYPE)）。指向主机内存的指针。
C – [in] 指向与 C 对应的数据的指针。指向 GPU 可访问内存的指针。
D – [out] 指向与 D 对应的数据的指针。指向 GPU 可访问内存的指针。
workspace – [out] 可选参数，可以为 NULL。此指针提供额外的设备内存工作区，供库用于其他优化；工作区必须与 256 字节对齐（即 cudaMalloc 的默认对齐方式）。
workspaceSize – [in] 工作区数组的大小（以字节为单位）；请参阅 cutensorEstimateWorkspaceSize 以查询所需的工作区。虽然 cutensorContract 并非严格要求工作区进行缩并，但仍建议提供一些小工作区（例如，128 MB）。
stream – [in] CUDA 流，所有计算都在其中执行。

返回值:

CUTENSOR_STATUS_NOT_SUPPORTED – 如果不支持该操作。
CUTENSOR_STATUS_INVALID_VALUE – 如果某些输入数据无效（这通常表示用户错误）。
CUTENSOR_STATUS_SUCCESS – 操作成功完成。
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。
CUTENSOR_STATUS_ARCH_MISMATCH – 如果计划是为与当前活动设备不同的设备创建的。
CUTENSOR_STATUS_INSUFFICIENT_DRIVER – 如果驱动程序不足。
CUTENSOR_STATUS_CUDA_ERROR – 如果发生了一些未知的 CUDA 错误（例如，内存不足）。

规约运算¶

以下函数执行张量规约。

`cutensorCreateReduction()`¶

cutensorStatus_t cutensorCreateReduction(const cutensorHandle_t handle, cutensorOperationDescriptor_t *desc, const cutensorTensorDescriptor_t descA, const int32_t modeA[], cutensorOperator_t opA, const cutensorTensorDescriptor_t descC, const int32_t modeC[], cutensorOperator_t opC, const cutensorTensorDescriptor_t descD, const int32_t modeD[], cutensorOperator_t opReduce, const cutensorComputeDescriptor_t descCompute)¶

创建 cutensorOperatorDescriptor_t 对象，该对象编码 \( D = alpha * opReduce(opA(A)) + beta * opC(C) \) 形式的张量规约。

例如，此函数使用户能够将整个张量规约为标量：C[] = alpha * A[i,j,k];

此函数还能够执行部分规约；例如：C[i,j] = alpha * A[k,j,i]; 在这种情况下，仅沿 k 模式的元素被缩并。

二元 opReduce 运算符提供对应该执行哪种规约的额外控制。例如，将 opReduce 设置为 CUTENSOR_OP_ADD 通过求和来规约 A 的元素，而 CUTENSOR_OP_MAX 将找到 A 中的最大元素。

支持的数据类型组合为

typeA	typeB	typeC	typeCompute
`CUTENSOR_R_16F`	`CUTENSOR_R_16F`	`CUTENSOR_R_16F`	`CUTENSOR_COMPUTE_DESC_16F`
`CUTENSOR_R_16F`	`CUTENSOR_R_16F`	`CUTENSOR_R_16F`	`CUTENSOR_COMPUTE_DESC_32F`
`CUTENSOR_R_16BF`	`CUTENSOR_R_16BF`	`CUTENSOR_R_16BF`	`CUTENSOR_COMPUTE_DESC_16BF`
`CUTENSOR_R_16BF`	`CUTENSOR_R_16BF`	`CUTENSOR_R_16BF`	`CUTENSOR_COMPUTE_DESC_32F`
`CUTENSOR_R_32F`	`CUTENSOR_R_32F`	`CUTENSOR_R_32F`	`CUTENSOR_COMPUTE_DESC_32F`
`CUTENSOR_R_64F`	`CUTENSOR_R_64F`	`CUTENSOR_R_64F`	`CUTENSOR_COMPUTE_DESC_64F`
`CUTENSOR_C_32F`	`CUTENSOR_C_32F`	`CUTENSOR_C_32F`	`CUTENSOR_COMPUTE_DESC_32F`
`CUTENSOR_C_64F`	`CUTENSOR_C_64F`	`CUTENSOR_C_64F`	`CUTENSOR_COMPUTE_DESC_64F`

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
desc – [out] 此不透明结构将被分配并填充用于编码所请求的张量规约运算的信息。
descA – [in] 描述符，用于保存关于 A 的数据类型、模式和步幅的信息。
modeA – [输入] 包含 ‘nmodeA’ 个条目的数组，表示 A 的模式。modeA[i] 对应于 extent[i] 和 stride[i]，与传递给 cutensorCreateTensorDescriptor 的参数相关。仅出现在 modeA 中但未出现在 modeC 中的模式会被约简（收缩）。
opA – [in] 在进一步处理之前将应用于 A 的每个元素的单元运算符。此张量的原始数据保持不变。
descC – [输入] 描述符，包含关于 C 的数据类型、模式和步长的信息。
modeC – [输入] 包含 ‘nmodeC’ 个条目的数组，表示 C 的模式。modeC[i] 对应于 extent[i] 和 stride[i]，与传递给 cutensorCreateTensorDescriptor 的参数相关。
opC – [in] 在进一步处理之前将应用于 C 的每个元素的单元运算符。此张量的原始数据保持不变。
descD – [输入] 目前必须与 descC 相同。
modeD – [输入] 目前必须与 modeC 相同。
opReduce – [输入] 用于约简 A 元素的二元运算符。
typeCompute – [输入] 所有算术运算都使用此数据类型执行（即，它会影响精度和性能）。

返回值:

CUTENSOR_STATUS_NOT_SUPPORTED – 如果不支持该操作。
CUTENSOR_STATUS_INVALID_VALUE – 如果某些输入数据无效（这通常表示用户错误）。
CUTENSOR_STATUS_SUCCESS – 操作成功完成。
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。

`cutensorReduce()`¶

cutensorStatus_t cutensorReduce(const cutensorHandle_t handle, const cutensorPlan_t plan, const void *alpha, const void *A, const void *beta, const void *C, void *D, void *workspace, uint64_t workspaceSize, cudaStream_t stream)¶

执行由 plan 编码的张量约简（参见 cutensorCreateReduction）。

参数:

alpha – [输入] A 的缩放因子。其数据类型由 ‘descCompute’ 确定（参见 cutensorOperationDescriptorGetAttribute(desc, CUTENSOR_OPERATION_SCALAR_TYPE)）。指向主机内存的指针。
A – [输入] 指向设备内存中与 A 对应的数据的指针。指向 GPU 可访问内存的指针。通过此指针访问的数据不得与写入 D 的元素重叠。
beta – [in] C 的缩放因子。其数据类型由 ‘descCompute’ 确定（参见 cutensorOperationDescriptorGetAttribute(desc, CUTENSOR_OPERATION_SCALAR_TYPE)）。指向主机内存的指针。
C – [输入] 指向设备内存中与 C 对应的数据的指针。指向 GPU 可访问内存的指针。
D – [输出] 指向设备内存中与 C 对应的数据的指针。指向 GPU 可访问内存的指针。
workspace – [输出] 临时（设备）内存，大小至少为 workspaceSize 字节；工作区必须对齐到 256 字节（即，cudaMalloc 的默认对齐方式）。
workspaceSize – [输入] 请使用 cutensorEstimateWorkspaceSize() 查询所需的工作区大小。
stream – [in] CUDA 流，所有计算都在其中执行。

返回值:

CUTENSOR_STATUS_SUCCESS – 操作成功完成。

通用操作函数¶

以下函数是通用的，适用于所有不同的操作。

`cutensorDestroyOperationDescriptor()`¶

cutensorStatus_t cutensorDestroyOperationDescriptor(cutensorOperationDescriptor_t desc)¶

释放与提供的描述符相关的所有资源。

备注

阻塞，不可重入，线程安全

参数:: desc – [输入/输出] 将被释放的 cutensorOperationDescriptor_t 对象。
返回值:: CUTENSOR_STATUS_SUCCESS – 成功时返回，否则返回错误代码

`cutensorOperationDescriptorGetAttribute()`¶

cutensorStatus_t cutensorOperationDescriptorGetAttribute(const cutensorHandle_t handle, cutensorOperationDescriptor_t desc, cutensorOperationDescriptorAttribute_t attr, void *buf, size_t sizeInBytes)¶

此函数检索提供的 cutensorOperationDescriptor_t 对象的属性（参见 cutensorOperationDescriptorAttribute_t）。

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
desc – [输入] 要查询属性的 cutensorOperationDescriptor_t 对象。
attr – [输入] 指定要检索的属性。
buf – [输出] 此缓冲区（大小为 sizeInBytes）将保存所提供的 cutensorOperationDescriptor_t 对象的请求属性。
sizeInBytes – [输入] buf 的大小（以字节为单位）；有关确切大小，请参见 cutensorOperationDescriptorAttribute_t。

返回值:

CUTENSOR_STATUS_SUCCESS – 操作成功完成。
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。
CUTENSOR_STATUS_INVALID_VALUE – 如果某些输入数据无效（这通常表示用户错误）。

`cutensorOperationDescriptorSetAttribute()`¶

cutensorStatus_t cutensorOperationDescriptorSetAttribute(const cutensorHandle_t handle, cutensorOperationDescriptor_t desc, cutensorOperationDescriptorAttribute_t attr, const void *buf, size_t sizeInBytes)¶

设置 cutensorOperationDescriptor_t 对象的属性。

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
desc – [输入/输出] 将被修改的操作描述符。
attr – [输入] 指定要设置的属性。
buf – [输入] 此缓冲区（大小为 sizeInBytes）确定 attr 将被设置为何值。
sizeInBytes – [输入] buf 的大小（以字节为单位）。

返回值:

CUTENSOR_STATUS_SUCCESS – 操作成功完成。
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。
CUTENSOR_STATUS_INVALID_VALUE – 如果某些输入数据无效（这通常表示用户错误）。

`cutensorCreatePlanPreference()`¶

cutensorStatus_t cutensorCreatePlanPreference(const cutensorHandle_t handle, cutensorPlanPreference_t *pref, cutensorAlgo_t algo, cutensorJitMode_t jitMode)¶

分配 cutensorPlanPreference_t，使用户能够限制给定计划/操作的适用内核。

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
pref – [输出] 指向此函数分配的 cutensorPlanPreference_t 结构的指针。参见 cutensorPlanPreference_t。
algo – [输入] 允许用户选择特定的算法。CUTENSOR_ALGO_DEFAULT 让启发式方法选择算法。任何值 >= 0 选择特定的类 GEMM 算法并停用启发式方法。如果指定算法不受支持，则返回 CUTENSOR_STATUS_NOT_SUPPORTED。有关其他选择，请参见 cutensorAlgo_t。
jitMode – [输入] 确定是否允许 cuTENSOR 使用 JIT 编译的内核（导致更长的计划创建阶段）；参见 cutensorJitMode_t。

`cutensorDestroyPlanPreference()`¶

cutensorStatus_t cutensorDestroyPlanPreference(cutensorPlanPreference_t pref)¶

释放与提供的偏好设置相关的所有资源。

备注

阻塞，不可重入，线程安全

参数:: pref – [输入/输出] 将被释放的 cutensorPlanPreference_t 对象。
返回值:: CUTENSOR_STATUS_SUCCESS – 成功时返回，否则返回错误代码

`cutensorPlanPreferenceSetAttribute()`¶

cutensorStatus_t cutensorPlanPreferenceSetAttribute(const cutensorHandle_t handle, cutensorPlanPreference_t pref, cutensorPlanPreferenceAttribute_t attr, const void *buf, size_t sizeInBytes)¶

设置 cutensorPlanPreference_t 对象的属性。

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
pref – [输入/输出] 此不透明结构限制了可行候选项的搜索空间。
attr – [输入] 指定要设置的属性。
buf – [输入] 此缓冲区（大小为 sizeInBytes）确定 attr 将被设置为何值。
sizeInBytes – [输入] buf 的大小（以字节为单位）；有关确切大小，请参见 cutensorPlanPreferenceAttribute_t。

返回值:

CUTENSOR_STATUS_SUCCESS – 操作成功完成。
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。
CUTENSOR_STATUS_INVALID_VALUE – 如果某些输入数据无效（这通常表示用户错误）。

`cutensorEstimateWorkspaceSize()`¶

cutensorStatus_t cutensorEstimateWorkspaceSize(const cutensorHandle_t handle, const cutensorOperationDescriptor_t desc, const cutensorPlanPreference_t planPref, const cutensorWorksizePreference_t workspacePref, uint64_t *workspaceSizeEstimate)¶

确定由 desc 编码的给定操作所需的 workspaceSize。

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
desc – [输入] 此不透明结构编码了操作。
planPref – [输入] 此不透明结构限制了可行候选项的空间。
workspacePref – [输入] 此参数影响工作区的大小；有关详细信息，请参见 cutensorWorksizePreference_t。
workspaceSizeEstimate – [输出] 给定操作所需的工作区大小（以字节为单位）。

返回值:

CUTENSOR_STATUS_SUCCESS – 操作成功完成。
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。
CUTENSOR_STATUS_INVALID_VALUE – 如果某些输入数据无效（这通常表示用户错误）。

`cutensorCreatePlan()`¶

cutensorStatus_t cutensorCreatePlan(const cutensorHandle_t handle, cutensorPlan_t *plan, const cutensorOperationDescriptor_t desc, const cutensorPlanPreference_t pref, uint64_t workspaceSizeLimit)¶

此函数分配一个 cutensorPlan_t 对象，为给定操作（由 desc 编码）选择合适的内核，并准备一个编码执行的计划。

此函数应用 cuTENSOR 的启发式方法，为给定操作（由 cutensorCreateContraction、cutensorCreateReduction、cutensorCreatePermutation、cutensorCreateElementwiseBinary 或 cutensorCreateElementwiseTrinary 创建）选择候选/内核。然后，可以将创建的计划传递给 cutensorContract、cutensorReduce、cutensorPermute、cutensorElementwiseBinaryExecute 或 cutensorElementwiseTrinaryExecute 以执行实际操作。

该计划是为活动的 CUDA 设备创建的。

注意：如果启用了即时 (Just-In-Time) 编译（即，cutensorJitMode_t 不是 CUTENSOR_JIT_MODE_NONE），则不得通过 CUDA 图捕获 cutensorCreatePlan。

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
plan – [输出] 指向由此函数创建的数据结构的指针，该结构保存执行所需操作的所有必要信息（例如，选定的内核）。
desc – [输入] 此不透明结构编码了给定的操作（参见 cutensorCreateContraction、cutensorCreateReduction、cutensorCreatePermutation、cutensorCreateElementwiseBinary 或 cutensorCreateElementwiseTrinary）。
pref – [输入] 此不透明结构用于限制适用候选/内核的空间（参见 cutensorCreatePlanPreference 或 cutensorPlanPreferenceAttribute_t）。可以为 nullptr，在这种情况下，将采用默认选择。
workspaceSizeLimit – [输入] 表示允许相应操作使用的最大工作区（参见 cutensorEstimateWorkspaceSize）

返回值:

CUTENSOR_STATUS_SUCCESS – 如果找到了可行的候选。
CUTENSOR_STATUS_NOT_SUPPORTED – 如果找不到可行的候选。
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。
CUTENSOR_STATUS_INSUFFICIENT_WORKSPACE – 如果提供的工作区不足。
CUTENSOR_STATUS_INVALID_VALUE – 如果某些输入数据无效（这通常表示用户错误）。

`cutensorDestroyPlan()`¶

cutensorStatus_t cutensorDestroyPlan(cutensorPlan_t plan)¶

释放与提供的计划相关的所有资源。

备注

阻塞，不可重入，线程安全

参数:: plan – [输入/输出] 将被释放的 cutensorPlan_t 对象。
返回值:: CUTENSOR_STATUS_SUCCESS – 成功时返回，否则返回错误代码

`cutensorPlanGetAttribute()`¶

cutensorStatus_t cutensorPlanGetAttribute(const cutensorHandle_t handle, const cutensorPlan_t plan, cutensorPlanAttribute_t attr, void *buf, size_t sizeInBytes)¶

检索有关已创建计划的信息（参见 cutensorPlanAttribute_t）

参数:

plan – [输入] 表示已创建的计划（例如，通过 cutensorCreatePlan 或 cutensorCreatePlanAutotuned）
attr – [输入] 请求的属性。
buf – [输出] 成功退出时：保存请求属性的信息。
sizeInBytes – [输入] buf 的大小（以字节为单位）。

返回值:

CUTENSOR_STATUS_SUCCESS – 操作成功完成。
CUTENSOR_STATUS_INVALID_VALUE – 如果某些输入数据无效（这通常表示用户错误）。

`cutensorPlanPreferenceSetAttribute()`¶

cutensorStatus_t cutensorPlanPreferenceSetAttribute(const cutensorHandle_t handle, cutensorPlanPreference_t pref, cutensorPlanPreferenceAttribute_t attr, const void *buf, size_t sizeInBytes)

设置 cutensorPlanPreference_t 对象的属性。

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
pref – [输入/输出] 此不透明结构限制了可行候选项的搜索空间。
attr – [输入] 指定要设置的属性。
buf – [输入] 此缓冲区（大小为 sizeInBytes）确定 attr 将被设置为何值。
sizeInBytes – [输入] buf 的大小（以字节为单位）；有关确切大小，请参见 cutensorPlanPreferenceAttribute_t。

返回值:

CUTENSOR_STATUS_SUCCESS – 操作成功完成。
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。
CUTENSOR_STATUS_INVALID_VALUE – 如果某些输入数据无效（这通常表示用户错误）。

缓存相关操作¶

`cutensorHandleResizePlanCache()`¶

cutensorStatus_t cutensorHandleResizePlanCache(cutensorHandle_t handle, const uint32_t numEntries)¶

调整计划缓存的大小。

此函数更改句柄的计划缓存中可以存储的计划数量。

调整大小会使缓存失效。

虽然此函数不是线程安全的，但生成的缓存可以以线程安全的方式在不同线程之间共享。

备注

非阻塞，不可重入，且非线程安全

参数:

handle – [输入] 持有 cuTENSOR 库上下文的不透明句柄。缓存将附加到此句柄
numEntries – [输入] 缓存将支持的条目数。

返回值:

CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。
CUTENSOR_STATUS_SUCCESS – 操作成功完成。
CUTENSOR_STATUS_INVALID_VALUE – 如果某些输入数据无效（这通常表示用户错误）。

`cutensorHandleReadPlanCacheFromFile()`¶

cutensorStatus_t cutensorHandleReadPlanCacheFromFile(cutensorHandle_t handle, const char filename[], uint32_t *numCachelinesRead)¶

从文件读取计划缓存，并覆盖所提供句柄的缓存行。

缓存仅对相同的 cuTENSOR 版本和 CUDA 版本有效；此外，GPU 架构（包括多处理器计数）必须匹配，否则将返回 CUTENSOR_STATUS_INVALID_VALUE。

备注

非阻塞，不可重入，线程安全

参数:

handle – [输入/输出] 持有 cuTENSOR 库上下文的不透明句柄。
filename – [输入] 指定文件名（包括绝对路径），该文件包含之前由 cutensorHandleWritePlanCacheToFile 写入的所有缓存信息。
numCachelinesRead – [输出] 退出时，如果返回 CUTENSOR_STATUS_SUCCESS，则此变量将保存成功读取的缓存行数。否则，此变量将保存读取与 filename 指向的缓存关联的所有缓存行所需的缓存行数；在这种情况下，将返回 CUTENSOR_STATUS_INSUFFICIENT_WORKSPACE。

返回值:

CUTENSOR_STATUS_SUCCESS – 操作成功完成。
CUTENSOR_STATUS_INVALID_VALUE – 如果存储的缓存是由不同的 cuTENSOR 或 CUDA 版本创建的，或者 GPU 架构（包括多处理器计数）不匹配
CUTENSOR_STATUS_INSUFFICIENT_WORKSPACE – 如果存储的缓存需要的缓存行数多于当前附加到句柄的缓存行数
CUTENSOR_STATUS_IO_ERROR – 如果文件无法读取
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。

`cutensorHandleWritePlanCacheToFile()`¶

cutensorStatus_t cutensorHandleWritePlanCacheToFile(const cutensorHandle_t handle, const char filename[])¶

将计划缓存（属于提供的句柄）写入文件。

备注

非阻塞，不可重入，线程安全

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
filename – [输入] 指定文件名（包括绝对路径），该文件应保存所有缓存信息。警告：现有文件将被覆盖。

返回值:

CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。
CUTENSOR_STATUS_SUCCESS – 操作成功完成。
CUTENSOR_STATUS_INVALID_VALUE – 如果未附加任何缓存
CUTENSOR_STATUS_IO_ERROR – 如果文件无法写入

`cutensorReadKernelCacheFromFile()`¶

cutensorStatus_t cutensorReadKernelCacheFromFile(cutensorHandle_t handle, const char filename[])¶

从文件读取内核缓存，并将所有不存在的 JIT 编译内核添加到内核缓存。

缓存仅对相同的 cuTENSOR 版本和 CUDA 版本有效；此外，GPU 架构（包括多处理器计数）必须匹配，否则将返回 CUTENSOR_STATUS_INVALID_VALUE。

备注

非阻塞，不可重入，线程安全

参数:

handle – [输入/输出] 持有 cuTENSOR 库上下文的不透明句柄。
filename – [输入] 指定文件名（包括绝对路径），该文件包含之前由 cutensorWriteKernelCacheToFile 写入的所有缓存信息。

返回值:

CUTENSOR_STATUS_SUCCESS – 操作成功完成，或者 filename 指向的文件为空。
CUTENSOR_STATUS_INVALID_VALUE – 如果存储的缓存是由不同的 cuTENSOR 或 CUDA 版本创建的，或者 GPU 架构（包括多处理器计数）不匹配。
CUTENSOR_STATUS_IO_ERROR – 如果文件无法读取。
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。
CUTENSOR_STATUS_NOT_SUPPORTED – 如果该函数不适用于操作系统、CUDA 工具包或设备的计算能力。

`cutensorWriteKernelCacheToFile()`¶

cutensorStatus_t cutensorWriteKernelCacheToFile(const cutensorHandle_t handle, const char filename[])¶

将 —每个库— 内核缓存写入文件。

将即时编译的内核写入到提供的文件（这些内核属于库—而不是句柄）。

备注

非阻塞，不可重入，线程安全

参数:

handle – [in] 持有 cuTENSOR 库上下文的不透明句柄。
filename – [输入] 指定文件名（包括绝对路径），该文件应保存所有缓存信息。警告：现有文件将被覆盖。

返回值:

CUTENSOR_STATUS_SUCCESS – 操作成功完成，或者缓存中没有内核。
CUTENSOR_STATUS_IO_ERROR – 如果文件无法写入。
CUTENSOR_STATUS_NOT_INITIALIZED – 如果句柄未初始化。
CUTENSOR_STATUS_NOT_SUPPORTED – 如果该函数不适用于操作系统、CUDA 工具包或设备的计算能力。

日志记录器函数¶

`cutensorLoggerSetCallback()`¶

cutensorStatus_t cutensorLoggerSetCallback(cutensorLoggerCallback_t callback)¶

此函数设置日志记录回调例程。

参数:: callback – [输入] 指向回调函数的指针。请查看 cutensorLoggerCallback_t。

`cutensorLoggerSetFile()`¶

cutensorStatus_t cutensorLoggerSetFile(FILE *file)¶

此函数设置日志记录输出文件。

参数:: file – [输入] 具有写入权限的已打开文件。

`cutensorLoggerOpenFile()`¶

cutensorStatus_t cutensorLoggerOpenFile(const char *logFile)¶

此函数在给定路径中打开日志记录输出文件。

参数:: logFile – [输入] 日志记录输出文件的路径。

`cutensorLoggerSetLevel()`¶

cutensorStatus_t cutensorLoggerSetLevel(int32_t level)¶

此函数设置日志记录级别的数值。

参数:

level – [输入] 日志级别，应为以下之一

0. 关闭
1. 错误
2. 性能跟踪
3. 性能提示
4. 启发式跟踪
5. API 跟踪

`cutensorLoggerSetMask()`¶

cutensorStatus_t cutensorLoggerSetMask(int32_t mask)¶

此函数设置日志掩码的数值。

参数:

mask – [输入] 日志掩码，以下各项的按位或

0. 关闭
1. 错误
2. 性能跟踪
4. 性能提示
8. 启发式跟踪
16. API 跟踪

`cutensorLoggerForceDisable()`¶

cutensorStatus_t cutensorLoggerForceDisable()¶: 此函数禁用整个运行过程的日志记录。

cuTENSOR 函数¶

辅助函数¶

cutensorCreate()¶

cutensorDestroy()¶

cutensorCreateTensorDescriptor()¶

cutensorDestroyTensorDescriptor()¶

cutensorGetErrorString()¶

cutensorGetVersion()¶

cutensorGetCudartVersion()¶

逐元素操作¶

cutensorCreateElementwiseTrinary()¶

cutensorElementwiseTrinaryExecute()¶

cutensorCreateElementwiseBinary()¶

cutensorElementwiseBinaryExecute()¶

cutensorCreatePermutation()¶

cutensorPermute()¶

缩并运算¶

cutensorCreateContraction()¶

cutensorContract()¶

规约运算¶

cutensorCreateReduction()¶

cutensorReduce()¶

通用操作函数¶

cutensorDestroyOperationDescriptor()¶

cutensorOperationDescriptorGetAttribute()¶

cutensorOperationDescriptorSetAttribute()¶

cutensorCreatePlanPreference()¶

cutensorDestroyPlanPreference()¶

cutensorPlanPreferenceSetAttribute()¶

cutensorEstimateWorkspaceSize()¶

cutensorCreatePlan()¶

cutensorDestroyPlan()¶

cutensorPlanGetAttribute()¶

cutensorPlanPreferenceSetAttribute()¶

缓存相关操作¶

cutensorHandleResizePlanCache()¶

cutensorHandleReadPlanCacheFromFile()¶

cutensorHandleWritePlanCacheToFile()¶

cutensorReadKernelCacheFromFile()¶

cutensorWriteKernelCacheToFile()¶

日志记录器函数¶

cutensorLoggerSetCallback()¶

cutensorLoggerSetFile()¶

cutensorLoggerOpenFile()¶

cutensorLoggerSetLevel()¶

cutensorLoggerSetMask()¶

cutensorLoggerForceDisable()¶

`cutensorCreate()`¶

`cutensorDestroy()`¶

`cutensorCreateTensorDescriptor()`¶

`cutensorDestroyTensorDescriptor()`¶

`cutensorGetErrorString()`¶

`cutensorGetVersion()`¶

`cutensorGetCudartVersion()`¶

`cutensorCreateElementwiseTrinary()`¶

`cutensorElementwiseTrinaryExecute()`¶

`cutensorCreateElementwiseBinary()`¶

`cutensorElementwiseBinaryExecute()`¶

`cutensorCreatePermutation()`¶

`cutensorPermute()`¶

`cutensorCreateContraction()`¶

`cutensorContract()`¶

`cutensorCreateReduction()`¶

`cutensorReduce()`¶

`cutensorDestroyOperationDescriptor()`¶

`cutensorOperationDescriptorGetAttribute()`¶

`cutensorOperationDescriptorSetAttribute()`¶

`cutensorCreatePlanPreference()`¶

`cutensorDestroyPlanPreference()`¶

`cutensorPlanPreferenceSetAttribute()`¶

`cutensorEstimateWorkspaceSize()`¶

`cutensorCreatePlan()`¶

`cutensorDestroyPlan()`¶

`cutensorPlanGetAttribute()`¶

`cutensorPlanPreferenceSetAttribute()`¶

`cutensorHandleResizePlanCache()`¶

`cutensorHandleReadPlanCacheFromFile()`¶

`cutensorHandleWritePlanCacheToFile()`¶

`cutensorReadKernelCacheFromFile()`¶

`cutensorWriteKernelCacheToFile()`¶

`cutensorLoggerSetCallback()`¶

`cutensorLoggerSetFile()`¶

`cutensorLoggerOpenFile()`¶

`cutensorLoggerSetLevel()`¶

`cutensorLoggerSetMask()`¶

`cutensorLoggerForceDisable()`¶