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} 	imes 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} 	imes 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θ⨂jPj

矩阵 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 	heta igotimes_j P_j})，其中 (igotimes_j P_j) 是泡利基的乘积。`paulis`、`targets` 和 `nTargets` 参数指定泡利基及其在状态向量索引中的比特位置。

应至少指定一个目标及其对应的泡利基。

`controls` 和 `nControls` 参数指定状态向量索引中的控制比特位置。

`controlBitValues` 参数指定控制比特的比特值。`controlBitValues` 的顺序由 `controls` 参数指定。如果为此参数指定空指针，则所有控制比特值都设置为 1。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sv` – **[inout]** 状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 状态向量索引中的比特数

        `theta` – **[in]** θ 值

        `paulis` – **[in]** 指向 `custatevecPauli_t` 数组的主机指针

        `targets` – **[in]** 指向目标比特主机数组的指针

        `nTargets` – **[in]** 目标比特数

        `controls` – **[in]** 指向控制比特主机数组的指针

        `controlBitValues` – **[in]** 指向控制比特值主机数组的指针

        `nControls` – **[in]** 控制比特数

广义置换矩阵 ¶

广义置换矩阵可以表示为置换矩阵 PP 和对角矩阵 DD 的乘积。例如，我们可以将一个 4×4 的广义置换矩阵 GG 分解如下：

G=PDG=PD

其中

P=[0100000110000010],D=[d00000d10000d20000d3]P=0010100000010100,D=d00000d10000d20000d3

当 DD 是对角矩阵时，广义置换矩阵也是对角矩阵。类似地，当 PP 是单位矩阵时，广义置换矩阵变为置换矩阵。

cuStateVec API custatevecApplyGeneralizedPermutationMatrix() 将类似 GG 的广义置换矩阵应用于状态向量。对于大型矩阵，该 API 可能需要额外工作空间，其大小可以通过 custatevecApplyGeneralizedPermutationMatrixGetWorkspaceSize() 查询。如果设置了设备内存处理器，则可以跳过 custatevecApplyGeneralizedPermutationMatrixGetWorkspaceSize()。

使用示例 ¶

// 检查外部工作空间的大小
custatevecApplyGeneralizedPermutationMatrixGetWorkspaceSize(
    handle, CUDA_C_64F, nIndexBits, permutation, diagonals, CUDA_C_64F, targets,
    nTargets, nControls, &extraWorkspaceSizeInBytes);

// 如有必要，分配外部工作空间
void* extraWorkspace = nullptr;
if (extraWorkspaceSizeInBytes > 0)
    cudaMalloc(&extraWorkspace, extraWorkspaceSizeInBytes);

// 应用广义置换矩阵
custatevecApplyGeneralizedPermutationMatrix(
    handle, d_sv, CUDA_C_64F, nIndexBits, permutation, diagonals, CUDA_C_64F,
    adjoint, targets, nTargets, controls, controlBitValues, nControls,
    extraWorkspace, extraWorkspaceSizeInBytes);

该操作等效于以下伪代码：

// sv, sv_temp: 状态向量和临时缓冲区。
int64_t sv_size = int64_t{1} << nIndexBits;
for (int64_t sv_idx = 0; sv_idx < sv_size; sv_idx++) {
    // 将 sv_idx 的基转换为置换基以获取 perm_idx
    auto perm_idx = convertToPermutationBasis(sv_idx);
    // 应用广义置换矩阵
    if (adjoint == 0)
        sv_temp[sv_idx] = sv[permutation[perm_idx]] * diagonals[perm_idx];
    else
        sv_temp[permutation[perm_idx]] = sv[sv_idx] * conj(diagonals[perm_idx]);
}

for (int64_t sv_idx = 0; sv_idx < sv_size; sv_idx++)
    sv[sv_idx] = sv_temp[sv_idx];

API 参考 ¶

custatevecApplyGeneralizedPermutationMatrixGetWorkspaceSize ¶

custatevecStatus_t custatevecApplyGeneralizedPermutationMatrixGetWorkspaceSize(custatevecHandle_t handle, cudaDataType_t svDataType, const uint32_t nIndexBits, const custatevecIndex_t *permutation, const void *diagonals, cudaDataType_t diagonalsDataType, const int32_t *targets, const uint32_t nTargets, const uint32_t nControls, size_t *extraWorkspaceSizeInBytes) ¶

获取 `custatevecApplyGeneralizedPermutationMatrix()` 所需的额外工作空间大小。

此函数获取执行 `custatevecApplyGeneralizedPermutationMatrix()` 所需的额外工作空间大小。对于给定的参数集，如果不需要额外缓冲区，`extraWorkspaceSizeInBytes` 将被设置为 0。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 状态向量的索引比特数

        `permutation` – **[in]** 指向置换表的主机或设备指针

        `diagonals` – **[in]** 指向对角线元素的主机或设备指针

        `diagonalsDataType` – **[in]** 对角线元素的数据类型

        `targets` – **[in]** 指向目标比特主机数组的指针

        `nTargets` – **[in]** 目标比特数

        `nControls` – **[in]** 控制比特数

        `extraWorkspaceSizeInBytes` – **[out]** 额外工作空间大小

custatevecApplyGeneralizedPermutationMatrix ¶

custatevecStatus_t custatevecApplyGeneralizedPermutationMatrix(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, custatevecIndex_t *permutation, const void *diagonals, cudaDataType_t diagonalsDataType, const int32_t adjoint, const int32_t *targets, const uint32_t nTargets, const int32_t *controls, const int32_t *controlBitValues, const uint32_t nControls, void *extraWorkspace, size_t extraWorkspaceSizeInBytes) ¶

应用广义置换矩阵。

此函数应用广义置换矩阵。

广义置换矩阵 (G) 表示为 (G = P D)，其中 (D) 和 (P) 分别是对角矩阵和置换矩阵。

置换矩阵 (P) 被指定为置换表，它是一个 `custatevecIndex_t` 数组，并传递给 `permutation` 参数。

对角矩阵 (D) 被指定为对角线元素数组。两个数组的长度都是 (2^{nTargets})。`diagonalsDataType` 参数指定对角线元素的类型。

以下是此版本中可用的 `svDataType` 和 `diagonalsDataType` 参数组合表：

| svDataType | diagonalsDataType |
| :--- | :--- |
| CUDA_C_64F | CUDA_C_64F |
| CUDA_C_32F | CUDA_C_64F |
| CUDA_C_32F | CUDA_C_32F |

此函数也可用于仅应用对角矩阵或置换矩阵。通过向 `permutation` 参数传递空指针，(P) 被视为单位矩阵，因此仅应用对角矩阵。同样，如果向 `diagonals` 参数传递空指针，(D) 被视为单位矩阵，仅应用置换矩阵。

`permutation` 参数应包含 ([0, 2^{nTargets})) 范围内的整数。每个整数只能出现一次，否则此函数的行为是未定义的。

`permutation` 和 `diagonals` 参数不应同时为空。在这种情况下，此函数返回 `CUSTATEVEC_STATUS_INVALID_VALUE`。

对于较大的 `nTargets` 或 `nIndexBits`，此函数可能返回 `CUSTATEVEC_STATUS_INSUFFICIENT_WORKSPACE`。在这种情况下，应指定 `extraWorkspace` 和 `extraWorkspaceSizeInBytes` 参数以提供额外工作空间。所需额外工作空间的大小可通过调用 `custatevecApplyGeneralizedPermutationMatrixGetWorkspaceSize()` 获得。

如果不需要额外工作空间，可以向 `extraWorkspace` 参数传递空指针。此外，如果设置了设备内存处理器，`extraWorkspace` 可以设置为空，`extraWorkspaceSizeInBytes` 可以设置为 0。

**注意**

在此版本中，即使指定了无效的 `permutation` 参数，`custatevecApplyGeneralizedPermutationMatrix()` 也不会返回错误。

**参数**

    `handle` – **[in]** cuStateVec 库的句柄

    `sv` – **[inout]** 状态向量

    `svDataType` – **[in]** 状态向量的数据类型

    `nIndexBits` – **[in]** 状态向量的索引比特数

    `permutation` – **[in]** 指向置换表的主机或设备指针

    `diagonals` – **[in]** 指向对角线元素的主机或设备指针

    `diagonalsDataType` – **[in]** 对角线元素的数据类型

    `adjoint` – **[in]** 应用广义置换矩阵的伴随

    `targets` – **[in]** 指向目标比特主机数组的指针

    `nTargets` – **[in]** 目标比特数

    `controls` – **[in]** 指向控制比特主机数组的指针

    `controlBitValues` – **[in]** 指向控制比特值主机数组的指针

    `nControls` – **[in]** 控制比特数

    `extraWorkspace` – **[in]** 额外工作空间

    `extraWorkspaceSizeInBytes` – **[in]** 额外工作空间大小

测量 ¶

Z基测量 ¶

让我们考虑在 nbnb 比特 Z 乘积基 ⨂j=0nb−1Zpj⨂j=0nb−1Zpj 上对 nn 量子比特状态向量进行测量。

在 Z 乘积基上，状态向量元素平方绝对值的和 S0S0 和 S1S1 通过以下公式获得：

S0=∑k: ⨁jbpj=0∣ψk∣2,S1=∑k: ⨁jbpj=1∣ψk∣2S0=k:⨁jbpj=0∑∣ψk∣2,S1=k:⨁jbpj=1∑∣ψk∣2

因此，获得奇偶性 0 和 1 的概率由以下表达式表示：

P0=S0S0+S1,P1=S1S0+S1P0=S0+S1S0,P1=S0+S1S1

根据测量结果，状态向量会发生坍缩。如果奇偶性等于 0，我们得到以下向量：

ψk′=ψkS0当⨁jbpj=0ψk′=S0ψk当j⨁bpj=0

如果奇偶性等于 1，我们得到以下向量：

ψk′=ψkS1当⨁jbpj=1ψk′=S1ψk当j⨁bpj=1

其中 1/S01/S0 或 1/S11/S1 是归一化因子。

使用示例 ¶

我们可以使用 custatevecMeasureOnZBasis() 进行测量，如下所示：

// 在 Z 基上进行测量
custatevecMeasureOnZBasis(
    handle, sv, svDataType, nIndexBits, &parity, basisBits, nBasisBits,
    randnum, collapse);

该操作等效于以下伪代码：

// 计算 Z 乘积基上状态向量元素平方绝对值的和
double abs2sum0, abs2sum1;
custatevecAbs2SumOnZBasis(
    handle, sv, svDataType, nIndexBits, &abs2sum0, &abs2sum1, basisBits,
    nBasisBits);

// [用户] 计算奇偶性和归一化因子
double abs2sum = abs2sum0 + abs2sum1;
int parity = (randnum * abs2sum < abs2sum0) ? 0 : 1;
double norm = (parity == 0) ? abs2sum0 : abs2sum1;

// 必要时进行坍缩
switch (collapse) {
case CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO:
    custatevecCollapseOnZBasis(
        handle, sv, svDataType, nIndexBits, parity, basisBits, nBasisBits,
        norm);
    break;  /* 坍缩 */
case CUSTATEVEC_COLLAPSE_NONE:
    break;  /* 不执行任何操作 */
}

API 参考 ¶

custatevecAbs2SumOnZBasis ¶

custatevecStatus_t custatevecAbs2SumOnZBasis(custatevecHandle_t handle, const void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, double *abs2sum0, double *abs2sum1, const int32_t *basisBits, const uint32_t nBasisBits) ¶

计算给定 Z 乘积基上平方绝对值的和。

此函数计算给定 Z 乘积基上平方绝对值的和。如果为 `abs2sum0` 或 `abs2sum1` 指定空指针，则不计算相应值的和。由于 `(abs2sum0 + abs2sum1)` 的和与状态向量的范数相同，因此可以将奇偶性 `parity == 0` 的概率计算为 `(abs2sum0 / (abs2sum0 + abs2sum1))`。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sv` – **[in]** 状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 索引比特数

        `abs2sum0` – **[out]** 指向主机或设备变量的指针，用于存储奇偶性为 0 的平方绝对值之和

        `abs2sum1` – **[out]** 指向主机或设备变量的指针，用于存储奇偶性为 1 的平方绝对值之和

        `basisBits` – **[in]** 指向 Z 基索引比特主机数组的指针

        `nBasisBits` – **[in]** `basisBits` 的数量

custatevecCollapseOnZBasis ¶

custatevecStatus_t custatevecCollapseOnZBasis(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, const int32_t parity, const int32_t *basisBits, const uint32_t nBasisBits, double norm) ¶

在给定 Z 乘积基上坍缩状态向量。

