cuStateVec API

库管理 ¶

句柄管理 API ¶

custatevecCreate ¶

custatevecStatus_t custatevecCreate(custatevecHandle_t *handle) ¶

此函数初始化 cuStateVec 库，并在 cuStateVec 上下文上创建一个句柄。它必须在调用任何其他 cuStateVec API 函数之前调用。 **参数** `handle` – **[in]** 指向 cuStateVec 上下文句柄的指针

custatevecDestroy ¶

custatevecStatus_t custatevecDestroy(custatevecHandle_t handle) ¶

此函数释放 cuStateVec 库使用的资源。 **参数** `handle` – **[in]** cuStateVec 上下文的句柄

custatevecGetDefaultWorkspaceSize ¶

custatevecStatus_t custatevecGetDefaultWorkspaceSize(custatevecHandle_t handle, size_t *workspaceSizeInBytes) ¶

此函数返回 cuStateVec 库定义的默认工作空间大小。 此函数返回用于工作空间的默认大小。 **参数** `handle` – **[in]** cuStateVec 上下文的句柄 `workspaceSizeInBytes` – **[out]** 默认工作空间大小

custatevecSetWorkspace ¶

custatevecStatus_t custatevecSetWorkspace(custatevecHandle_t handle, void *workspace, size_t workspaceSizeInBytes) ¶

此函数设置 cuStateVec 库使用的工作空间。 此函数设置附加到句柄的工作空间。所需的工作空间大小可通过 `custatevecGetDefaultWorkspaceSize()` 获取。 通过设置更大的工作空间，用户能够在某些函数中无需额外分配工作空间即可执行。 如果设置了设备内存处理器，工作空间可以设置为空，并使用用户定义的内存池分配工作空间。 **参数** `handle` – **[in]** cuStateVec 上下文的句柄 `workspace` – **[in]** 指向工作空间的设备指针 `workspaceSizeInBytes` – **[in]** 工作空间大小

CUDA 流管理 API ¶

custatevecSetStream ¶

custatevecStatus_t custatevecSetStream(custatevecHandle_t handle, cudaStream_t streamId) ¶

此函数设置 cuStateVec 库执行其例程所使用的流。 **参数** `handle` – **[in]** cuStateVec 上下文的句柄 `streamId` – **[in]** 库要使用的流

custatevecGetStream ¶

custatevecStatus_t custatevecGetStream(custatevecHandle_t handle, cudaStream_t *streamId) ¶

此函数获取 cuStateVec 库用于执行 cuStateVec 库函数所有调用的流。 **参数** `handle` – **[in]** cuStateVec 上下文的句柄 `streamId` – **[out]** 库要使用的流

错误管理 API ¶

custatevecGetErrorName ¶

const char *custatevecGetErrorName(custatevecStatus_t status) ¶

此函数返回输入错误代码的名称字符串。如果无法识别错误代码，则返回“unrecognized error code”。 **参数** `status` – **[in]** 要转换为字符串的错误代码

custatevecGetErrorString ¶

const char *custatevecGetErrorString(custatevecStatus_t status) ¶

此函数返回错误代码的描述字符串。如果无法识别错误代码，则返回“unrecognized error code”。 **参数** `status` – **[in]** 要转换为字符串的错误代码

日志记录器 API ¶

custatevecLoggerSetCallback ¶

custatevecStatus_t custatevecLoggerSetCallback(custatevecLoggerCallback_t callback) ¶

**实验性功能**：此函数设置日志记录回调函数。 **参数** `callback` – **[in]** 指向回调函数的指针。参见 `custatevecLoggerCallback_t`。

custatevecLoggerSetCallbackData ¶

custatevecStatus_t custatevecLoggerSetCallbackData(custatevecLoggerCallbackData_t callback, void *userData) ¶

**实验性功能**：此函数设置带用户数据的日志记录回调函数。 **参数** `callback` – **[in]** 指向回调函数的指针。参见 `custatevecLoggerCallbackData_t`。 `userData` – **[in]** 指向用户提供数据的指针。

custatevecLoggerSetFile ¶

custatevecStatus_t custatevecLoggerSetFile(FILE *file) ¶

**实验性功能**：此函数设置日志记录输出文件。 **注意** 通过此函数调用注册后，除非再次调用该函数切换到不同的文件句柄，否则不得关闭所提供的文件句柄。 **参数** `file` – **[in]** 指向已打开文件的指针。文件应具有写入权限。

custatevecLoggerOpenFile ¶

custatevecStatus_t custatevecLoggerOpenFile(const char *logFile) ¶

**实验性功能**：此函数在给定路径打开一个日志记录输出文件。 **参数** `logFile` – **[in]** 日志记录输出文件的路径。

custatevecLoggerSetLevel ¶

custatevecStatus_t custatevecLoggerSetLevel(int32_t level) ¶

**实验性功能**：此函数设置日志记录级别的值。 级别定义如下： | 级别 | 摘要 | 详细描述 | | :--- | :--- | :--- | | "0" | 关闭 | 禁用日志记录（默认） | | "1" | 错误 | 仅记录错误 | | "2" | 性能追踪 | 启动 CUDA 内核的 API 调用将记录其参数和重要信息 | | "3" | 性能提示 | 可能提高应用程序性能的提示 | | "4" | 启发式追踪 | 提供库执行的常规信息，可能包含启发式状态详情 | | "5" | API 追踪 | API 调用将记录其参数和重要信息 | **参数** `level` – **[in]** 日志记录级别的值。

custatevecLoggerSetMask ¶

custatevecStatus_t custatevecLoggerSetMask(int32_t mask) ¶

**实验性功能**：此函数设置日志记录掩码的值。掩码定义为以下掩码的组合： | 级别 | 描述 | | :--- | :--- | | "0" | 关闭 | | "1" | 错误 | | "2" | 性能追踪 | | "4" | 性能提示 | | "8" | 启发式追踪 | | "16" | API 追踪 | 有关详细信息，请参阅 `custatevecLoggerCallback_t`。 **参数** `mask` – **[in]** 日志记录掩码的值。

custatevecLoggerForceDisable ¶

custatevecStatus_t custatevecLoggerForceDisable() ¶

**实验性功能**：此函数为整个运行过程禁用日志记录。

版本管理 API ¶

custatevecGetProperty ¶

custatevecStatus_t custatevecGetProperty(libraryPropertyType type, int32_t *value) ¶

此函数返回 cuStateVec 库的版本信息。 **参数** `type` – **[in]** 请求的属性（MAJOR_VERSION、MINOR_VERSION 或 PATCH_LEVEL）。 `value` – **[out]** 请求属性的值。

custatevecGetVersion ¶

size_t custatevecGetVersion() ¶

此函数返回 cuStateVec 库的版本信息。

内存管理 API ¶

流序内存分配器（或简称为内存池）以流序方式从内存池异步分配/释放内存，这意味着排入流的存储器操作和计算具有明确定义的流间和流内依赖关系。目前有几个成熟的流序内存池实现，例如自 CUDA 11.2 起在 CUDA 驱动程序级别内置的 cudaMemPool_t（使得同一进程中的所有 CUDA 应用程序可以轻松共享同一池，参见此处）以及 RAPIDS 内存管理器（RMM）。详细介绍请参阅 NVIDIA 开发者博客。

新的设备内存处理器 API 允许用户将流序内存池绑定到库句柄，使得 cuStateVec 可以替用户处理大部分内存管理。下图说明了可以实现的功能：

MyMemPool pool = MyMemPool(); // 在实际应用程序中，在整个进程期间保持存活 int my_alloc(void* ctx, void** ptr, size_t size, cudaStream_t stream) { return reinterpret_cast<MyMemPool*>(ctx)->alloc(ptr, size, stream); } int my_dealloc(void* ctx, void* ptr, size_t size, cudaStream_t stream) { return reinterpret_cast<MyMemPool*>(ctx)->dealloc(ptr, size, stream); } // 创建一个内存处理器并填充库使用所需的成员 custatevecDeviceMemHandler_t handler; handler.ctx = reinterpret_cast<void*>(&pool); handler.device_alloc = my_alloc; handler.device_free = my_dealloc; memcpy(handler.name, std::string("my pool").c_str(), CUSTATEVEC_ALLOCATOR_NAME_LEN); // 将处理器绑定到库句柄 custatevecSetDeviceMemHandler(handle, &handler); /* ... 照常使用门操作应用 ... */ // 用户无需计算所需大小 // 用户无需查询工作空间大小（但如果需要也可以查询） // 用户无需分配内存！ // 用户设置空指针以指示库应从用户的内存池中获取内存； void* extraWorkspace = nullptr; size_t extraWorkspaceInBytes = 0; custatevecApplyMatrix( handle, sv, svDataType, nIndexBits, matrix, matrixDataType, layout, adjoint, targets, nTargets, controls, nControls, controlBitValues, computeType, extraWorkspace, extraWorkspaceSizeInBytes); // 用户无需释放内存！