此函数在给定 Z 乘积基上坍缩状态向量。与 `parity` 参数匹配的状态元素按 `norm` 参数指定的因子缩放。其他元素设置为零。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sv` – **[inout]** 状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 索引比特数

        `parity` – **[in]** 奇偶性，0 或 1

        `basisBits` – **[in]** 指向 Z 基索引比特主机数组的指针

        `nBasisBits` – **[in]** Z 基比特数

        `norm` – **[in]** 归一化因子

custatevecMeasureOnZBasis ¶

custatevecStatus_t custatevecMeasureOnZBasis(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, int32_t *parity, const int32_t *basisBits, const uint32_t nBasisBits, const double randnum, enum custatevecCollapseOp_t collapse) ¶

在给定 Z 乘积基上进行测量。

此函数在给定 Z 乘积基上进行测量。测量结果是指定 Z 乘积基的奇偶性。应至少指定一个基比特，否则此函数将失败。

如果为 `collapse` 参数指定 `CUSTATEVEC_COLLAPSE_NONE`，则此函数仅返回测量结果而不坍缩状态向量。如果指定 `CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO`，则此函数会像 `custatevecCollapseOnZBasis()` 那样坍缩状态向量。

如果随机数不在 [0, 1) 范围内，此函数返回 `CUSTATEVEC_STATUS_INVALID_VALUE`。应至少指定一个基比特，否则此函数返回 `CUSTATEVEC_STATUS_INVALID_VALUE`。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sv` – **[inout]** 状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 索引比特数

        `parity` – **[out]** 奇偶性，0 或 1

        `basisBits` – **[in]** 指向 Z 基比特主机数组的指针

        `nBasisBits` – **[in]** Z 基比特数

        `randnum` – **[in]** 随机数，[0, 1)

        `collapse` – **[in]** 坍缩操作

量子比特测量 ¶

假设我们使用 mm 比特的比特串 {qj}j=0m−1{qj}j=0m−1 测量 nn 量子比特状态向量。

状态向量元素平方绝对值的和通过以下公式获得：

Sb=∑k: ∀j, bqj=bj∣ψk∣2Sb=k:∀j,bqj=bj∑∣ψk∣2

其中 b=(b0,b1,…,bm−1)b=(b0,b1,…,bm−1)，bj∈{0,1}bj∈{0,1}。

因此，获得第 bb 种比特模式的概率由以下表达式表示：

Pb=Sb∑b′Sb′Pb=∑b′Sb′Sb

根据测量结果，状态向量会发生坍缩。

如果 bb 满足 Sb>0Sb>0，我们得到：

ψk′=ψkSb当∀j, bqj=bjψk′=Sbψk当∀j,bqj=bj

否则，ψk′=0ψk′=0，其中 1/Sb1/Sb 是归一化因子。

使用示例 ¶

我们可以使用 custatevecBatchMeasure() 进行测量，如下所示：

// 使用比特串进行测量
custatevecBatchMeasure(
    handle, sv, svDataType, nIndexBits, bitString, bitOrdering, bitStringLen,
    randnum, collapse);

该操作等效于以下伪代码：

// 计算状态向量元素平方绝对值的和
int maskLen = 0;
int* maskBitString = nullptr;
int* maskOrdering = nullptr;

custatevecAbs2SumArray(
    handle, sv, svDataType, nIndexBits, abs2Sum, bitOrdering, bitOrderingLen,
    maskBitString, maskOrdering, maskLen);

// [用户] 计算累积和并通过随机数选择比特串

// 必要时进行坍缩
switch (collapse) {
case CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO:
    custatevecCollapseByBitString(
        handle, sv, svDataType, nIndexBits, bitString, bitOrdering,
        bitStringLen, norm);
    break;  /* 坍缩 */
case CUSTATEVEC_COLLAPSE_NONE:
    break;  /* 不执行任何操作 */
}

对于批处理状态向量，可以使用 custatevecAbs2SumArrayBatched()、custatevecCollapseByBitStringBatched() 和 custatevecMeasureBatched()。有关批处理状态向量模拟的概述，请参阅批处理状态向量部分。

对于多 GPU 计算，可以使用 custatevecBatchMeasureWithOffset()。此函数在一个设备上工作，用户需要预先计算状态向量元素平方绝对值的累积数组。

// 状态向量被划分为 nSubSvs 个子状态向量。
// 每个状态向量有自己的序号和 nLocalBits 个索引比特。
// 子状态向量的序号对应于扩展的索引比特。
// 在此示例中，所有本地量子比特都被测量并坍缩。

// 获取每个子状态向量的 abs2sum
double abs2SumArray[nSubSvs];
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]);
    custatevecAbs2SumArray(
        handle[iSv], d_sv[iSv], CUDA_C_64F, nLocalBits, &abs2SumArray[iSv], nullptr,
        0, nullptr, nullptr, 0);
}

for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]);
    cudaDeviceSynchronize();
}

// 获取累积数组
double cumulativeArray[nSubSvs + 1];
cumulativeArray[0] = 0.0;
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cumulativeArray[iSv + 1] = cumulativeArray[iSv] + abs2SumArray[iSv];
}

// 测量
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    // 检测将用于测量的子状态向量
    if (cumulativeArray[iSv] <= randnum && randnum < cumulativeArray[iSv + 1]) {
        double norm = cumulativeArray[nSubSvs];
        double offset = cumulativeArray[iSv];
        cudaSetDevice(devices[iSv]);
        // 测量本地量子比特。这里状态向量不会被坍缩。
        // 只有本地量子比特可以包含在 bitOrdering 和 bitString 参数中。
        // 即，bitOrdering = {0, 1, 2, ..., nLocalBits - 1}，
        // bitString 将存储本地量子比特的值作为整数数组。
        custatevecBatchMeasureWithOffset(
            handle[iSv], d_sv[iSv], CUDA_C_64F, nLocalBits, bitString, bitOrdering,
            bitStringLen, randnum, CUSTATEVEC_COLLAPSE_NONE, offset, norm);
    }
}

for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]);
    cudaDeviceSynchronize();
}

// 获取坍缩后的 abs2Sum
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]);
    custatevecAbs2SumArray(
        handle[iSv], d_sv[iSv], CUDA_C_64F, nLocalBits, &abs2SumArray[iSv], nullptr,
        0, bitString, bitOrdering, bitStringLen);
}

for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]);
    cudaDeviceSynchronize();
}

// 获取坍缩后的范数
double norm = 0.0;
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    norm += abs2SumArray[iSv];
}

// 坍缩子状态向量
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]);
    custatevecCollapseByBitString(
        handle[iSv], d_sv[iSv], CUDA_C_64F, nLocalBits, bitString, bitOrdering,
        bitStringLen, norm);
}

// 销毁句柄
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]);
    custatevecDestroy(handle[iSv]);
}

有关更多详细信息，请参阅 NVIDIA/cuQuantum 存储库。

API 参考 ¶

custatevecAbs2SumArray ¶

custatevecStatus_t custatevecAbs2SumArray(custatevecHandle_t handle, const void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, double *abs2sum, const int32_t *bitOrdering, const uint32_t bitOrderingLen, const int32_t *maskBitString, const int32_t *maskOrdering, const uint32_t maskLen) ¶

计算给定索引比特集的 abs2sum 数组。

计算状态向量元素平方绝对值的和数组。`abs2sum` 数组可以位于主机或设备上。`abs2sum` 数组的索引比特顺序由 `bitOrdering` 和 `bitOrderingLen` 参数指定。未指定的比特被折叠（求和）。

`maskBitString`、`maskOrdering` 和 `maskLen` 参数在状态向量索引中设置比特掩码。`abs2sum` 数组是通过使用索引与掩码比特串匹配的状态向量元素计算的。如果 `maskLen` 参数为 0，则可以为 `maskBitString` 和 `maskOrdering` 参数指定空指针，所有状态向量元素都用于计算。

根据定义，`bitOrdering` 和 `maskOrdering` 参数中的比特位置不应重叠。

可以指定空的 `bitOrdering` 来计算状态向量的范数。在这种情况下，向 `bitOrderingLen` 参数传递 0，`bitOrdering` 参数可以是空指针。

**注意**

由于 `abs2sum` 数组的大小与 (2^{bitOrderingLen}) 成正比，因此 `bitOrdering` 的最大长度取决于可用内存量和 `maskLen`。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sv` – **[in]** 状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 索引比特数

        `abs2sum` – **[out]** 指向平方绝对值之和的主机或设备数组的指针

        `bitOrdering` – **[in]** 指向索引比特顺序主机数组的指针

        `bitOrderingLen` – **[in]** `bitOrdering` 的长度

        `maskBitString` – **[in]** 指向用于指定掩码的比特串主机数组的指针

        `maskOrdering` – **[in]** 指向掩码顺序主机数组的指针

        `maskLen` – **[in]** 掩码的长度

custatevecCollapseByBitString ¶

custatevecStatus_t custatevecCollapseByBitString(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, const int32_t *bitString, const int32_t *bitOrdering, const uint32_t bitStringLen, double norm) ¶

将状态向量坍缩到给定比特串指定的状态。

此函数将状态向量坍缩到给定比特串指定的状态。由 `bitString`、`bitOrdering` 和 `bitStringLen` 参数指定的状态向量元素按 `norm` 参数归一化。其他元素设置为零。

应至少指定一个基比特，否则此函数返回 `CUSTATEVEC_STATUS_INVALID_VALUE`。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sv` – **[inout]** 状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 索引比特数

        `bitString` – **[in]** 指向比特串主机数组的指针

        `bitOrdering` – **[in]** 指向比特串顺序主机数组的指针

        `bitStringLen` – **[in]** 比特串长度

        `norm` – **[in]** 归一化常数

custatevecBatchMeasure ¶

custatevecStatus_t custatevecBatchMeasure(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, int32_t *bitString, const int32_t *bitOrdering, const uint32_t bitStringLen, const double randnum, enum custatevecCollapseOp_t collapse) ¶

批量单量子比特测量。

此函数执行批量单量子比特测量并返回一个比特串。`bitOrdering` 参数指定要测量的索引比特。测量结果按照 `bitOrdering` 参数指定的顺序存储在 `bitString` 中。

如果为 `collapse` 参数指定 `CUSTATEVEC_COLLAPSE_NONE`，则此函数仅返回测量的比特串而不坍缩状态向量。当指定 `CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO` 时，此函数会像 `custatevecCollapseByBitString()` 那样坍缩状态向量。

如果随机数不在 [0, 1) 范围内，此函数返回 `CUSTATEVEC_STATUS_INVALID_VALUE`。应至少指定一个基比特，否则此函数返回 `CUSTATEVEC_STATUS_INVALID_VALUE`。

**注意**