如上所示，可以跳过对工作空间相关 API 的几个调用。此外，允许库共享您的内存池不仅可以缓解潜在的内存冲突，还可以实现可能的优化。

在当前版本中，只能绑定设备内存池。

custatevecSetDeviceMemHandler ¶

custatevecStatus_t custatevecSetDeviceMemHandler(custatevecHandle_t handle, const custatevecDeviceMemHandler_t *handler) ¶

设置当前的设备内存处理器。 一旦设置，当 cuStateVec 在各种 API 调用中需要设备内存时，它将从用户提供的内存池中分配，并在完成后释放。有关进一步详细信息，请参阅 `custatevecDeviceMemHandler_t` 以及需要额外工作空间的 API。 内部流序是通过用户提供的流（通过 `custatevecSetStream()` 设置）建立的。 如果 `handler` 参数设置为 nullptr，库句柄将分离其现有的内存处理器。 **警告** 以下场景的行为是未定义的： * 库句柄先绑定到一个内存处理器，随后又绑定到另一个处理器 * 库句柄的存活时间超过了所附加的内存池 * 内存池不是流序的 **参数** `handle` – **[in]** 保存 cuStateVec 库上下文的不透明句柄。 `handler` – **[in]** 封装了用户内存池的设备内存处理器。结构体内容在内部被复制。

custatevecGetDeviceMemHandler ¶

custatevecStatus_t custatevecGetDeviceMemHandler(custatevecHandle_t handle, custatevecDeviceMemHandler_t *handler) ¶

获取当前的设备内存处理器。 **参数** `handle` – **[in]** 保存 cuStateVec 库上下文的不透明句柄。 `handler` – **[out]** 如果先前已设置，则填充 `handler` 所指向的结构体，否则返回 `CUSTATEVEC_STATUS_NO_DEVICE_ALLOCATOR`。

初始化 ¶

cuStateVec API 中的 custatevecInitializeStateVector() 函数可用于将状态向量初始化为一组预设状态中的任意一个。详细信息请参阅 custatevecStateVectorType_t。

使用示例 ¶

// 初始化状态向量 custatevecInitializeStateVector(handle, sv, svDataType, nIndexBits, svType);

API 参考 ¶
custatevecInitializeStateVector ¶

custatevecStatus_t custatevecInitializeStateVector(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, custatevecStateVectorType_t svType) ¶

将状态向量初始化为特定形式。 **参数** `handle` – **[in]** cuStateVec 库的句柄 `sv` – **[inout]** 状态向量 `svDataType` – **[in]** 状态向量的数据类型 `nIndexBits` – **[in]** 索引比特数 `svType` – **[in]** 目标量子态

门操作应用 ¶

通用矩阵 ¶

cuStateVec API 中的 custatevecApplyMatrix() 可以将表示量子门的矩阵应用于状态向量。对于大型矩阵，该 API 可能需要外部工作空间，而 custatevecApplyMatrixGetWorkspaceSize() 可提供工作空间的大小。如果设置了设备内存处理器，则可以跳过 custatevecApplyMatrixGetWorkspaceSize()。

custatevecApplyMatrixBatchedGetWorkspaceSize() 和 custatevecApplyMatrixBatched() 可以将矩阵应用于批处理的状态向量。有关批处理状态向量模拟的概述，请参阅批处理状态向量部分。

使用示例 ¶

// 检查外部工作空间的大小 custatevecApplyMatrixGetWorkspaceSize( handle, svDataType, nIndexBits, matrix, matrixDataType, layout, adjoint, nTargets, nControls, computeType, &extraWorkspaceSizeInBytes); // 如有必要，分配外部工作空间 void* extraWorkspace = nullptr; if (extraWorkspaceSizeInBytes > 0) cudaMalloc(&extraWorkspace, extraWorkspaceSizeInBytes); // 应用量子门 custatevecApplyMatrix( handle, sv, svDataType, nIndexBits, matrix, matrixDataType, layout, adjoint, targets, nTargets, controls, controlBitValues, nControls, computeType, extraWorkspace, extraWorkspaceSizeInBytes);