此 API 用于测量单个状态向量。对于测量批处理状态向量，请使用 `custatevecMeasureBatched()`，其参数以不同的约定传递。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sv` – **[inout]** 状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 索引比特数

        `bitString` – **[out]** 指向测量的比特串主机数组的指针

        `bitOrdering` – **[in]** 指向比特串顺序主机数组的指针

        `bitStringLen` – **[in]** `bitString` 的长度

        `randnum` – **[in]** 随机数，[0, 1)

        `collapse` – **[in]** 坍缩操作

custatevecAbs2SumArrayBatched ¶

custatevecStatus_t custatevecAbs2SumArrayBatched(custatevecHandle_t handle, const void *batchedSv, cudaDataType_t svDataType, const uint32_t nIndexBits, const uint32_t nSVs, const custatevecIndex_t svStride, double *abs2sumArrays, const custatevecIndex_t abs2sumArrayStride, const int32_t *bitOrdering, const uint32_t bitOrderingLen, const custatevecIndex_t *maskBitStrings, const int32_t *maskOrdering, const uint32_t maskLen) ¶

计算给定索引比特集的批处理 abs2sum 数组。

`custatevecAbs2SumArray()` 的批处理版本，计算从批处理状态向量中获取的平方绝对值之和的批处理数组。

状态向量放置在单个连续设备内存块中。`svStride` 参数指定两个相邻状态向量之间的距离。因此，`svStride` 应大于或等于状态向量大小。

计算出的平方绝对值之和输出到 `abs2sumArrays`，这是一个连续内存块。`abs2sumArrayStride` 指定相邻两个 abs2sum 数组之间的距离。批处理的 abs2sum 数组可以位于主机或设备上。批处理中 abs2sum 数组的索引比特顺序由 `bitOrdering` 和 `bitOrderingLen` 参数指定。未指定的比特被折叠（求和）。

`maskBitStrings`、`maskOrdering` 和 `maskLen` 参数为批处理状态向量的索引比特指定比特掩码。`abs2sum` 数组是通过使用索引与指定掩码比特串匹配的状态向量元素计算的。`maskBitStrings` 参数指定一个掩码值数组，作为应用于状态向量索引的整型比特掩码。

如果 `maskLen` 参数为 0，则可以为 `maskBitStrings` 和 `maskOrdering` 参数指定空指针。在这种情况下，所有状态向量元素都用于计算平方绝对值的和，而不使用掩码。

根据定义，`bitOrdering` 和 `maskOrdering` 参数中的比特位置不应重叠。

可以指定空的 `bitOrdering` 来计算状态向量的范数。在这种情况下，向 `bitOrderingLen` 参数传递 0，`bitOrdering` 参数可以是空指针。

**注意**

在此版本中，即使 `maskBitStrings` 参数包含无效的比特串，此 API 也不会返回任何错误。但是，在适用的情况下，错误消息将打印到 stdout。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `batchedSv` – **[in]** 批处理状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 索引比特数

        `nSVs` – **[in]** 批处理中状态向量的数量

        `svStride` – **[in]** 状态向量的步长

        `abs2sumArrays` – **[out]** 指向平方绝对值之和的主机或设备数组的指针

        `abs2sumArrayStride` – **[in]** 连续 `abs2sumArrays` 之间的距离

        `bitOrdering` – **[in]** 指向索引比特顺序主机数组的指针

        `bitOrderingLen` – **[in]** `bitOrdering` 的长度

        `maskBitStrings` – **[in]** 指向掩码比特串的主机或设备数组的指针

        `maskOrdering` – **[in]** 指向掩码顺序主机数组的指针

        `maskLen` – **[in]** 掩码的长度

custatevecCollapseByBitStringBatchedGetWorkspaceSize ¶

custatevecStatus_t custatevecCollapseByBitStringBatchedGetWorkspaceSize(custatevecHandle_t handle, const uint32_t nSVs, const custatevecIndex_t *bitStrings, const double *norms, size_t *extraWorkspaceSizeInBytes) ¶

此函数获取 `custatevecCollapseByBitStringBatched()` 所需的工作空间大小。

此函数返回执行 `custatevecCollapseByBitStringBatched()` 所需的额外工作空间大小。如果不需要额外缓冲区，`extraWorkspaceSizeInBytes` 将被设置为 0。

**注意**

`bitStrings` 和 `norms` 数组的大小相同，都是 `nSVs`，可以位于主机或设备上，但在调用 `custatevecCollapseByBitStringBatched()` 时，它们的位置必须保持不变，否则计算出的工作空间大小可能变得无效并导致未定义行为。

**参数**

        `handle` – **[in]** cuStateVec 上下文的句柄

        `nSVs` – **[in]** 批处理状态向量的数量

        `bitStrings` – **[in]** 指向比特串数组的指针，位于主机或设备上

        `norms` – **[in]** 指向归一化常数数组的指针，位于主机或设备上

        `extraWorkspaceSizeInBytes` – **[out]** 工作空间大小

custatevecCollapseByBitStringBatched ¶

custatevecStatus_t custatevecCollapseByBitStringBatched(custatevecHandle_t handle, void *batchedSv, cudaDataType_t svDataType, const uint32_t nIndexBits, const uint32_t nSVs, const custatevecIndex_t svStride, const custatevecIndex_t *bitStrings, const int32_t *bitOrdering, const uint32_t bitStringLen, const double *norms, void *extraWorkspace, size_t extraWorkspaceSizeInBytes) ¶

将批处理状态向量坍缩到给定比特串指定的状态。

此函数将批处理中的所有状态向量坍缩到给定比特串指定的状态。批处理状态向量在单个设备内存块中分配，其间隔由 `svStride` 参数指定。每个状态向量的大小为 (2^{nIndexBits})，状态向量的数量由 `nSVs` 参数指定。

第 (i) 个状态向量的元素，由第 (i) 个 `bitStrings` 元素以及 `bitOrdering` 和 `bitStringLen` 参数指定，按第 (i) 个 `norms` 元素归一化。其他状态向量元素设置为零。

应至少指定一个基比特，否则此函数返回 `CUSTATEVEC_STATUS_INVALID_VALUE`。

请注意，`bitOrdering` 和 `bitStringLen` 适用于批处理中的所有状态向量，而 `bitStrings` 和 `norms` 数组的大小相同，都是 `nSVs`，可以位于主机或设备上。

`bitStrings` 参数应包含 ([0, 2^{bitStringLen})) 范围内的整数。

对于较大的 `nSVs` 和/或 `nIndexBits`，此函数可能返回 `CUSTATEVEC_STATUS_INSUFFICIENT_WORKSPACE`。在这种情况下，应指定 `extraWorkspace` 和 `extraWorkspaceSizeInBytes` 参数以提供额外工作空间。所需额外工作空间的大小可通过调用 `custatevecCollapseByBitStringBatchedGetWorkspaceSize()` 获得。如果不需要额外工作空间，可以向 `extraWorkspace` 参数传递空指针。此外，如果设置了设备内存处理器，`extraWorkspace` 可以设置为空，`extraWorkspaceSizeInBytes` 可以设置为 0。

**注意**

在此版本中，即使指定了无效的 `bitStrings` 或 `norms` 参数，`custatevecCollapseByBitStringBatched()` 也不会返回错误。但是，在适用的情况下，错误消息将打印到 stdout。

**注意**

与非批处理版本 (`custatevecCollapseByBitString()`) 不同，在此批处理版本中，`bitStrings` 存储为元素类型为 `custatevecIndex_t` 的数组；即，每个元素是一个表示二进制形式比特串的整数。这种用法与 `custatevecSamplerSample()` API 一致。有关进一步详细信息，请参阅“比特顺序”部分。

`bitStrings` 和 `norms` 数组的大小相同，都是 `nSVs`，可以位于主机或设备上，但在调用 `custatevecCollapseByBitStringBatchedGetWorkspaceSize()` 时，它们的位置必须保持不变，否则计算出的工作空间大小可能变得无效并导致未定义行为。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `batchedSv` – **[inout]** 在设备上单个连续内存块中分配的批处理状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 状态向量的索引比特数

        `nSVs` – **[in]** 批处理状态向量的数量

        `svStride` – **[in]** 两个连续状态向量之间的距离

        `bitStrings` – **[in]** 指向比特串数组的指针，位于主机或设备上

        `bitOrdering` – **[in]** 指向比特串顺序主机数组的指针

        `bitStringLen` – **[in]** 比特串长度

        `norms` – **[in]** 指向位于主机或设备上的归一化常数数组的指针

        `extraWorkspace` – **[in]** 额外工作空间

        `extraWorkspaceSizeInBytes` – **[in]** 额外工作空间的大小

custatevecMeasureBatched ¶

custatevecStatus_t custatevecMeasureBatched(custatevecHandle_t handle, void *batchedSv, cudaDataType_t svDataType, const uint32_t nIndexBits, const uint32_t nSVs, const custatevecIndex_t svStride, custatevecIndex_t *bitStrings, const int32_t *bitOrdering, const uint32_t bitStringLen, const double *randnums, enum custatevecCollapseOp_t collapse) ¶

批处理状态向量的单量子比特测量。

此函数测量批处理状态向量的比特串。`bitOrdering` 和 `bitStringLen` 参数指定要测量的索引比特位置的整数数组。测量结果返回到 `bitStrings`，这是一个 64 位整数比特掩码的 64 位整数数组。

示例：当指定 `bitOrdering = {3, 1}` 时，此函数测量两个索引比特。`bitStrings` 元素中的第 0 位表示索引比特 3 的测量结果，第 1 位表示索引比特 1 的测量结果。

批处理状态向量在单个连续内存块中给出，其中状态向量放置在 `svStride` 指定的距离处。`svStride` 以元素数量表示。

`randnums` 存储用于测量的随机数。随机数的数量与 `nSVs` 相同，值应在 [0, 1) 范围内。任何不在此范围内的随机数，其值将被裁剪到 [0, 1)。

如果为 `collapse` 参数指定 `CUSTATEVEC_COLLAPSE_NONE`，则此函数仅返回测量的比特串而不坍缩状态向量。当指定 `CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO` 时，此函数坍缩状态向量。坍缩状态向量后，所有状态向量的范数将为 1。

**注意**

此 API 用于测量批处理状态向量。对于测量单个状态向量，也可以使用 `custatevecBatchMeasure()`，其参数以不同的约定传递。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `batchedSv` – **[inout]** 批处理状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 索引比特数

        `nSVs` – **[in]** 批处理状态向量中状态向量的数量

        `svStride` – **[in]** 批处理中状态向量之间的距离

        `bitStrings` – **[out]** 指向测量的比特串的主机或设备数组的指针

        `bitOrdering` – **[in]** 指向比特串顺序主机数组的指针

        `bitStringLen` – **[in]** `bitString` 的长度

        `randnums` – **[in]** 指向随机数的主机或设备数组的指针

        `collapse` – **[in]** 坍缩操作

custatevecBatchMeasureWithOffset ¶

custatevecStatus_t custatevecBatchMeasureWithOffset(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, int32_t *bitString, const int32_t *bitOrdering, const uint32_t bitStringLen, const double randnum, enum custatevecCollapseOp_t collapse, const double offset, const double abs2sum) ¶

部分向量的批量单量子比特测量。

此函数执行批量单量子比特测量并返回一个比特串。`bitOrdering` 参数指定要测量的索引比特。测量结果按照 `bitOrdering` 参数指定的顺序存储在 `bitString` 中。

如果为 `collapse` 参数指定 `CUSTATEVEC_COLLAPSE_NONE`，则此函数仅返回测量的比特串而不坍缩状态向量。当指定 `CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO` 时，此函数会像 `custatevecCollapseByBitString()` 那样坍缩状态向量。

此函数假设 `sv` 是部分状态向量并丢弃一些最高有效比特。必须将较低索引的前缀和以及整个状态向量分别作为 `offset` 和 `abs2sum` 提供。当 `offset == abs2sum == 0` 时，此函数的行为与 `custatevecBatchMeasure()` 相同。

如果随机数不在 [0, 1) 范围内，此函数返回 `CUSTATEVEC_STATUS_INVALID_VALUE`。应至少指定一个基比特，否则此函数返回 `CUSTATEVEC_STATUS_INVALID_VALUE`。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sv` – **[inout]** 部分状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 索引比特数

        `bitString` – **[out]** 指向测量的比特串主机数组的指针

        `bitOrdering` – **[in]** 指向比特串顺序主机数组的指针

        `bitStringLen` – **[in]** `bitString` 的长度

        `randnum` – **[in]** 随机数，[0, 1)

        `collapse` – **[in]** 坍缩操作

        `offset` – **[in]** 平方绝对值的部分和

        `abs2sum` – **[in]** 整个状态向量的平方绝对值之和

期望值 ¶

通过矩阵计算期望值 ¶

期望值执行以下操作：

⟨ψ∣M∣ψ⟩⟨ψ∣M∣ψ⟩

其中 ∣ψ⟩∣ψ⟩ 是状态向量，MM 是矩阵或可观测量。用于计算期望值的 API custatevecComputeExpectation() 对于大型矩阵可能需要外部工作空间，而 custatevecComputeExpectationGetWorkspaceSize() 可提供工作空间的大小。如果设置了设备内存处理器，则可以跳过 custatevecComputeExpectationGetWorkspaceSize()。

custatevecComputeExpectationBatchedGetWorkspaceSize() 和 custatevecComputeExpectationBatched() 可以为批处理状态向量计算期望值。有关批处理状态向量模拟的概述，请参阅批处理状态向量部分。

使用示例 ¶

// 检查外部工作空间的大小
custatevecComputeExpectationGetWorkspaceSize(
    handle, svDataType, nIndexBits, matrix, matrixDataType, layout, nBasisBits, computeType,
    &extraWorkspaceSizeInBytes);

// 如有必要，分配外部工作空间
void* extraWorkspace = nullptr;
if (extraWorkspaceSizeInBytes > 0)
    cudaMalloc(&extraWorkspace, extraWorkspaceSizeInBytes);

// 执行期望值计算
custatevecComputeExpectation(
    handle, sv, svDataType, nIndexBits, expect, expectDataType, residualNorm,
    matrix, matrixDataType, layout, basisBits, nBasisBits, computeType,
    extraWorkspace, extraWorkspaceSizeInBytes);

API 参考 ¶

custatevecComputeExpectationGetWorkspaceSize ¶

custatevecStatus_t custatevecComputeExpectationGetWorkspaceSize(custatevecHandle_t handle, cudaDataType_t svDataType, const uint32_t nIndexBits, const void *matrix, cudaDataType_t matrixDataType, custatevecMatrixLayout_t layout, const uint32_t nBasisBits, custatevecComputeType_t computeType, size_t *extraWorkspaceSizeInBytes) ¶

此函数获取 `custatevecComputeExpectation()` 所需的工作空间大小。

此函数返回执行 `custatevecComputeExpectation()` 所需的额外工作空间大小。如果不需要额外缓冲区，`extraWorkspaceSizeInBytes` 将被设置为 0。