API 参考 ¶

custatevecApplyMatrixGetWorkspaceSize ¶

custatevecStatus_t custatevecApplyMatrixGetWorkspaceSize(custatevecHandle_t handle, cudaDataType_t svDataType, const uint32_t nIndexBits, const void *matrix, cudaDataType_t matrixDataType, custatevecMatrixLayout_t layout, const int32_t adjoint, const uint32_t nTargets, const uint32_t nControls, custatevecComputeType_t computeType, size_t *extraWorkspaceSizeInBytes) ¶

此函数获取 `custatevecApplyMatrix()` 所需的工作空间大小。 此函数返回执行 `custatevecApplyMatrix()` 所需的额外工作空间大小。对于给定的参数集，如果不需要额外缓冲区，`extraWorkspaceSizeInBytes` 将被设置为 0。 **参数** `handle` – **[in]** cuStateVec 上下文的句柄 `svDataType` – **[in]** 状态向量的数据类型 `nIndexBits` – **[in]** 状态向量的索引比特数 `matrix` – **[in]** 指向矩阵的主机或设备指针 `matrixDataType` – **[in]** 矩阵的数据类型 `layout` – **[in]** 指定矩阵内存布局的枚举器 `adjoint` – **[in]** 应用矩阵的伴随 `nTargets` – **[in]** 目标比特数 `nControls` – **[in]** 控制比特数 `computeType` – **[in]** 矩阵乘法的计算类型 `extraWorkspaceSizeInBytes` – **[out]** 工作空间大小

custatevecApplyMatrix ¶

custatevecStatus_t custatevecApplyMatrix(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, const void *matrix, cudaDataType_t matrixDataType, custatevecMatrixLayout_t layout, const int32_t adjoint, const int32_t *targets, const uint32_t nTargets, const int32_t *controls, const int32_t *controlBitValues, const uint32_t nControls, custatevecComputeType_t computeType, void *extraWorkspace, size_t extraWorkspaceSizeInBytes) ¶

应用门矩阵。 将门矩阵应用于状态向量。状态向量的大小为 \(2^{nIndexBits}\)。 `matrix` 参数是指向方阵二维数组的主机或设备指针。矩阵的大小为 \((2^{nTargets} \times 2^{nTargets})\)，其值类型由 `matrixDataType` 参数指定。`layout` 参数指定矩阵布局，可以是行优先或列优先顺序。`targets` 和 `controls` 参数指定状态向量索引中的目标和控制比特位置。 `controlBitValues` 参数指定控制比特的比特值。`controlBitValues` 的顺序由 `controls` 参数指定。如果为此参数指定空指针，则所有控制比特值都设置为 1。 根据定义，`targets` 和 `controls` 参数中的比特位置不应重叠。 对于较大的 `nTargets`，此函数可能返回 `CUSTATEVEC_STATUS_INSUFFICIENT_WORKSPACE`。在这种情况下，应指定 `extraWorkspace` 和 `extraWorkspaceSizeInBytes` 参数以提供额外工作空间。所需额外工作空间的大小可通过调用 `custatevecApplyMatrixGetWorkspaceSize()` 获得。如果不需要额外工作空间，可以向 `extraWorkspace` 参数传递空指针。此外，如果设置了设备内存处理器，`extraWorkspace` 可以设置为空，`extraWorkspaceSizeInBytes` 可以设置为 0。 **参数** `handle` – **[in]** cuStateVec 库的句柄 `sv` – **[inout]** 状态向量 `svDataType` – **[in]** 状态向量的数据类型 `nIndexBits` – **[in]** 状态向量的索引比特数 `matrix` – **[in]** 指向方阵的主机或设备指针 `matrixDataType` – **[in]** 矩阵的数据类型 `layout` – **[in]** 指定矩阵内存布局的枚举器 `adjoint` – **[in]** 应用矩阵的伴随 `targets` – **[in]** 指向目标比特主机数组的指针 `nTargets` – **[in]** 目标比特数 `controls` – **[in]** 指向控制比特主机数组的指针 `controlBitValues` – **[in]** 指向控制比特值主机数组的指针 `nControls` – **[in]** 控制比特数 `computeType` – **[in]** 矩阵乘法的计算类型 `extraWorkspace` – **[in]** 额外工作空间 `extraWorkspaceSizeInBytes` – **[in]** 额外工作空间大小