**参数**

        `handle` – **[in]** cuStateVec 上下文的句柄

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 状态向量的索引比特数

        `matrix` – **[in]** 指向矩阵的主机或设备指针

        `matrixDataType` – **[in]** 矩阵的数据类型

        `layout` – **[in]** 指定矩阵内存布局的枚举器

        `nBasisBits` – **[in]** 目标比特数

        `computeType` – **[in]** 矩阵乘法的计算类型

        `extraWorkspaceSizeInBytes` – **[out]** 额外工作空间的大小

custatevecComputeExpectation ¶

custatevecStatus_t custatevecComputeExpectation(custatevecHandle_t handle, const void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, void *expectationValue, cudaDataType_t expectationDataType, double *residualNorm, const void *matrix, cudaDataType_t matrixDataType, custatevecMatrixLayout_t layout, const int32_t *basisBits, const uint32_t nBasisBits, custatevecComputeType_t computeType, void *extraWorkspace, size_t extraWorkspaceSizeInBytes) ¶

计算矩阵可观测量期望值。

此函数计算给定矩阵可观测量的期望值。`expectationDataType` 参数可接受的值为 `CUDA_R_64F` 和 `CUDA_C_64F`。

`basisBits` 和 `nBasisBits` 参数指定计算期望值的基。对于 `computeType` 参数，可以使用与 `custatevecApplyMatrix()` 相同的组合。

对于较大的 `nBasisBits`，此函数可能返回 `CUSTATEVEC_STATUS_INSUFFICIENT_WORKSPACE`。在这种情况下，应指定 `extraWorkspace` 和 `extraWorkspaceSizeInBytes` 参数以提供额外工作空间。所需额外工作空间的大小可通过调用 `custatevecComputeExpectationGetWorkspaceSize()` 获得。如果不需要额外工作空间，可以向 `extraWorkspace` 参数传递空指针。此外，如果设置了设备内存处理器，`extraWorkspace` 可以设置为空，`extraWorkspaceSizeInBytes` 可以设置为 0。

**注意**

在此版本中，`residualNorm` 参数不可用。如果 `matrix` 参数给出的矩阵可能不是厄米矩阵，请为 `expectationDataType` 参数指定 `CUDA_C_64F`，并检查计算出的期望值的虚部。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sv` – **[in]** 状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 状态向量的索引比特数

        `expectationValue` – **[out]** 指向存储期望值变量的主机指针

        `expectationDataType` – **[in]** 期望值的数据类型

        `residualNorm` – **[out]** 矩阵类型测试的结果

        `matrix` – **[in]** 作为矩阵的可观测量

        `matrixDataType` – **[in]** 矩阵的数据类型

        `layout` – **[in]** 矩阵内存布局

        `basisBits` – **[in]** 指向基索引比特主机数组的指针

        `nBasisBits` – **[in]** 基比特数

        `computeType` – **[in]** 矩阵乘法的计算类型

        `extraWorkspace` – **[in]** 指向额外工作空间的指针

        `extraWorkspaceSizeInBytes` – **[in]** 额外工作空间的大小

注意

根据参数的不同，此函数可能相对于主机是异步的。在使用存储在 expectationValue 中的结果之前，请将流设置为当前设备的句柄，使用 cudaStreamSynchronize（用于同步）或 cudaStreamWaitEvent（用于建立流顺序）。

custatevecComputeExpectationBatchedGetWorkspaceSize ¶

custatevecStatus_t custatevecComputeExpectationBatchedGetWorkspaceSize(custatevecHandle_t handle, cudaDataType_t svDataType, const uint32_t nIndexBits, const uint32_t nSVs, const custatevecIndex_t svStride, const void *matrices, cudaDataType_t matrixDataType, custatevecMatrixLayout_t layout, const uint32_t nMatrices, const uint32_t nBasisBits, custatevecComputeType_t computeType, size_t *extraWorkspaceSizeInBytes) ¶

此函数获取 `custatevecComputeExpectationBatched()` 所需的工作空间大小。

此函数返回执行 `custatevecComputeExpectationBatched()` 所需的额外工作空间大小。如果不需要额外缓冲区，`extraWorkspaceSizeInBytes` 将被设置为 0。

**参数**

        `handle` – **[in]** cuStateVec 上下文的句柄

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 状态向量的索引比特数

        `nSVs` – **[in]** 状态向量的数量

        `svStride` – **[in]** 两个连续状态向量之间的距离

        `matrices` – **[in]** 指向主机或设备上单个连续内存块中分配的矩阵的指针

        `matrixDataType` – **[in]** 矩阵的数据类型

        `layout` – **[in]** 指定矩阵内存布局的枚举器

        `nMatrices` – **[in]** 矩阵的数量

        `nBasisBits` – **[in]** 基比特数

        `computeType` – **[in]** 矩阵乘法的计算类型

        `extraWorkspaceSizeInBytes` – **[out]** 额外工作空间的大小

custatevecComputeExpectationBatched ¶

custatevecStatus_t custatevecComputeExpectationBatched(custatevecHandle_t handle, const void *batchedSv, cudaDataType_t svDataType, const uint32_t nIndexBits, const uint32_t nSVs, custatevecIndex_t svStride, double2 *expectationValues, const void *matrices, cudaDataType_t matrixDataType, custatevecMatrixLayout_t layout, const uint32_t nMatrices, const int32_t *basisBits, const uint32_t nBasisBits, custatevecComputeType_t computeType, void *extraWorkspace, size_t extraWorkspaceSizeInBytes) ¶

为每个批处理状态向量计算矩阵可观测量的期望值。

此函数为 `batchedSv` 参数给出的批处理状态向量中的每一个计算给定矩阵可观测量的期望值。批处理状态向量在单个设备内存块中分配，其间隔由 `svStride` 参数指定。每个状态向量的大小为 (2^{nIndexBits})，状态向量的数量由 `nSVs` 参数指定。

`expectationValues` 参数指向输出期望值的单个内存块。无论输入数据类型如何，此 API 都以双精度（complex128）返回值。输出数组的大小为 ((nSVs 	imes nMatrices))，其主维度是 `nMatrices`。

`matrices` 参数是指向方阵二维数组的主机或设备指针。矩阵的大小为 ((2^{nBasisBits} 	imes 2^{nBasisBits}))，其值类型由 `matrixDataType` 参数指定。`layout` 参数指定矩阵布局，可以是行优先或列优先顺序。

`basisBits` 和 `nBasisBits` 参数指定计算期望值的基。对于 `computeType` 参数，可以使用与 `custatevecComputeExpectation()` 相同的组合。

对于较大的 `nBasisBits`，此函数可能返回 `CUSTATEVEC_STATUS_INSUFFICIENT_WORKSPACE`。在这种情况下，应指定 `extraWorkspace` 和 `extraWorkspaceSizeInBytes` 参数以提供额外工作空间。所需额外工作空间的大小可通过调用 `custatevecComputeExpectationBatchedGetWorkspaceSize()` 获得。如果不需要额外工作空间，可以向 `extraWorkspace` 参数传递空指针。此外，如果设置了设备内存处理器，`extraWorkspace` 可以设置为空，`extraWorkspaceSizeInBytes` 可以设置为 0。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `batchedSv` – **[in]** 在设备上单个连续内存块中分配的批处理状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 状态向量的索引比特数

        `nSVs` – **[in]** 状态向量的数量

        `svStride` – **[in]** 两个连续状态向量之间的距离

        `expectationValues` – **[out]** 指向存储期望值的主机数组的指针

        `matrices` – **[in]** 指向主机或设备上单个连续内存块中分配的矩阵的指针

        `matrixDataType` – **[in]** 矩阵的数据类型

        `layout` – **[in]** 矩阵内存布局

        `nMatrices` – **[in]** 矩阵的数量

        `basisBits` – **[in]** 指向基索引比特主机数组的指针

        `nBasisBits` – **[in]** 基比特数

        `computeType` – **[in]** 矩阵乘法的计算类型

        `extraWorkspace` – **[in]** 指向额外工作空间的指针

        `extraWorkspaceSizeInBytes` – **[in]** 额外工作空间的大小

泡利基上的期望值 ¶

cuStateVec API custatevecComputeExpectationsOnPauliBasis() 计算一批泡利字符串的期望值。每个可观测量可以表示如下：

⨂jPjj⨂Pj

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

使用示例 ¶

// 计算 Z(q1) 和 X(q0)Y(q2) 的范数和期望值

uint32_t nPauliOperatorArrays = 3;
custatevecPauli_t pauliOperators0[] = {};                                       // III
int32_t           basisBits0[]      = {};
custatevecPauli_t pauliOperators1[] = {CUSTATEVEC_PAULI_Z};                     // IZI
int32_t           basisBits1[]      = {1};
custatevecPauli_t pauliOperators2[] = {CUSTATEVEC_PAULI_X, CUSTATEVEC_PAULI_Y}; // XIY
int32_t           basisBits2[]      = {0, 2};
const uint32_t nBasisBitsArray[] = {0, 1, 2};

const custatevecPauli_t*
  pauliOperatorsArray[] = {pauliOperators0, pauliOperators1, pauliOperators2};
const int32_t *basisBitsArray[] = { basisBits0, basisBits1, basisBits2};

uint32_t nIndexBits = 3;
double expectationValues[nPauliOperatorArrays];

custatevecComputeExpectationsOnPauliBasis(
    handle, sv, svDataType, nIndexBits, expectationValues,
    pauliOperatorsArray, nPauliOperatorArrays,
    basisBitsArray, nBasisBitsArray);

API 参考 ¶

custatevecComputeExpectationsOnPauliBasis ¶

custatevecStatus_t custatevecComputeExpectationsOnPauliBasis(custatevecHandle_t handle, const void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, double *expectationValues, const custatevecPauli_t **pauliOperatorsArray, const uint32_t nPauliOperatorArrays, const int32_t **basisBitsArray, const uint32_t *nBasisBitsArray) ¶

计算一批（多量子比特）泡利算符的期望值。

此函数通过单次调用计算给定泡利算符序列的多个期望值。

单个泡利算符序列 `pauliOperators` 通过使用 `custatevecPauli_t` 数组表示。这些泡利算符作用的基比特由索引比特位置的数组表示。如果未为某个索引比特指定泡利算符，则隐含地假定为单位算符（`CUSTATEVEC_PAULI_I`）。

`pauliOperators` 和 `basisBits` 的长度相同，并由 `nBasisBits` 指定。

泡利算符序列的数量由 `nPauliOperatorArrays` 参数指定。

多个泡利算符序列以下列数组形式表示：

    * `pauliOperatorsArray` 参数是 `custatevecPauli_t` 数组的数组。
    * `basisBitsArray` 是基比特位置数组的数组。
    * `nBasisBitsArray` 参数保存泡利算符序列长度和基比特数组的数组。

计算出的期望值存储在由 `expectationValues` 参数指定的主机缓冲区中，其长度为 `nPauliOperatorArrays`。

如果为泡利算符序列指定的基比特有重复和/或超出 [0, `nIndexBits`) 范围，此函数返回 `CUSTATEVEC_STATUS_INVALID_VALUE`。

此函数接受空的泡利算符序列以获取状态向量的范数。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sv` – **[in]** 状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 状态向量的索引比特数

        `expectationValues` – **[out]** 指向存储期望值的主机数组的指针

        `pauliOperatorsArray` – **[in]** 指向泡利算符数组的主机数组的指针

        `nPauliOperatorArrays` – **[in]** 泡利算符数组的数量

        `basisBitsArray` – **[in]** 指向基比特数组的主机数组的指针

        `nBasisBitsArray` – **[in]** 指向基比特数量数组的主机指针

矩阵属性测试 ¶

API custatevecTestMatrixType() 可用于检查矩阵的属性。

如果一个矩阵 UU 是幺正矩阵，则 U†U=IU†U=I，其中 U†U† 是 UU 的共轭转置，II 是单位矩阵。

当为其参数指定 CUSTATEVEC_MATRIX_TYPE_UNITARY 时，此 API 计算 1-范数 ∥U†U−I∥1=∑i,j∣(U†U−I)i,j∣∥U†U−I∥1=∑i,j∣(U†U−I)i,j∣，其中 UU 是给定矩阵。如果 UU 是幺正矩阵，此值将近似为零。

如果一个矩阵 HH 是厄米矩阵，则 H=H†H=H†。

当为其参数指定 CUSTATEVEC_MATRIX_TYPE_HERMITIAN 时，此 API 计算 2-范数 ∥H−H†∥22=∑i,j∣(H−H†)i,j∣2∥H−H†∥22=∑i,j∣(H−H†)i,j∣2，其中 HH 是给定矩阵。如果 HH 是厄米矩阵，此值将近似为零。

该 API 对于大型矩阵可能需要外部工作空间，而 custatevecTestMatrixTypeGetWorkspaceSize() 可提供工作空间的大小。如果设置了设备内存处理器，用户无需提供显式的工作空间。

使用示例 ¶

double residualNorm;

void* extraWorkspace = nullptr;
size_t extraWorkspaceSizeInBytes = 0;

// 检查外部工作空间的大小
custatevecTestMatrixTypeGetWorkspaceSize(
    handle, matrixType, matrix, matrixDataType, layout,
    nTargets, adjoint, computeType, &extraWorkspaceSizeInBytes);

// 如有必要，分配外部工作空间
if (extraWorkspaceSizeInBytes > 0)
    cudaMalloc(&extraWorkspace, extraWorkspaceSizeInBytes);

// 执行测试
custatevecTestMatrixType(
    handle, &residualNorm, matrixType, matrix, matrixDataType, layout,
    nTargets, adjoint, computeType, extraWorkspace, extraWorkspaceSizeInBytes);

API 参考 ¶

custatevecTestMatrixTypeGetWorkspaceSize ¶

custatevecStatus_t custatevecTestMatrixTypeGetWorkspaceSize(custatevecHandle_t handle, custatevecMatrixType_t matrixType, const void *matrix, cudaDataType_t matrixDataType, custatevecMatrixLayout_t layout, const uint32_t nTargets, const int32_t adjoint, custatevecComputeType_t computeType, size_t *extraWorkspaceSizeInBytes) ¶

获取 `custatevecTestMatrixType()` 的额外工作空间大小。

此函数获取执行 `custatevecTestMatrixType()` 所需的额外工作空间大小。如果不需要额外缓冲区，`extraWorkspaceSizeInBytes` 将被设置为 0。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `matrixType` – **[in]** 矩阵类型

        `matrix` – **[in]** 指向矩阵的主机或设备指针

        `matrixDataType` – **[in]** 矩阵的数据类型

        `layout` – **[in]** 指定矩阵内存布局的枚举器

        `nTargets` – **[in]** 目标比特数，最多 15

        `adjoint` – **[in]** 控制是否测试矩阵伴随的标志

        `computeType` – **[in]** 计算类型

        `extraWorkspaceSizeInBytes` – **[out]** 工作空间大小

custatevecTestMatrixType ¶

custatevecStatus_t custatevecTestMatrixType(custatevecHandle_t handle, double *residualNorm, custatevecMatrixType_t matrixType, const void *matrix, cudaDataType_t matrixDataType, custatevecMatrixLayout_t layout, const uint32_t nTargets, const int32_t adjoint, custatevecComputeType_t computeType, void *extraWorkspace, size_t extraWorkspaceSizeInBytes) ¶

测试给定矩阵与厄米矩阵（或幺正矩阵）的偏差。

此函数测试给定矩阵的类型是否与 `matrixType` 参数给定的类型匹配。

对于幺正类型的测试，计算 (R = U^dagger U - I)，其中 (U) 是给定矩阵。返回 (R) 矩阵元素的绝对值之和。

对于厄米类型的测试，计算 (R = H - H^dagger)。返回 (R) 矩阵元素的平方绝对值之和。

对于较大的 `nTargets`，此函数可能返回 `CUSTATEVEC_STATUS_INSUFFICIENT_WORKSPACE`。在这种情况下，应指定 `extraWorkspace` 和 `extraWorkspaceSizeInBytes` 参数以提供额外工作空间。所需额外工作空间的大小可通过调用 `custatevecTestMatrixTypeGetWorkspaceSize()` 获得。如果不需要额外工作空间，可以向 `extraWorkspace` 参数传递空指针。此外，如果设置了设备内存处理器，`extraWorkspace` 可以设置为空，`extraWorkspaceSizeInBytes` 可以设置为 0。

**注意**

在此版本中，`nTargets` 参数必须不大于 15。对于更大的 `nTargets`，此函数返回 `CUSTATEVEC_STATUS_INVALID_VALUE`。

**参数**

    `handle` – **[in]** cuStateVec 库的句柄

    `residualNorm` – **[out]** 主机指针，用于存储与特定矩阵类型的偏差

    `matrixType` – **[in]** 矩阵类型

    `matrix` – **[in]** 指向矩阵的主机或设备指针

    `matrixDataType` – **[in]** 矩阵的数据类型

    `layout` – **[in]** 指定矩阵内存布局的枚举器

    `nTargets` – **[in]** 目标比特数，最多 15

    `adjoint` – **[in]** 控制是否测试矩阵伴随的标志

    `computeType` – **[in]** 计算类型

    `extraWorkspace` – **[in]** 额外工作空间

    `extraWorkspaceSizeInBytes` – **[in]** 额外工作空间大小

采样 ¶

采样能够通过使用从量子态计算出的概率多次获取测量结果。

使用示例 ¶

// 创建采样器并检查外部工作空间的大小
custatevecSamplerCreate(
    handle, sv, svDataType, nIndexBits, &sampler, nMaxShots,
    &extraWorkspaceSizeInBytes);

// 如有必要，分配外部工作空间
void* extraWorkspace = nullptr;
if (extraWorkspaceSizeInBytes > 0)
    cudaMalloc(&extraWorkspace, extraWorkspaceSizeInBytes);

// 计算累积 abs2sum
custatevecSamplerPreprocess(
    handle, sampler, extraWorkspace, extraWorkspaceSizeInBytes);

// [用户] 生成 randnums，用于采样的随机数数组 [0, 1)
...

// 采样比特串
custatevecSamplerSample(
    handle, sampler, bitStrings, bitOrdering, bitStringLen, randnums, nShots,
    output);

// 释放采样器
custatevecSamplerDestroy(sampler);

对于多 GPU 计算，cuStateVec 提供了 custatevecSamplerGetSquaredNorm() 和 custatevecSamplerApplySubSVOffset()。用户需要通过 custatevecSamplerGetSquaredNorm() 计算每个子状态向量平方范数的累积 abs2sum 数组，并通过 custatevecSamplerApplySubSVOffset() 将其值提供给采样器描述符。

// 状态向量被划分为 nSubSvs 个子状态向量。
// 每个状态向量有自己的序号和 nLocalBits 个索引比特。
// 子状态向量的序号对应于扩展的索引比特。

// 创建采样器并检查外部工作空间的大小
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]);
    custatevecSamplerCreate(
        handle[iSv], d_sv[iSv], CUDA_C_64F, nLocalBits, &sampler[iSv], nMaxShots,
        &extraWorkspaceSizeInBytes[iSv]);
}

// 如有必要，分配外部工作空间
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    if (extraWorkspaceSizeInBytes[iSv] > 0) {
        cudaSetDevice(devices[iSv]);
        cudaMalloc(&extraWorkspace[iSv], extraWorkspaceSizeInBytes[iSv]);
    }
}

// 采样预处理
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]);
    custatevecSamplerPreprocess(
        handle[iSv], sampler[iSv], extraWorkspace[iSv],
        extraWorkspaceSizeInBytes[iSv]);
}

// 获取子状态向量的范数
double subNorms[nSubSvs];
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]);
    custatevecSamplerGetSquaredNorm(
        handle[iSv], sampler[iSv], &subNorms[iSv]);
}

for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]);
    cudaDeviceSynchronize();
}

// 获取累积数组
double cumulativeArray[nSubSvs + 1];
cumulativeArray[0] = 0.0;
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cumulativeArray[iSv + 1] = cumulativeArray[iSv] + subNorms[iSv];
}
double norm = cumulativeArray[nSubSvs];

// 应用偏移和范数
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]);
    custatevecSamplerApplySubSVOffset(
        handle[iSv], sampler[iSv], iSv, nSubSvs, cumulativeArray[iSv], norm);
}

// 划分 randnum 数组。randnums 必须按升序排序。
int shotOffsets[nSubSvs + 1];
shotOffsets[0] = 0;
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    double* pos = std::lower_bound(randnums, randnums + nShots,
                                    cumulativeArray[iSv + 1] / norm);
    if (iSv == nSubSvs - 1) {
        pos = randnums + nShots;
    }
    shotOffsets[iSv + 1] = pos - randnums;
}

// 采样比特串
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    int shotOffset = shotOffsets[iSv];
    int nSubShots = shotOffsets[iSv + 1] - shotOffsets[iSv];
    if (nSubShots > 0) {
        cudaSetDevice(devices[iSv]);
        custatevecSamplerSample(
            handle[iSv], sampler[iSv], &bitStrings[shotOffset], bitOrdering,
            bitStringLen, &randnums[shotOffset], nSubShots,
            CUSTATEVEC_SAMPLER_OUTPUT_RANDNUM_ORDER);
    }
}

for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]);
    custatevecSamplerDestroy(sampler[iSv]);
}

有关更多详细信息，请参阅 NVIDIA/cuQuantum 存储库。

API 参考 ¶

custatevecSamplerCreate ¶

custatevecStatus_t custatevecSamplerCreate(custatevecHandle_t handle, const void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, custatevecSamplerDescriptor_t *sampler, uint32_t nMaxShots, size_t *extraWorkspaceSizeInBytes) ¶

创建采样器描述符。

此函数创建一个采样器描述符。如果需要额外工作空间，其大小将设置为 `extraWorkspaceSizeInBytes`。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sv` – **[in]** 指向状态向量的指针

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 状态向量的索引比特数

        `sampler` – **[out]** 指向新采样器描述符的指针

        `nMaxShots` – **[in]** 此采样器上下文使用的最大采样次数

        `extraWorkspaceSizeInBytes` – **[out]** 工作空间大小

注意

nMaxShots 的最大值为 224224。如果值超过此限制，custatevecSamplerCreate() 返回 CUSTATEVEC_STATUS_INVALID_VALUE。

custatevecSamplerPreprocess ¶

custatevecStatus_t custatevecSamplerPreprocess(custatevecHandle_t handle, custatevecSamplerDescriptor_t sampler, void *extraWorkspace, const size_t extraWorkspaceSizeInBytes) ¶

预处理状态向量以准备采样。

此函数准备采样器描述符的内部状态。如果设置了设备内存处理器，`extraWorkspace` 可以设置为空，`extraWorkspaceSizeInBytes` 可以设置为 0。否则，传递给 `extraWorkspace` 参数的指针将与采样器句柄关联，并在其生命周期内保持不变。额外工作空间的大小在调用 `custatevecSamplerCreate()` 时获得。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sampler` – **[inout]** 采样器描述符

        `extraWorkspace` – **[in]** 额外工作空间

        `extraWorkspaceSizeInBytes` – **[in]** 额外工作空间的大小

custatevecSamplerGetSquaredNorm ¶

custatevecStatus_t custatevecSamplerGetSquaredNorm(custatevecHandle_t handle, custatevecSamplerDescriptor_t sampler, double *norm) ¶

获取状态向量的平方范数。

此函数返回状态向量的平方范数。一个预期的用例是使用多设备进行采样。此 API 应在 `custatevecSamplerPreprocess()` 之后调用。否则，此函数的行为是未定义的。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sampler` – **[in]** 采样器描述符

        `norm` – **[out]** 状态向量的范数

custatevecSamplerApplySubSVOffset ¶

custatevecStatus_t custatevecSamplerApplySubSVOffset(custatevecHandle_t handle, custatevecSamplerDescriptor_t sampler, int32_t subSVOrd, uint32_t nSubSVs, double offset, double norm) ¶

将部分范数和范数应用于状态向量到采样描述符。

此函数应用偏移量，假设给定的状态向量是一个子状态向量。一个预期的用例是使用分布式状态向量进行采样。`nSubSVs` 参数应该是 2 的幂，且 `subSVOrd` 应小于 `nSubSVs`。否则，此函数返回 `CUSTATEVEC_STATUS_INVALID_VALUE`。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sampler` – **[in]** 采样器描述符

        `subSVOrd` – **[in]** 子状态向量序号

        `nSubSVs` – **[in]** 子状态向量的数量

        `offset` – **[in]** 子状态向量的累积和偏移量

        `norm` – **[in]** 所有子向量的范数

custatevecSamplerSample ¶

custatevecStatus_t custatevecSamplerSample(custatevecHandle_t handle, custatevecSamplerDescriptor_t sampler, custatevecIndex_t *bitStrings, const int32_t *bitOrdering, const uint32_t bitStringLen, const double *randnums, const uint32_t nShots, enum custatevecSamplerOutput_t output) ¶

从状态向量中采样比特串。

此函数执行采样。`bitOrdering` 和 `bitStringLen` 参数指定要采样的比特。采样的比特串表示为 `custatevecIndex_t` 数组，并存储到 `bitStrings` 参数指向的主机内存缓冲区中。

`randnums` 参数是用户生成的随机数数组，其长度为 `nShots`。随机数的范围应在 [0, 1) 内。如果 `randnums` 参数给出的随机数的范围不在 [0, 1) 内，则将其裁剪到 [0, 1)。

`output` 参数指定采样比特串的顺序：

    * 如果指定 `CUSTATEVEC_SAMPLER_OUTPUT_RANDNUM_ORDER`，则采样比特串的顺序与 `randnums` 参数中的顺序相同。
    * 如果指定 `CUSTATEVEC_SAMPLER_OUTPUT_ASCENDING_ORDER`，则比特串按升序返回。