custatevecApplyMatrixBatchedGetWorkspaceSize ¶

custatevecStatus_t custatevecApplyMatrixBatchedGetWorkspaceSize(custatevecHandle_t handle, cudaDataType_t svDataType, const uint32_t nIndexBits, const uint32_t nSVs, const custatevecIndex_t svStride, custatevecMatrixMapType_t mapType, const int32_t *matrixIndices, const void *matrices, cudaDataType_t matrixDataType, custatevecMatrixLayout_t layout, const int32_t adjoint, const uint32_t nMatrices, const uint32_t nTargets, const uint32_t nControls, custatevecComputeType_t computeType, size_t *extraWorkspaceSizeInBytes) ¶

此函数获取 `custatevecApplyMatrixBatched()` 所需的工作空间大小。 此函数返回执行 `custatevecApplyMatrixBatched()` 所需的额外工作空间大小。对于给定的参数集，如果不需要额外缓冲区，`extraWorkspaceSizeInBytes` 将被设置为 0。 **参数** `handle` – **[in]** cuStateVec 上下文的句柄 `svDataType` – **[in]** 状态向量的数据类型 `nIndexBits` – **[in]** 状态向量的索引比特数 `nSVs` – **[in]** 状态向量的数量 `svStride` – **[in]** 两个连续状态向量之间的距离 `mapType` – **[in]** 指定矩阵分配方式的枚举器 `matrixIndices` – **[in]** 指向矩阵索引的主机或设备数组的指针 `matrices` – **[in]** 指向主机或设备上单个连续内存块中分配的矩阵的指针 `matrixDataType` – **[in]** 矩阵的数据类型 `layout` – **[in]** 指定矩阵内存布局的枚举器 `adjoint` – **[in]** 应用矩阵的伴随 `nMatrices` – **[in]** 矩阵的数量 `nTargets` – **[in]** 目标比特数 `nControls` – **[in]** 控制比特数 `computeType` – **[in]** 矩阵乘法的计算类型 `extraWorkspaceSizeInBytes` – **[out]** 工作空间大小

custatevecApplyMatrixBatched ¶

custatevecStatus_t custatevecApplyMatrixBatched(custatevecHandle_t handle, void *batchedSv, cudaDataType_t svDataType, const uint32_t nIndexBits, const uint32_t nSVs, custatevecIndex_t svStride, custatevecMatrixMapType_t mapType, const int32_t *matrixIndices, const void *matrices, cudaDataType_t matrixDataType, custatevecMatrixLayout_t layout, const int32_t adjoint, const uint32_t nMatrices, const int32_t *targets, const uint32_t nTargets, const int32_t *controls, const int32_t *controlBitValues, const uint32_t nControls, custatevecComputeType_t computeType, void *extraWorkspace, size_t extraWorkspaceSizeInBytes) ¶

此函数将一个门矩阵应用于一组批处理状态向量中的每一个。 此函数为 `batchedSv` 参数给出的批处理状态向量中的每一个应用一个门矩阵。批处理状态向量在单个设备内存块中分配，其间隔由 `svStride` 参数指定。每个状态向量的大小为 \(2^{nIndexBits}\)，状态向量的数量由 `nSVs` 参数指定。 `mapType` 参数指定将矩阵分配给状态向量的方式，`matrixIndices` 参数指定状态向量的矩阵索引。当 `mapType` 为 `CUSTATEVEC_MATRIX_MAP_TYPE_MATRIX_INDEXED` 时，第 \(i\) 个矩阵将分配给第 \(i\) 个状态向量。当 `mapType` 为 `CUSTATEVEC_MATRIX_MAP_TYPE_MATRIX_INDEXED` 时，`matrixIndices` 应包含 `nSVs` 个整数；当 `mapType` 为 `CUSTATEVEC_MATRIX_MAP_TYPE_BROADCAST` 时，`matrixIndices` 可以是空指针。 `matrices` 参数是指向方阵二维数组的主机或设备指针。矩阵的大小为 \((2^{nTargets} \times 2^{nTargets})\)，其值类型由 `matrixDataType` 参数指定。`layout` 参数指定矩阵布局，可以是行优先或列优先顺序。`targets` 和 `controls` 参数指定状态向量索引中的目标和控制比特位置。在此 API 中，这些比特位置对于所有批处理状态向量是统一的。 `controlBitValues` 参数指定控制比特的比特值。`controlBitValues` 的顺序由 `controls` 参数指定。如果为此参数指定空指针，则所有控制比特值都设置为 1。 根据定义，`targets` 和 `controls` 参数中的比特位置不应重叠。 对于较大的 `nTargets`，此函数可能返回 `CUSTATEVEC_STATUS_INSUFFICIENT_WORKSPACE`。在这种情况下，应指定 `extraWorkspace` 和 `extraWorkspaceSizeInBytes` 参数以提供额外工作空间。所需额外工作空间的大小可通过调用 `custatevecApplyMatrixBatchedGetWorkspaceSize()` 获得。如果不需要额外工作空间，可以向 `extraWorkspace` 参数传递空指针。此外，如果设置了设备内存处理器，`extraWorkspace` 可以设置为空，`extraWorkspaceSizeInBytes` 可以设置为 0。 **注意** 在此版本中，即使 `matrixIndices` 参数包含无效的矩阵索引，此 API 也不会返回任何错误。但是，在适用的情况下，错误消息将打印到 stdout。 **参数** `handle` – **[in]** cuStateVec 库的句柄 `batchedSv` – **[inout]** 在设备上单个连续内存块中分配的批处理状态向量 `svDataType` – **[in]** 状态向量的数据类型 `nIndexBits` – **[in]** 状态向量的索引比特数 `nSVs` – **[in]** 状态向量的数量 `svStride` – **[in]** 两个连续状态向量之间的距离 `mapType` – **[in]** 指定矩阵分配方式的枚举器 `matrixIndices` – **[in]** 指向矩阵索引的主机或设备数组的指针 `matrices` – **[in]** 指向主机或设备上单个连续内存块中分配的矩阵的指针 `matrixDataType` – **[in]** 矩阵的数据类型 `layout` – **[in]** 指定矩阵内存布局的枚举器 `adjoint` – **[in]** 应用矩阵的伴随 `nMatrices` – **[in]** 矩阵的数量 `targets` – **[in]** 指向目标比特主机数组的指针 `nTargets` – **[in]** 目标比特数 `controls` – **[in]** 指向控制比特主机数组的指针 `controlBitValues` – **[in]** 指向控制比特值主机数组的指针 `nControls` – **[in]** 控制比特数 `computeType` – **[in]** 矩阵乘法的计算类型 `extraWorkspace` – **[in]** 额外工作空间 `extraWorkspaceSizeInBytes` – **[in]** 额外工作空间大小

泡利矩阵 ¶

泡利矩阵张量积的指数可以表示如下：

eiθ⨂jPjeiθ⨂j​Pj​

矩阵 PP 可以是泡利矩阵 II、XX、YY 和 ZZ 中的任意一个，分别对应于 custatevecPauli_t 枚举值 CUSTATEVEC_PAULI_I、CUSTATEVEC_PAULI_X、CUSTATEVEC_PAULI_Y 和 CUSTATEVEC_PAULI_Z。详细信息请参阅 custatevecPauli_t。

使用示例 ¶

// 应用指数运算 custatevecApplyPauliRotation( handle, sv, svDataType, nIndexBits, theta, paulis, targets, nTargets, controls, controlBitValues, nControls);

API 参考 ¶

custatevecApplyPauliRotation ¶

custatevecStatus_t custatevecApplyPauliRotation(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, double theta, const custatevecPauli_t *paulis, const int32_t *targets, const uint32_t nTargets, const int32_t *controls, const int32_t *controlBitValues, const uint32_t nControls) ¶

应用多量子比特泡利算符的指数。 应用由 `bases` 指定的泡利基张量积的指数 \(e^{i \theta \bigotimes_j P_j}\)，其中 \(\bigotimes_j P_j\) 是泡利基的乘积。`paulis`、`targets` 和 `nTargets` 参数指定泡利基及其在状态向量索引中的比特位置。 应至少指定一个目标及其对应的泡利基。 `controls` 和 `nControls` 参数指定状态向