如果不需要特定的顺序，默认情况下选择 `CUSTATEVEC_SAMPLER_OUTPUT_RANDNUM_ORDER`。（它可能会提供稍好的性能。）

此 API 应在 `custatevecSamplerPreprocess()` 之后调用。否则，此函数的行为是未定义的。通过在此函数之前调用 `custatevecSamplerApplySubSVOffset()`，可以采样对应于子状态向量序号的比特。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sampler` – **[in]** 采样器描述符

        `bitStrings` – **[out]** 指向存储采样比特串的主机数组的指针

        `bitOrdering` – **[in]** 指向用于采样的比特顺序主机数组的指针

        `bitStringLen` – **[in]** `bitOrdering` 中的比特数

        `randnums` – **[in]** 指向随机数数组的指针

        `nShots` – **[in]** 采样次数

        `output` – **[in]** 采样比特串的顺序

custatevecSamplerDestroy ¶

custatevecStatus_t custatevecSamplerDestroy(custatevecSamplerDescriptor_t sampler) ¶

此函数释放采样器使用的资源。

**参数**

    `sampler` – **[in]** 采样器描述符

访问器 ¶

访问器用于提取或更新状态向量片段。

API custatevecAccessorCreate() 和 custatevecAccessorCreateView() 初始化一个访问器，并同时返回额外工作空间的大小（如果 API custatevecAccessorGet() 和 custatevecAccessorSet() 需要执行复制操作）。必须通过 custatevecAccessorSetExtraWorkspace() 将工作空间绑定到访问器，并且工作空间的生存期必须与访问器一样长，以覆盖整个复制操作的持续时间。如果设置了设备内存处理器，用户无需提供显式的工作空间。

Get/Set API 中的 begin 和 end 参数对应于状态向量元素的索引，使得指定范围内的元素被复制。

使用示例 ¶
提取 ¶

// 创建访问器并检查外部工作空间的大小
custatevecAccessorCreateView(
    handle, d_sv, CUDA_C_64F, nIndexBits, &accessor, bitOrdering, bitOrderingLen,
    maskBitString, maskOrdering, maskLen, &extraWorkspaceSizeInBytes);

// 如有必要，分配外部工作空间
if (extraWorkspaceSizeInBytes > 0)
    cudaMalloc(&extraWorkspace, extraWorkspaceSizeInBytes);

// 设置外部工作空间
custatevecAccessorSetExtraWorkspace(
    handle, &accessor, extraWorkspace, extraWorkspaceSizeInBytes);

// 获取状态向量元素
custatevecAccessorGet(
    handle, &accessor, buffer, accessBegin, accessEnd);

// 释放访问器
custatevecAccessorDestroy(accessor);

更新 ¶

// 创建访问器并检查外部工作空间的大小
custatevecAccessorCreate(
    handle, d_sv, CUDA_C_64F, nIndexBits, &accessor, bitOrdering, bitOrderingLen,
    maskBitString, maskOrdering, maskLen, &extraWorkspaceSizeInBytes);

// 如有必要，分配外部工作空间
if (extraWorkspaceSizeInBytes > 0)
    cudaMalloc(&extraWorkspace, extraWorkspaceSizeInBytes);

// 设置外部工作空间
custatevecAccessorSetExtraWorkspace(
    handle, &accessor, extraWorkspace, extraWorkspaceSizeInBytes);

// 设置状态向量元素
custatevecAccessorSet(
    handle, &accessor, buffer, 0, nSvSize);

// 释放访问器
custatevecAccessorDestroy(accessor);

API 参考 ¶

custatevecAccessorCreate ¶

custatevecStatus_t custatevecAccessorCreate(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, custatevecAccessorDescriptor_t *accessor, const int32_t *bitOrdering, const uint32_t bitOrderingLen, const int32_t *maskBitString, const int32_t *maskOrdering, const uint32_t maskLen, size_t *extraWorkspaceSizeInBytes) ¶

创建访问器以在状态向量和外部缓冲区之间复制元素。

访问器在状态向量和外部缓冲区之间复制状态向量元素。在复制期间，状态向量元素的顺序会根据 `bitOrdering` 参数指定的比特顺序重新排列。

状态向量假定具有默认顺序：对于 N 个索引比特的系统，LSB 是第 0 个索引比特，(N-1) 个索引比特是 MSB。外部缓冲区的比特顺序由 `bitOrdering` 参数指定。当向 `nIndexBits` 参数传递 3 并向 `bitOrdering` 参数传递 [1, 2, 0] 时，状态向量索引比特被置换到指定的比特位置。因此，状态向量索引被重新排列并映射到外部缓冲区索引为 [0, 4, 1, 5, 2, 6, 3, 7]。

`maskBitString`、`maskOrdering` 和 `maskLen` 参数指定被访问状态向量索引的比特掩码。如果 `maskLen` 参数为 0，则 `maskBitString` 和/或 `maskOrdering` 参数可以为空。

所有比特位置 [0, `nIndexBits`) 应恰好出现一次，无论是在 `bitOrdering` 还是在 `maskOrdering` 参数中。如果一个比特位置没有出现在这些参数中，和/或存在比特位置重叠，此函数返回 `CUSTATEVEC_STATUS_INVALID_VALUE`。

如果访问器被多次调用且外部缓冲区位于设备上且较小，额外工作空间可提高性能。如果不需要额外工作空间，可以为 `extraWorkspaceSizeInBytes` 指定空指针。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sv` – **[in]** 状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 状态向量的索引比特数

        `accessor` – **[in]** 指向访问器描述符的指针

        `bitOrdering` – **[in]** 指向指定外部缓冲区基比特的主机数组的指针

        `bitOrderingLen` – **[in]** `bitOrdering` 的长度

        `maskBitString` – **[in]** 指向指定掩码值以限制访问的主机数组的指针

        `maskOrdering` – **[in]** 指向掩码顺序主机数组的指针

        `maskLen` – **[in]** 掩码的长度

        `extraWorkspaceSizeInBytes` – **[out]** 所需额外工作空间的大小

custatevecAccessorCreateView ¶

custatevecStatus_t custatevecAccessorCreateView(custatevecHandle_t handle, const void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, custatevecAccessorDescriptor_t *accessor, const int32_t *bitOrdering, const uint32_t bitOrderingLen, const int32_t *maskBitString, const int32_t *maskOrdering, const uint32_t maskLen, size_t *extraWorkspaceSizeInBytes) ¶

为常量状态向量创建访问器。

此函数与 `custatevecAccessorCreate()` 相同，但只接受常量状态向量。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sv` – **[in]** 状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 状态向量的索引比特数

        `accessor` – **[in]** 指向访问器描述符的指针

        `bitOrdering` – **[in]** 指向指定外部缓冲区基比特的主机数组的指针

        `bitOrderingLen` – **[in]** `bitOrdering` 的长度

        `maskBitString` – **[in]** 指向指定掩码值以限制访问的主机数组的指针

        `maskOrdering` – **[in]** 指向掩码顺序主机数组的指针

        `maskLen` – **[in]** 掩码的长度

        `extraWorkspaceSizeInBytes` – **[out]** 所需额外工作空间的大小

custatevecAccessorDestroy ¶

custatevecStatus_t custatevecAccessorDestroy(custatevecAccessorDescriptor_t accessor) ¶

此函数释放访问器使用的资源。

**参数**

    `accessor` – **[in]** 访问器描述符

custatevecAccessorSetExtraWorkspace ¶

custatevecStatus_t custatevecAccessorSetExtraWorkspace(custatevecHandle_t handle, custatevecAccessorDescriptor_t accessor, void *extraWorkspace, size_t extraWorkspaceSizeInBytes) ¶

设置访问器的外部工作空间。

此函数将额外工作空间设置到访问器。所需额外工作空间的大小可以通过 `custatevecAccessorCreate()` 或 `custatevecAccessorCreateView()` 获得。如果设置了设备内存处理器，`extraWorkspace` 可以设置为空，`extraWorkspaceSizeInBytes` 可以设置为 0。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `accessor` – **[in]** 访问器描述符

        `extraWorkspace` – **[in]** 额外工作空间

        `extraWorkspaceSizeInBytes` – **[in]** 额外工作空间大小

custatevecAccessorGet ¶

custatevecStatus_t custatevecAccessorGet(custatevecHandle_t handle, custatevecAccessorDescriptor_t accessor, void *externalBuffer, const custatevecIndex_t begin, const custatevecIndex_t end) ¶

将状态向量元素复制到外部缓冲区。

此函数将状态向量元素复制到 `externalBuffer` 参数指定的外部缓冲区。在复制期间，索引比特按照 `custatevecAccessorCreate()` 或 `custatevecAccessorCreateView()` 中 `bitOrdering` 参数指定的方式进行置换。

`begin` 和 `end` 参数指定被复制的状态向量元素的范围。两个参数都具有 `bitOrdering` 参数指定的比特顺序。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `accessor` – **[in]** 访问器描述符

        `externalBuffer` – **[out]** 指向接收复制元素的主机或设备缓冲区的指针

        `begin` – **[in]** 被复制到状态向量的第一个元素在置换比特顺序中的索引

        `end` – **[in]** 被复制到状态向量的最后一个元素在置换比特顺序中的索引（不包含）

custatevecAccessorSet ¶

custatevecStatus_t custatevecAccessorSet(custatevecHandle_t handle, custatevecAccessorDescriptor_t accessor, const void *externalBuffer, const custatevecIndex_t begin, const custatevecIndex_t end) ¶

从外部缓冲区设置状态向量元素。

此函数使用 `externalBuffer` 参数指定的外部缓冲区将复数设置到状态向量。在复制期间，索引比特按照 `custatevecAccessorCreate()` 中 `bitOrdering` 参数指定的方式进行置换。

`begin` 和 `end` 参数指定被设置到状态向量的状态向量元素的范围。两个参数都具有 `bitOrdering` 参数指定的比特顺序。

如果提供了通过调用 `custatevecAccessorCreateView()` 创建的只读访问器，此函数返回 `CUSTATEVEC_STATUS_NOT_SUPPORTED`。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `accessor` – **[in]** 访问器描述符

        `externalBuffer` – **[in]** 指向要复制到状态向量的复数值的主机或设备缓冲区的指针

        `begin` – **[in]** 从状态向量复制的第一个元素在置换比特顺序中的索引

        `end` – **[in]** 从状态向量复制的最后一个元素在置换比特顺序中的索引（不包含）

单进程量子比特重排序 ¶

对于单进程计算，cuStateVec 为单个设备提供了 custatevecSwapIndexBits() API，为多个设备提供了 custatevecMultiDeviceSwapIndexBits() 来重新排序状态向量元素。

使用示例 ¶
单设备 ¶

// 此示例使用 3 个量子比特。
const int nIndexBits = 3;

// 交换第 0 个和第 2 个量子比特
const int nBitSwaps  = 1;
const int2 bitSwaps[] = {{0, 2}}; // 指定量子比特对

// 仅当第 1 个量子比特为 1 时交换状态向量元素
const int maskLen = 1;
int maskBitString[] = {1}; // 指定掩码量子比特的值
int maskOrdering[] = {1};  // 指定掩码量子比特

// 交换索引比特对。
// {|000>, |001>, |010>, |011>, |100>, |101>, |110>, |111>} 将被置换为
// {|000>, |001>, |010>, |110>, |100>, |101>, |011>, |111>}。
custatevecSwapIndexBits(handle, sv, svDataType, nIndexBits, bitSwaps, nBitSwaps,
    maskBitString, maskOrdering, maskLen);

多设备 ¶

// 此示例使用 2 个 GPU，每个 GPU 存储 2 量子比特的子状态向量。
const int nGlobalIndexBits = 1;
const int nLocalIndexBits = 2;
const int nHandles = 1 << nGlobalIndexBits;

// 用户需要在调用交换 API 之前在对等设备上启用直接访问。
for (int i0 = 0; i0 < nHandles; i0++) {
  cudaSetDevice(i0);
  for (int i1 = 0; i1 < nHandles; i1++) {
    if (i0 == i1)
      continue;
    cudaDeviceEnablePeerAccess(i1, 0);
  }
}
cudaSetDevice(0);

// 指定设备网络拓扑类型以优化数据传输序列。
// 这里假设设备通过 NVLink 与 NVSwitch 连接，或通过单个 PCIe 交换机的 PCIe 设备网络连接。
const custatevecDeviceNetworkType_t deviceNetworkType = CUSTATEVEC_DEVICE_NETWORK_TYPE_SWITCH;

// 交换第 0 个和第 2 个量子比特
const int nIndexBitSwaps  = 1;
const int2 indexBitSwaps[] = {{0, 2}}; // 指定量子比特对

// 仅当第 1 个量子比特为 1 时交换状态向量元素
const int maskLen = 1;
int maskBitString[] = {1}; // 指定掩码量子比特的值
int maskOrdering[] = {1};  // 指定掩码量子比特

// 交换索引比特对。
// {|000>, |001>, |010>, |011>, |100>, |101>, |110>, |111>} 将被置换为
// {|000>, |001>, |010>, |110>, |100>, |101>, |011>, |111>}。
custatevecMultiDeviceSwapIndexBits(handles, nHandles, subSVs, svDataType,
    nGlobalIndexBits, nLocalIndexBits, indexBitSwaps, nIndexBitSwaps,
    maskBitString, maskOrdering, maskLen, deviceNetworkType);

API 参考 ¶

custatevecSwapIndexBits ¶

custatevecStatus_t custatevecSwapIndexBits(custatevecHandle_t handle, void *sv, cudaDataType_t svDataType, const uint32_t nIndexBits, const int2 *bitSwaps, const uint32_t nBitSwaps, const int32_t *maskBitString, const int32_t *maskOrdering, const uint32_t maskLen) ¶

交换索引比特并在单个设备中重新排序状态向量元素。

此函数通过交换比特位置对来更新状态向量的比特顺序。

状态向量假定具有默认顺序：对于 N 个索引比特的系统，LSB 是第 0 个索引比特，(N-1) 个索引比特是 MSB。`bitSwaps` 参数指定交换的比特索引对，其值必须在 [0, `nIndexBits`) 范围内。

`maskBitString`、`maskOrdering` 和 `maskLen` 参数指定被置换状态向量索引的比特掩码。如果 `maskLen` 参数为 0，则 `maskBitString` 和/或 `maskOrdering` 参数可以为空。

一个比特位置可以同时包含在 `bitSwaps` 和 `maskOrdering` 中。当交换被掩码的比特时，原始索引与掩码比特串匹配的状态向量元素被写入置换后的索引，而其他元素不被复制。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `sv` – **[inout]** 状态向量

        `svDataType` – **[in]** 状态向量的数据类型

        `nIndexBits` – **[in]** 状态向量的索引比特数

        `bitSwaps` – **[in]** 指向交换比特索引对主机数组的指针

        `nBitSwaps` – **[in]** 比特交换次数

        `maskBitString` – **[in]** 指向用于掩码输出的主机数组的指针

        `maskOrdering` – **[in]** 指向指定 `maskBitString` 顺序的主机数组的指针

        `maskLen` – **[in]** 掩码的长度

custatevecMultiDeviceSwapIndexBits ¶

custatevecStatus_t custatevecMultiDeviceSwapIndexBits(custatevecHandle_t *handles, const uint32_t nHandles, void **subSVs, const cudaDataType_t svDataType, const uint32_t nGlobalIndexBits, const uint32_t nLocalIndexBits, const int2 *indexBitSwaps, const uint32_t nIndexBitSwaps, const int32_t *maskBitString, const int32_t *maskOrdering, const uint32_t maskLen, const custatevecDeviceNetworkType_t deviceNetworkType) ¶

交换索引比特并为分布在多个设备中的多个子状态向量重新排序状态向量元素。

此函数通过交换比特位置对来更新分布在多个设备中的状态向量的比特顺序。

此函数假设状态向量被分割成多个子状态向量并分布到多个设备中，以表示一个 (`nGlobalIndexBits` + `nLocalIndexBits`) 量子比特系统。

`handles` 参数应接收为所有分配了子状态向量的设备创建的 cuStateVec 句柄。如果给出了为同一设备创建的两个或更多 cuStateVec 句柄，此函数将返回错误 `CUSTATEVEC_STATUS_INVALID_VALUE`。`handles` 参数应包含在当前设备上创建的句柄，因为此函数中的所有操作将在当前设备句柄的流上排序。否则，此函数返回错误 `CUSTATEVEC_STATUS_INVALID_VALUE`。

子状态向量由 `subSVs` 参数指定为设备指针数组。所有子状态向量都假定持有由 `nLocalIndexBits` 指定的相同索引比特数。因此，每个子状态向量持有 (1 << `nLocalIndexBits`) 个状态向量元素。全局索引比特等同于子状态向量的索引。子状态向量的数量为 (1 << `nGlobalIndexBits`)。`nGlobalIndexBits` 的最大值为 5，对应于 32 个子状态向量。

分布式状态向量的索引比特具有默认顺序：子状态向量的索引比特从第 0 个索引比特映射到第 (`nLocalIndexBits`-1) 个索引比特。全局索引比特从第 (`nLocalIndexBits`) 个比特映射到第 (`nGlobalIndexBits` + `nLocalIndexBits` - 1) 个比特。

`indexBitSwaps` 参数指定被交换的索引比特对。每个索引比特对可以是两个全局索引比特的对，或一个全局索引比特与一个局部索引比特的对。不接受两个局部索引比特的对。请使用 `custatevecSwapIndexBits()` 来交换局部索引比特。

`maskBitString`、`maskOrdering` 和 `maskLen` 参数指定比特串掩码，用于限制在此调用期间交换的状态向量元素。`maskOrdering` 中的比特可以与 `indexBitSwaps` 参数中指定的索引比特重叠。在这种情况下，掩码比特串应用于索引比特交换之前的比特位置。如果 `maskLen` 参数为 0，则 `maskBitString` 和/或 `maskOrdering` 参数可以为空。

`deviceNetworkType` 参数指定设备网络拓扑以优化数据传输序列。假设以下两种网络拓扑：

    * 交换机网络：设备通过 NVLink 与 NVSwitch 连接（例如 DGX A100 和 DGX-2）或通过单个 PCIe 交换机的 PCIe 设备网络
    * 全连接网络：所有设备通过全连接连接（例如 DGX Station V100/A100）

**注意**

**重要通知** 此函数假设双向 GPUDirect P2P 在所有分配了子状态向量的设备之间得到支持并通过 `cudaDeviceEnablePeerAccess()` 启用。如果 GPUDirect P2P 未启用，调用 `custatevecMultiDeviceSwapIndexBits()` 访问其他 GPU 中分配的无法访问的设备内存将导致段错误。

为了获得最佳性能，请使用 (2^n) 个设备并在每个设备中分配一个子状态向量。此函数允许使用非 (2^n) 个设备，在一个设备上分配两个或更多子状态向量，或在单个设备上分配所有子状态向量以适应各种硬件配置。然而，当在每个 (2^n) 个设备上分配单个子状态向量时，性能总是最佳。

每个参与设备上的复制操作通过 `custatevecSetStream()` 绑定到相应句柄的 CUDA 流中排队。如果在此函数调用之前发出的所有 CUDA 调用都在设置为句柄的流上执行，则这些调用将被正确排序。此函数是异步执行的。请将流设置为当前设备的句柄，使用 `cudaStreamSynchronize()`（用于同步）或 `cudaStreamWaitEvent()`（用于建立流顺序）。

**参数**

    `handles` – **[in]** 指向 `custatevecHandle_t` 主机数组的指针

    `nHandles` – **[in]** `handles` 参数中指定的句柄数量

    `subSVs` – **[inout]** 指向子状态向量数组的指针

    `svDataType` – **[in]** `subSVs` 参数指定的状态向量的数据类型

    `nGlobalIndexBits` – **[in]** 分布式状态向量的全局索引比特数

    `nLocalIndexBits` – **[in]** 子状态向量中的局部索引比特数

    `indexBitSwaps` – **[in]** 指向被交换的索引比特对主机数组的指针

    `nIndexBitSwaps` – **[in]** 索引比特交换次数

    `maskBitString` – **[in]** 指向用于掩码输出的主机数组的指针

    `maskOrdering` – **[in]** 指向指定 `maskBitString` 顺序的主机数组的指针

    `maskLen` – **[in]** 掩码的长度

    `deviceNetworkType` – **[in]** 设备网络拓扑

多进程量子比特重排序 ¶

对于多进程计算，cuStateVec 提供了 API 来调度/重新排序分布式状态向量元素。此外，cuStateVec 拥有 custatevecCommunicator_t，它封装了 MPI 库用于进程间通信。有关概述和详细用法，请参阅分布式索引比特交换 API。

API 参考 ¶

custatevecCommunicatorCreate ¶

custatevecStatus_t custatevecCommunicatorCreate(custatevecHandle_t handle, custatevecCommunicatorDescriptor_t *communicator, custatevecCommunicatorType_t communicatorType, const char *soname) ¶

创建通信器。

此函数创建一个通信器实例。

通信器的类型由 `communicatorType` 参数指定。通过指定 `CUSTATEVEC_COMMUNICATOR_TYPE_OPENMPI` 或 `CUSTATEVEC_COMMUNICATOR_TYPE_MPICH`，此函数分别创建一个内部使用 Open MPI 或 MPICH 的通信器实例。通过指定 `CUSTATEVEC_COMMUNICATOR_TYPE_EXTERNAL`，此函数加载一个封装 MPI 库的自定义插件。自定义插件的源代码可从 NVIDIA/cuQuantum 下载。

`soname` 参数指定通信器实例将使用的共享库的名称。

此函数使用 `dlopen()` 加载指定的共享库。如果 Open MPI 或 MPICH 库直接链接到应用程序，并且为 `communicatorType` 参数指定了 `CUSTATEVEC_COMMUNICATOR_TYPE_OPENMPI` 或 `CUSTATEVEC_COMMUNICATOR_TYPE_MPICH`，则 `soname` 参数应设置为 `NULL`。因此，函数符号通过在启动时加载到应用程序的函数中搜索来解析。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `communicator` – **[out]** 指向通信器的指针

        `communicatorType` – **[in]** 通信器类型

        `soname` – **[in]** 共享对象名称

custatevecCommunicatorDestroy ¶

custatevecStatus_t custatevecCommunicatorDestroy(custatevecHandle_t handle, custatevecCommunicatorDescriptor_t communicator) ¶

此函数释放通信器。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `communicator` – **[in]** 通信器描述符

custatevecDistIndexBitSwapSchedulerCreate ¶

custatevecStatus_t custatevecDistIndexBitSwapSchedulerCreate(custatevecHandle_t handle, custatevecDistIndexBitSwapSchedulerDescriptor_t *scheduler, const uint32_t nGlobalIndexBits, const uint32_t nLocalIndexBits) ¶

创建分布式索引比特交换调度器。

此函数创建一个分布式索引比特交换调度器描述符。

局部索引比特从第 0 个索引比特到第 (`nLocalIndexBits`-1) 个索引比特。全局索引比特从第 (`nLocalIndexBits`) 个比特映射到第 (`nGlobalIndexBits` + `nLocalIndexBits` - 1) 个比特。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `scheduler` – **[out]** 指向批交换调度器的指针

        `nGlobalIndexBits` – **[in]** 全局索引比特数

        `nLocalIndexBits` – **[in]** 局部索引比特数

custatevecDistIndexBitSwapSchedulerDestroy ¶

custatevecStatus_t custatevecDistIndexBitSwapSchedulerDestroy(custatevecHandle_t handle, custatevecDistIndexBitSwapSchedulerDescriptor_t scheduler) ¶

此函数释放分布式索引比特交换调度器。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `scheduler` – **[in]** 指向要销毁的批交换调度器的指针

custatevecDistIndexBitSwapSchedulerSetIndexBitSwaps ¶

custatevecStatus_t custatevecDistIndexBitSwapSchedulerSetIndexBitSwaps(custatevecHandle_t handle, custatevecDistIndexBitSwapSchedulerDescriptor_t scheduler, const int2 *indexBitSwaps, const uint32_t nIndexBitSwaps, const int32_t *maskBitString, const int32_t *maskOrdering, const uint32_t maskLen, uint32_t *nSwapBatches) ¶

设置分布式索引比特交换调度器的索引比特交换。

此函数将索引比特交换设置到分布式索引比特交换调度器，并计算给定索引比特交换所需的批处理数据传输次数。

分布式状态向量的索引比特具有默认顺序：子状态向量的索引比特从第 0 个索引比特映射到第 (`nLocalIndexBits`-1) 个索引比特。全局索引比特从第 (`nLocalIndexBits`) 个比特映射到第 (`nGlobalIndexBits` + `nLocalIndexBits` - 1) 个比特。

`indexBitSwaps` 参数指定被交换的索引比特对。每个索引比特对可以是两个全局索引比特的对，或一个全局索引比特与一个局部索引比特的对。不接受两个局部索引比特的对。请使用 `custatevecSwapIndexBits()` 来交换局部索引比特。

`maskBitString`、`maskOrdering` 和 `maskLen` 参数指定比特串掩码，用于限制在此调用期间交换的状态向量元素。`maskOrdering` 中的比特可以与 `indexBitSwaps` 参数中指定的索引比特重叠。在这种情况下，掩码比特串应用于索引比特交换之前的比特位置。如果 `maskLen` 参数为 0，则 `maskBitString` 和/或 `maskOrdering` 参数可以为空。

由 `nSwapBatches` 参数返回的值表示完成索引比特交换所需的循环次数，并在后续阶段中使用。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `scheduler` – **[in]** 指向批交换调度器描述符的指针

        `indexBitSwaps` – **[in]** 指向被交换的索引比特对主机数组的指针

        `nIndexBitSwaps` – **[in]** 索引比特交换次数

        `maskBitString` – **[in]** 指向用于掩码输出的主机数组的指针

        `maskOrdering` – **[in]** 指向指定 `maskBitString` 顺序的主机数组的指针

        `maskLen` – **[in]** 掩码的长度

        `nSwapBatches` – **[out]** 批处理数据传输次数

custatevecDistIndexBitSwapSchedulerGetParameters ¶

custatevecStatus_t custatevecDistIndexBitSwapSchedulerGetParameters(custatevecHandle_t handle, custatevecDistIndexBitSwapSchedulerDescriptor_t scheduler, const int32_t swapBatchIndex, const int32_t orgSubSVIndex, custatevecSVSwapParameters_t *parameters) ¶

获取要设置到状态向量交换工作器的参数。

此函数计算用于子状态向量之间数据传输的参数。`swapBatchIndex` 参数的值应在 [0, `nSwapBatches`) 范围内，其中 `nSwapBatches` 是通过调用 `custatevecDistIndexBitSwapSchedulerSetIndexBitSwaps()` 获得的循环次数。

`parameters` 参数返回计算出的数据传输参数，这些参数通过调用 `custatevecSVSwapWorkerSetParameters()` 设置到 `custatevecSVSwapWorker`。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `scheduler` – **[in]** 指向批交换调度器描述符的指针

        `swapBatchIndex` – **[in]** 用于状态向量交换参数的交换批索引

        `orgSubSVIndex` – **[in]** 要交换状态向量段的源子状态向量的索引

        `parameters` – **[out]** 指向数据传输参数的指针

custatevecSVSwapWorkerCreate ¶

custatevecStatus_t custatevecSVSwapWorkerCreate(custatevecHandle_t handle, custatevecSVSwapWorkerDescriptor_t *svSwapWorker, custatevecCommunicatorDescriptor_t communicator, void *orgSubSV, int32_t orgSubSVIndex, cudaEvent_t orgEvent, cudaDataType_t svDataType, cudaStream_t stream, size_t *extraWorkspaceSizeInBytes, size_t *minTransferWorkspaceSizeInBytes) ¶

创建状态向量交换工作器。

此函数创建一个 `custatevecSVSwapWorkerDescriptor_t`，用于在多个子状态向量之间交换/发送/接收状态向量元素。作为 `communicator` 参数指定的通信器用于进程间通信，因此状态向量元素在分布到多个进程和节点的子状态向量之间传输。

创建的描述符在创建句柄的设备上工作。由 `orgSubSV` 参数指定的源子状态向量应分配在同一设备上。同样适用于分别由 `orgEvent` 和 `stream` 参数指定的事件和流。

有两种工作空间：额外工作空间和数据传输工作空间。额外工作空间具有固定大小，用于保持描述符的内部状态。数据传输工作空间用于暂存正在传输的状态向量元素。其最小大小由 `minTransferWorkspaceSizeInBytes` 参数给出。根据系统情况，增加数据传输工作空间的大小可以提高性能。

如果所有目标子状态向量都通过使用 `custatevecSVSwapWorkerSetSubSVsP2P()` 指定，则 `communicator` 参数可以为空。在这种情况下，内部 CUDA 调用不会在 `stream` 参数指定的流上序列化。用户有责任按此顺序调用 `cudaStreamSynchronize()` 和全局屏障（如 `MPI_Barrier()`）以完成所有内部 CUDA 调用。此限制将在未来版本中修复。

如果子状态向量分布到多个进程中，事件应使用 `cudaEventInterprocess` 标志创建。有关详细信息，请参阅 CUDA 工具包文档。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `svSwapWorker` – **[out]** 状态向量交换工作器

        `communicator` – **[in]** 指向 MPI 通信器的指针

        `orgSubSV` – **[in]** 指向子状态向量的指针

        `orgSubSVIndex` – **[in]** 由 `orgSubSV` 参数指定的子状态向量的索引

        `orgEvent` – **[in]** 用于与对等工作器同步的事件

        `svDataType` – **[in]** 用于状态向量表示的数据类型

        `stream` – **[in]** 用于在数据传输期间本地执行内核的流

        `extraWorkspaceSizeInBytes` – **[out]** 所需的额外工作空间大小

        `minTransferWorkspaceSizeInBytes` – **[out]** 传输工作空间的最小所需大小

custatevecSVSwapWorkerDestroy ¶

custatevecStatus_t custatevecSVSwapWorkerDestroy(custatevecHandle_t handle, custatevecSVSwapWorkerDescriptor_t svSwapWorker) ¶

此函数释放状态向量交换工作器。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `svSwapWorker` – **[in]** 状态向量交换工作器

custatevecSVSwapWorkerSetExtraWorkspace ¶

custatevecStatus_t custatevecSVSwapWorkerSetExtraWorkspace(custatevecHandle_t handle, custatevecSVSwapWorkerDescriptor_t svSwapWorker, void *extraWorkspace, size_t extraWorkspaceSizeInBytes) ¶

设置额外工作空间。

此函数将额外工作空间设置到状态向量交换工作器。所需额外工作空间的大小可通过 `custatevecSVSwapWorkerCreate()` 获得。

应在调用 `custatevecSVSwapWorkerSetParameters()` 之前设置额外工作空间。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `svSwapWorker` – **[in]** 状态向量交换工作器

        `extraWorkspace` – **[in]** 指向用户拥有的工作空间的指针

        `extraWorkspaceSizeInBytes` – **[in]** 用户提供的工作空间的大小

custatevecSVSwapWorkerSetTransferWorkspace ¶

custatevecStatus_t custatevecSVSwapWorkerSetTransferWorkspace(custatevecHandle_t handle, custatevecSVSwapWorkerDescriptor_t svSwapWorker, void *transferWorkspace, size_t transferWorkspaceSizeInBytes) ¶

设置传输工作空间。

此函数将传输工作空间设置到状态向量交换工作器实例。传输工作空间的最小大小可通过 `custatevecSVSwapWorkerCreate()` 获得。

根据系统硬件配置，更大的传输工作空间大小可以提高性能。由 `transferWorkspaceSizeInBytes` 指定的大小应为 2 的幂，并且应大于或等于通过调用 `custatevecSVSwapWorkerCreate()` 返回的 `minTransferWorkspaceSizeInBytes` 的值。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `svSwapWorker` – **[in]** 状态向量交换工作器

        `transferWorkspace` – **[in]** 指向用户拥有的工作空间的指针

        `transferWorkspaceSizeInBytes` – **[in]** 用户提供的工作空间的大小

custatevecSVSwapWorkerSetSubSVsP2P ¶

custatevecStatus_t custatevecSVSwapWorkerSetSubSVsP2P(custatevecHandle_t handle, custatevecSVSwapWorkerDescriptor_t svSwapWorker, void **dstSubSVsP2P, const int32_t *dstSubSVIndicesP2P, cudaEvent_t *dstEvents, const uint32_t nDstSubSVsP2P) ¶

设置可通过 GPUDirect P2P 访问的子状态向量指针。

此函数设置子状态向量指针，这些指针可通过 GPUDirect P2P 从状态向量交换工作器工作的设备访问。子状态向量指针应连同子状态向量索引和事件一起指定，这些事件传递给 `custatevecSVSwapWorkerCreate()` 以创建对等 SV 交换工作器实例。

如果子状态向量分配在不同的进程中，应使用 CUDA IPC 检索子状态向量指针和事件。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `svSwapWorker` – **[in]** 状态向量交换工作器

        `dstSubSVsP2P` – **[in]** 指向可通过 GPUDirect P2P 访问的子状态向量的指针数组

        `dstSubSVIndicesP2P` – **[in]** 由 `dstSubSVsP2P` 参数指定的子状态向量指针的子状态向量索引

        `dstEvents` – **[in]** 用于创建对等工作器的事件

        `nDstSubSVsP2P` – **[in]** 由 `dstSubSVsP2P` 参数指定的子状态向量指针的数量

custatevecSVSwapWorkerSetParameters ¶

custatevecStatus_t custatevecSVSwapWorkerSetParameters(custatevecHandle_t handle, custatevecSVSwapWorkerDescriptor_t svSwapWorker, const custatevecSVSwapParameters_t *parameters, int peer) ¶

设置状态向量交换参数。

此函数设置交换状态向量元素的参数。`parameters` 参数的值通过调用 `custatevecDistIndexBitSwapSchedulerGetParameters()` 获取。

`peer` 参数指定持有目标子状态向量的对等进程的秩。目标子状态向量的子状态向量索引从 `custatevecSVSwapParameters_t` 中定义的 `dstSubSVIndex` 成员获取。

如果所有子状态向量都可通过 GPUDirect P2P 访问，并且在调用 `custatevecSVSwapWorkerCreate()` 时向 `communicator` 参数传递了空指针，则忽略 `peer` 参数。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `svSwapWorker` – **[in]** 状态向量交换工作器

        `parameters` – **[in]** 数据传输参数

        `peer` – **[in]** 数据传输的对等进程标识符

custatevecSVSwapWorkerExecute ¶

custatevecStatus_t custatevecSVSwapWorkerExecute(custatevecHandle_t handle, custatevecSVSwapWorkerDescriptor_t svSwapWorker, custatevecIndex_t begin, custatevecIndex_t end) ¶

执行数据传输。

此函数执行状态向量元素的传输。要传输的元素数量从 `custatevecSVSwapParameters_t` 中的 `transferSize` 成员获取。`begin` 和 `end` 参数指定要传输的元素的范围 [begin, end)。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `svSwapWorker` – **[in]** 状态向量交换工作器

        `begin` – **[in]** 开始传输的索引

        `end` – **[in]** 结束传输的索引

子状态向量迁移 ¶

对于主机/设备内存上的分布式状态向量模拟，cuStateVec 提供了 API 来迁移分布式状态向量元素。有关概述和详细用法，请参阅子状态向量迁移 API。

API 参考 ¶

custatevecSubSVMigratorCreate ¶

custatevecStatus_t custatevecSubSVMigratorCreate(custatevecHandle_t handle, custatevecSubSVMigratorDescriptor_t *migrator, void *deviceSlots, cudaDataType_t svDataType, int nDeviceSlots, int nLocalIndexBits) ¶

创建子状态向量迁移器描述符。

此函数创建一个子状态向量迁移器描述符。由 `deviceSlots` 参数指定的子状态向量分配在一个连续的内存数组中，其大小应至少为 (nDeviceSlots 	imes (1 << nLocalIndexBits))。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `migrator` – **[out]** 指向新迁移器描述符的指针

        `deviceSlots` – **[in]** 指向设备上的子状态向量的指针

        `svDataType` – **[in]** 状态向量的数据类型

        `nDeviceSlots` – **[in]** `deviceSlots` 中子状态向量的数量

        `nLocalIndexBits` – **[in]** 子状态向量的索引比特数

custatevecSubSVMigratorDestroy ¶

custatevecStatus_t custatevecSubSVMigratorDestroy(custatevecHandle_t handle, custatevecSubSVMigratorDescriptor_t migrator) ¶

销毁子状态向量迁移器描述符。

此函数释放一个子状态向量迁移器描述符。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `migrator` – **[inout]** 迁移器描述符

custatevecSubSVMigratorMigrate ¶

custatevecStatus_t custatevecSubSVMigratorMigrate(custatevecHandle_t handle, custatevecSubSVMigratorDescriptor_t migrator, int deviceSlotIndex, const void *srcSubSV, void *dstSubSV, custatevecIndex_t begin, custatevecIndex_t end) ¶

子状态向量迁移。

此函数执行子状态向量迁移。`deviceSlotIndex` 参数指定要传输的子状态向量的索引，`srcSubSV` 和 `dstSubSV` 参数指定要从设备上的子状态向量传输到/从设备上的子状态向量传输的子状态向量。在当前版本中，`srcSubSV` 和 `dstSubSV` 必须是分配在主机内存中且可从设备访问的数组。如果 `srcSubSV` 或 `dstSubSV` 为空指针，则跳过相应的数据传输。`begin` 和 `end` 参数指定要传输的元素的范围 [begin, end)。

**参数**

        `handle` – **[in]** cuStateVec 库的句柄

        `migrator` – **[in]** 迁移器描述符

        `deviceSlotIndex` – **[in]** 指定要迁移的子状态向量的索引

        `srcSubSV` – **[in]** 指向要迁移到 `deviceSlots` 的子状态向量的指针

        `dstSubSV` – **[out]** 指向要从 `deviceSlots` 迁移出的子状态向量的指针

        `begin` – **[in]** 开始迁移的索引

        `end` – **[in]** 结束迁移的索引