cuStateVec 函数¶

库管理¶

句柄管理 API¶

`custatevecCreate`¶

custatevecStatus_t custatevecCreate(custatevecHandle_t *handle)¶

此函数初始化 cuStateVec 库并在 cuStateVec 上下文中创建一个句柄。它必须在任何其他 cuStateVec API 函数之前调用。如果设备具有不受支持的计算能力，此函数可能会返回 CUSTATEVEC_STATUS_ARCH_MISMATCH。

参数: 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() 获得。

通过设置更大的工作区，用户可以执行函数而无需在某些函数中分配额外的工作区。

如果设置了设备内存处理程序，则可以将 workspace 设置为空，并且工作区将使用用户定义的内存池进行分配。

参数

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 追踪 - 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¶

流序内存分配器（或简称 mempool）以异步方式从/向 mempool 分配/释放内存，采用流序方式，这意味着在流上排队的内存操作和计算具有明确定义的流间和流内依赖性。有几个完善的流序 mempool 可用，例如 CUDA 11.2 及更高版本 CUDA 驱动程序级别内置的 cudaMemPool_t （以便同一进程中的所有 CUDA 应用程序可以轻松共享同一池，请参阅此处）和 RAPIDS 内存管理器 (RMM)。有关详细介绍，请参阅 NVIDIA 开发者博客。

新的设备内存处理程序 API 允许用户将流序 mempool 绑定到库句柄，以便 cuStateVec 可以处理用户的大部分内存管理。以下是可以执行的操作的说明

MyMemPool pool = MyMemPool();  // kept alive for the entire process in real apps

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);
}

// create a mem handler and fill in the required members for the library to use
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);

// bind the handler to the library handle
custatevecSetDeviceMemHandler(handle, &handler);

/* ... use gate application as usual ... */

// User doesn’t compute the required sizes

// User doesn’t query the workspace size (but one can if desired)

// User doesn’t allocate memory!

// User sets null pointer to indicate the library should draw memory from the user's pool;
void* extraWorkspace = nullptr;
size_t extraWorkspaceInBytes = 0;
custatevecApplyMatrix(
    handle, sv, svDataType, nIndexBits, matrix, matrixDataType, layout,
    adjoint, targets, nTargets, controls, nControls, controlBitValues,
    computeType, extraWorkspace, extraWorkspaceSizeInBytes);

// User doesn’t deallocate memory!

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

在当前版本中，只能绑定设备 mempool。

`custatevecSetDeviceMemHandler`¶

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

设置当前的设备内存处理程序。

设置后，当 cuStateVec 在各种 API 调用中需要设备内存时，它将从用户提供的内存池中分配，并在完成时释放。有关更多详细信息，请参阅 custatevecDeviceMemHandler_t 和需要额外工作区的 API。

内部流顺序是使用用户通过 custatevecSetStream() 设置的流建立的。

如果 handler 参数设置为 nullptr，则库句柄将分离其现有的内存处理程序。

警告

在以下情况下，行为是未定义的

库句柄绑定到一个内存处理程序，然后又绑定到另一个处理程序
库句柄的生命周期超过了附加的内存池
内存池不是流序的

参数

handle – [in] 持有 cuStateVec 库上下文的不透明句柄。
handler – [in] 封装用户 mempool 的设备内存处理程序。结构内容在内部复制。

`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 获取详细信息。

用例¶

// initialize state vector
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() 可以将矩阵应用于批量状态向量。请参考批量状态向量以获得批量状态向量模拟的概述。

用例¶

// check the size of external workspace
custatevecApplyMatrixGetWorkspaceSize(
    handle, svDataType, nIndexBits, matrix, matrixDataType, layout, adjoint, nTargets,
    nControls, computeType, &extraWorkspaceSizeInBytes);

// allocate external workspace if necessary
void* extraWorkspace = nullptr;
if (extraWorkspaceSizeInBytes > 0)
    cudaMalloc(&extraWorkspace, extraWorkspaceSizeInBytes);

// apply gate
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] 矩阵乘法的 computeType
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^\text{nIndexBits}\)。

matrix 参数是指向方阵的二维数组的主机或设备指针。矩阵的大小为 (\(2^\text{nTargets} \times 2^\text{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] 矩阵乘法的 computeType
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] 矩阵乘法的 computeType
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^\text{nIndexBits}\)，状态向量的数量由 nSVs 参数指定。

mapType 参数指定将矩阵分配给状态向量的方式，matrixIndices 参数指定状态向量的矩阵索引。当 mapType 为 CUSTATEVEC_MATRIX_MAP_TYPE_MATRIX_INDEXED 时，第 \(\text{matrixIndices[}i\text{]}\) 个矩阵将分配给第 \(i\) 个状态向量。当 mapType 为 CUSTATEVEC_MATRIX_MAP_TYPE_MATRIX_INDEXED 时，matrixIndices 应包含 nSVs 个整数；当 mapType 为 CUSTATEVEC_MATRIX_MAP_TYPE_BROADCAST 时，它可以为空指针。

matrices 参数是方阵的二维数组的主机或设备指针。矩阵的大小为 (\(\text{nMatrices} \times 2^\text{nTargets} \times 2^\text{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] 矩阵乘法的 computeType
extraWorkspace – [in] 额外的工作区
extraWorkspaceSizeInBytes – [in] 额外的工作区大小

泡利矩阵¶

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

\[e^{i \theta \left( P_{target[0]} \otimes P_{target[1]} \otimes \cdots \otimes P_{target[nTargets-1]} \right)}.\]

矩阵 \(P_{target[i]}\) 可以是泡利矩阵 \(I\)、\(X\)、\(Y\) 和 \(Z\) 中的任何一个，它们分别对应于 custatevecPauli_t 枚举 CUSTATEVEC_PAULI_I、CUSTATEVEC_PAULI_X、CUSTATEVEC_PAULI_Y 和 CUSTATEVEC_PAULI_Z。另请参阅 custatevecPauli_t 以了解详细信息。

用例¶

// apply exponential
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)¶

应用多量子位泡利算子的指数。

应用由基指定的泡利基张量积的指数，\( e^{i \theta P} \)，其中 \(P\) 是泡利基的乘积。 paulis、targets 和 nTargets 参数指定泡利基及其在状态向量索引中的位位置。

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

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

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

参数

handle – [in] cuStateVec 库的句柄
sv – [inout] 状态向量
svDataType – [in] 状态向量的数据类型
nIndexBits – [in] 状态向量索引中的位数
theta – [in] theta
paulis – [in] 指向 custatevecPauli_t 数组的主机指针
targets – [in] 指向目标位的主机数组的指针
nTargets – [in] 目标位的数量
controls – [in] 指向控制位的主机数组的指针
controlBitValues – [in] 指向控制位值的主机数组的指针
nControls – [in] 控制位的数量

广义置换矩阵¶

广义置换矩阵可以表示为置换矩阵 \(P\) 和对角矩阵 \(D\) 的乘积。例如，我们可以将 4 \(\times\) 4 广义置换矩阵 \(A\) 分解如下

\[\begin{split}A = \left[ \begin{array}{cccc} 0 & 0 & a_0 & 0 \\ a_1 & 0 & 0 & 0 \\ 0 & 0 & 0 & a_2 \\ 0 & a_3 & 0 & 0 \end{array}\right] = DP\end{split}\]

，其中

\[\begin{split}D = \left[ \begin{array}{cccc} a_0 & 0 & 0 & 0 \\ 0 & a_1 & 0 & 0 \\ 0 & 0 & a_2 & 0 \\ 0 & 0 & 0 & a_3 \end{array}\right], P = \left[ \begin{array}{cccc} 0 & 0 & 1 & 0 \\ 1 & 0 & 0 & 0 \\ 0 & 0 & 0 & 1 \\ 0 & 1 & 0 & 0 \end{array}\right].\end{split}\]

当 \(P\) 为对角矩阵时，广义置换矩阵也是对角矩阵。类似地，当 \(D\) 为单位矩阵时，广义置换矩阵变为置换矩阵。

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

用例¶

// check the size of external workspace
custatevecApplyGeneralizedPermutationMatrixGetWorkspaceSize(
    handle, CUDA_C_64F, nIndexBits, permutation, diagonals, CUDA_C_64F, targets,
    nTargets, nControls, &extraWorkspaceSizeInBytes);

// allocate external workspace if necessary
void* extraWorkspace = nullptr;
if (extraWorkspaceSizeInBytes > 0)
    cudaMalloc(&extraWorkspace, extraWorkspaceSizeInBytes);

// apply a generalized permutation matrix
custatevecApplyGeneralizedPermutationMatrix(
    handle, d_sv, CUDA_C_64F, nIndexBits, permutation, diagonals, CUDA_C_64F,
    adjoint, targets, nTargets, controls, controlBitValues, nControls,
    extraWorkspace, extraWorkspaceSizeInBytes);

该操作等效于以下操作

// sv, sv_temp: the state vector and temporary buffer.

int64_t sv_size = int64_t{1} << nIndexBits;
for (int64_t sv_idx = 0; sv_idx < sv_size; sv_idx++) {
    // The basis of sv_idx is converted to permutation basis to obtain perm_idx
    auto perm_idx = convertToPermutationBasis(sv_idx);
    // apply generalized permutation matrix
    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)¶

应用广义置换矩阵。

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

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

置换矩阵 \(P\) 被指定为置换表，该表是 custatevecIndex_t 的数组，并传递给 permutation 参数。

对角矩阵 \(D\) 被指定为对角元素数组。两个数组的长度均为 \( 2^{{\text 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\) 被视为单位矩阵，因此，仅应用对角矩阵 \(D\)。同样地，如果将空指针传递给 diagonals 参数，\(D\) 被视为单位矩阵，并且仅应用置换矩阵 \(P\)。

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

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

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

如果不需要额外的 workspace，则可以将空指针传递给 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 基测量¶

让我们考虑对 \(nIndexBits\) 量子比特态向量 \(sv\) 在 \(nBasisBits\) 位 Z 乘积基 \(basisBits\) 上进行测量。

Z 乘积基上态向量元素的平方绝对值之和，\(abs2sum0\) 和 \(abs2sum1\)，可以通过以下方式获得

\[\begin{split}abs2sum0 &= \Bra{sv} \left\{ \dfrac{1}{2} \left( 1 + Z_{basisBits[0]} \otimes Z_{basisBits[1]} \otimes \cdots \otimes Z_{basisBits[nBasisBits-1]} \right) \right\} \Ket{sv}, \\ abs2sum1 &= \Bra{sv} \left\{ \dfrac{1}{2} \left( 1 - Z_{basisBits[0]} \otimes Z_{basisBits[1]} \otimes \cdots \otimes Z_{basisBits[nBasisBits-1]} \right) \right\} \Ket{sv}.\end{split}\]

因此，获得奇偶校验 0 和 1 的概率可以用以下表达式表示

\[\begin{split}Pr(parity = 0) &= \dfrac{abs2sum0}{abs2sum0 + abs2sum1}, \\ Pr(parity = 1) &= \dfrac{abs2sum1}{abs2sum0 + abs2sum1}.\end{split}\]

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

\[\ket{sv} = \dfrac{1}{\sqrt{norm}} \left\{ \dfrac{1}{2} \left( 1 + Z_{basisBits[0]} \otimes Z_{basisBits[1]} \otimes \cdots \otimes Z_{basisBits[nBasisBits-1]} \right) \right\} \Ket{sv},\]

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

\[\ket{sv} = \dfrac{1}{\sqrt{norm}} \left\{ \dfrac{1}{2} \left( 1 - Z_{basisBits[0]} \otimes Z_{basisBits[1]} \otimes \cdots \otimes Z_{basisBits[nBasisBits-1]} \right) \right\} \Ket{sv},\]

其中 \(norm\) 是归一化因子。

用例¶

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

// measure on a Z basis
custatevecMeasureOnZBasis(
    handle, sv, svDataType, nIndexBits, &parity, basisBits, nBasisBits,
    randnum, collapse);

该操作等效于以下操作

// compute the sums of squared absolute values of state vector elements
// on a Z product basis
double abs2sum0, abs2sum1;
custatevecAbs2SumOnZBasis(
    handle, sv, svDataType, nIndexBits, &abs2sum0, &abs2sum1, basisBits,
    nBasisBits);

// [User] compute parity and norm
double abs2sum = abs2sum0 + abs2sum1;
int parity = (randnum * abs2sum < abs2sum0) ? 0 : 1;
double norm = (parity == 0) ? abs2sum0 : abs2sum1;

// collapse if necessary
switch (collapse) {
case CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO:
    custatevecCollapseOnZBasis(
        handle, sv, svDataType, nIndexBits, parity, basisBits, nBasisBits,
        norm);
    break;  /* collapse */
case CUSTATEVEC_COLLAPSE_NONE:
    break;  /* Do nothing */

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) 的总和与态向量的范数相同，因此可以将奇偶校验 == 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] 坍缩操作

量子比特测量¶

假设我们使用 \(bitOrderingLen\) 位比特串 \(bitOrdering\) 测量 \(nIndexBits\) 量子比特态向量 \(sv\)。

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

\[abs2sum[idx] = \braket{sv|i}\braket{i|sv},\]

其中 \(idx = b_{BitOrderingLen-1}\cdots b_1 b_0\)， \(i = b_{bitOrdering[BitOrderingLen-1]} \cdots b_{bitOrdering[1]} b_{bitOrdering[0]}\)， \(b_p \in \{0, 1\}\)。

因此，获得第 \(idx\) 个比特模式的概率可以用以下表达式表示

\[Pr(idx) = \dfrac{abs2sum[idx]}{\sum_{k}abs2sum[k]}.\]

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

如果 \(idx\) 满足 \((idx \ \& \ bitString) = idx\)，我们得到 \(sv[idx] = \dfrac{1}{\sqrt{norm}} sv[idx]\)。否则，\(sv[idx] = 0\)，其中 \(norm\) 是归一化因子。

用例¶

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

// measure with a bit string
custatevecBatchMeasure(
    handle, sv, svDataType, nIndexBits, bitString, bitOrdering, bitStringLen,
    randnum, collapse);

该操作等效于以下操作

// compute the sums of squared absolute values of state vector elements
int maskLen = 0;
int* maskBitString = nullptr;
int* maskOrdering = nullptr;

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

// [User] compute a cumulative sum and choose bitString by a random number

// collapse if necessary
switch (collapse) {
case CUSTATEVEC_COLLAPSE_NORMALIZE_AND_ZERO:
    custatevecCollapseByBitString(
        handle, sv, svDataType, nIndexBits, bitString, bitOrdering,
        bitStringLen, norm);
    break;  /* collapse */
case CUSTATEVEC_COLLAPSE_NONE:
    break;  /* Do nothing */

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

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

// The state vector is divided to nSubSvs sub state vectors.
// each state vector has its own ordinal and nLocalBits index bits.
// The ordinals of sub state vectors correspond to the extended index bits.
// In this example, all the local qubits are measured and collapsed.

// get abs2sum for each sub state vector
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();
}

// get cumulative array
double cumulativeArray[nSubSvs + 1];
cumulativeArray[0] = 0.0;
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cumulativeArray[iSv + 1] = cumulativeArray[iSv] + abs2SumArray[iSv];
}

// measurement
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    // detect which sub state vector will be used for measurement.
    if (cumulativeArray[iSv] <= randnum && randnum < cumulativeArray[iSv + 1]) {
        double norm = cumulativeArray[nSubSvs];
        double offset = cumulativeArray[iSv];
        cudaSetDevice(devices[iSv]);
        // measure local qubits. Here the state vector will not be collapsed.
        // Only local qubits can be included in bitOrdering and bitString arguments.
        // That is, bitOrdering = {0, 1, 2, ..., nLocalBits - 1} and
        // bitString will store values of local qubits as an array of integers.
        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();
}

// get abs2Sum after collapse
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();
}

// get norm after collapse
double norm = 0.0;
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    norm += abs2SumArray[iSv];
}

// collapse sub state vectors
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]);
    custatevecCollapseByBitString(
        handle[iSv], d_sv[iSv], CUDA_C_64F, nLocalBits, bitString, bitOrdering,
        bitStringLen, norm);
}

// destroy handle
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 以计算态向量的范数。在这种情况下，0 传递给 bitOrderingLen 参数，并且 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 参数指定要测量的索引位。测量结果存储在 bitString 中，顺序由 bitOrdering 参数指定。

如果为 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 数组可以在主机或设备上。bitOrdering 和 bitOrderingLen 参数指定批处理中 abs2sum 数组的索引位顺序。未指定的位将被折叠（求和）。

maskBitStrings、maskOrdering 和 maskLen 参数指定用于批处理状态向量的索引位的位掩码。abs2sum 数组是通过使用索引与指定的掩码位字符串匹配的状态向量元素来计算的。maskBitStrings 参数将掩码值数组指定为应用于状态向量索引的整数位掩码。

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

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

可以指定空的 bitOrdering 以计算态向量的范数。在这种情况下，0 传递给 bitOrderingLen 参数，并且 bitOrdering 参数可以为空指针。

注意

在此版本中，即使 maskBitStrings 参数包含无效的位字符串，此 API 也不会返回任何错误。但是，在适用的情况下，错误消息将打印到标准输出。

参数

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^\text{nIndexBits}\)，状态向量的数量由 nSVs 参数指定。

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

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

请注意，bitOrdering 和 bitStringLen 适用于批处理中的所有状态向量，而 bitStrings 和 norms 数组的大小均为 nSVs，并且可以驻留在主机或设备上。

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

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

注意

在此版本中，如果指定了无效的 bitStrings 或 norms 参数，custatevecCollapseByBitStringBatched() 不会返回错误。但是，在适用的情况下，错误消息将打印到标准输出。

注意

与非批处理版本 (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 参数指定要测量的索引位。测量结果存储在 bitString 中，顺序由 bitOrdering 参数指定。

如果为 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] 整个状态向量的平方绝对值之和

期望值¶

通过矩阵计算期望值¶

期望值执行以下操作

\[\langle A \rangle = \bra{\phi}A\ket{\phi},\]

其中 \(\ket{\phi}\) 是状态向量，\(A\) 是矩阵或观测算符。用于计算期望值的 API custatevecComputeExpectation() 可能需要外部工作区来处理大型矩阵，custatevecComputeExpectationGetWorkspaceSize() 提供工作区的大小。如果设置了设备内存处理程序，则可以跳过 custatevecComputeExpectationGetWorkspaceSize()。

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

用例¶

// check the size of external workspace
custatevecComputeExpectationGetWorkspaceSize(
    handle, svDataType, nIndexBits, matrix, matrixDataType, layout, nBasisBits, computeType,
    &extraWorkspaceSizeInBytes);

// allocate external workspace if necessary
void* extraWorkspace = nullptr;
if (extraWorkspaceSizeInBytes > 0)
    cudaMalloc(&extraWorkspace, extraWorkspaceSizeInBytes);

// perform expectation
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] 矩阵乘法的 computeType
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] 矩阵乘法的 computeType
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] 矩阵乘法的 computeType
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^\text{nIndexBits}\)，状态向量的数量由 nSVs 参数指定。

expectationValues 参数指向用于输出期望值的单个内存块。无论输入数据类型如何，此 API 都以双精度 (complex128) 返回值。输出数组大小为 ( \(\text{nMatrices} \times \text{nSVs}\) )，其前导维度为 nMatrices。

matrices 参数是方阵的二维数组的主机或设备指针。矩阵的大小为 ( \(\text{nMatrices} \times 2^\text{nBasisBits} \times 2^\text{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] 矩阵乘法的 computeType
extraWorkspace – [in] 指向额外工作空间的指针
extraWorkspaceSizeInBytes – [in] 额外工作空间的大小（以字节为单位）

保 Pauli 基上的期望值¶

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

\[P_{\text{basisBits}[0]} \otimes P_{\text{basisBits}[1]} \otimes \cdots \otimes P_{\text{basisBits}[\text{nBasisBits}-1]}.\]

每个矩阵 \(P_{\text{basisBits}[i]}\) 可以是 Pauli 矩阵 \(I\)、 \(X\)、 \(Y\) 和 \(Z\) 之一，分别对应于 custatevecPauli_t 枚举 CUSTATEVEC_PAULI_I、 CUSTATEVEC_PAULI_X、 CUSTATEVEC_PAULI_Y 和 CUSTATEVEC_PAULI_Z。另请参阅 custatevecPauli_t 了解详情。

用例¶

// calculate the norm and the expectations for Z(q1) and 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)¶

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

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

单个 Pauli 算子序列 pauliOperators 通过使用 custatevecPauli_t 数组表示。这些 Pauli 算子作用的基位由索引位位置数组表示。如果未为索引位指定 Pauli 算子，则隐式假定为单位算子 (CUSTATEVEC_PAULI_I)。

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

Pauli 算子序列的数量由 nPauliOperatorArrays 参数指定。

Pauli 算子的多个序列以下列方式以数组的数组形式表示：

pauliOperatorsArray 参数是 custatevecPauli_t 数组的数组。
basisBitsArray 是基位位置数组的数组。
nBasisBitsArray 参数保存 Pauli 算子序列和基位数组的长度数组。

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

如果为 Pauli 算子序列指定的基位具有重复项和/或超出 [0, nIndexBits) 范围，此函数将返回 CUSTATEVEC_STATUS_INVALID_VALUE。

此函数接受空的 Pauli 算子序列以获取状态向量的范数。

参数

handle – [in] cuStateVec 库的句柄
sv – [in] 态向量
svDataType – [in] 状态向量的数据类型
nIndexBits – [in] 状态向量的索引位数量
expectationValues – [out] 指向用于存储期望值的主机数组的指针
pauliOperatorsArray – [in] 指向 Pauli 算子数组的主机数组的指针
nPauliOperatorArrays – [in] Pauli 算子数组的数量
basisBitsArray – [in] 基位数组的主机数组
nBasisBitsArray – [in] 基位数量的主机数组

矩阵属性测试¶

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

如果矩阵 \(A\) 是酉矩阵，则 \(AA^{\dagger} = A^{\dagger}A = I\)，其中 \(A^{\dagger}\) 是 \(A\) 的共轭转置， \(I\) 是单位矩阵。

当为参数提供 CUSTATEVEC_MATRIX_TYPE_UNITARY 时，此 API 计算 1-范数 \(||R||_1 = \sum{|r_{ij}|}\)，其中 \(R = AA^{\dagger} - I\)。如果 \(A\) 是酉矩阵，则此值将近似为零。

如果矩阵 \(A\) 是厄米特矩阵，则 \(A^{\dagger} = A\)。

当为参数提供 CUSTATEVEC_MATRIX_TYPE_HERMITIAN 时，此 API 计算 2-范数 \(||R||_2 = \sum{|r_{ij}|^2}\)，其中 \(R = (A - A^{\dagger}) / 2\)。如果 \(A\) 是厄米特矩阵，则此值将近似为零。

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

用例¶

double residualNorm;

void* extraWorkspace = nullptr;
size_t extraWorkspaceSizeInBytes = 0;

// check the size of external workspace
custatevecTestMatrixTypeGetWorkspaceSize(
    handle, matrixType, matrix, matrixDataType, layout,
    nTargets, adjoint, computeType, &extraWorkspaceSizeInBytes);

// allocate external workspace if necessary
if (extraWorkspaceSizeInBytes > 0)
    cudaMalloc(&extraWorkspace, extraWorkspaceSizeInBytes);

// execute testing
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 = (AA^{\dagger} - I) \)，其中 \( A \) 是给定的矩阵。返回 \( R \) 矩阵元素的绝对值之和。

对于厄米特类型测试，计算 \( R = (M - M^{\dagger}) / 2 \)。返回 \( 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] 额外的工作区大小

采样¶

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

用例¶

// create sampler and check the size of external workspace
custatevecSamplerCreate(
    handle, sv, svDataType, nIndexBits, &sampler, nMaxShots,
    &extraWorkspaceSizeInBytes);

// allocate external workspace if necessary
void extraWorkspace = nullptr;
if (extraWorkspaceSizeInBytes > 0)
    cudaMalloc(extraWorkspace, extraWorkspaceSizeInBytes);

// calculate cumulative abs2sum
custatevecSamplerPreprocess(
    handle, sampler, extraWorkspace, extraWorkspaceSizeInBytes);

// [User] generate randnums, array of random numbers [0, 1) for sampling
...

// sample bit strings
custatevecSamplerSample(
    handle, sampler, bitStrings, bitOrdering, bitStringLen, randnums, nShots,
    output);

// deallocate the sampler
custatevecSamplerDestroy(sampler);

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

// The state vector is divided to nSubSvs sub state vectors.
// each state vector has its own ordinal and nLocalBits index bits.
// The ordinals of sub state vectors correspond to the extended index bits.

// create sampler and check the size of external workspace
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]);
}

// allocate external workspace if necessary
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    if (extraWorkspaceSizeInBytes[iSv] > 0) {
        cudaSetDevice(devices[iSv]);
        cudaMalloc(&extraWorkspace[iSv], extraWorkspaceSizeInBytes[iSv]);
    }
}

// sample preprocess
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]) );
    custatevecSampler_preprocess(
        handle[iSv], sampler[iSv], extraWorkspace[iSv],
        extraWorkspaceSizeInBytes[iSv]);
}

// get norm of the sub state vectors
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();
}

// get cumulative array
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];

// apply offset and norm
for (int iSv = 0; iSv < nSubSvs; iSv++) {
    cudaSetDevice(devices[iSv]) );
    custatevecSamplerApplySubSVOffset(
        handle[iSv], sampler[iSv], iSv, nSubSvs, cumulativeArray[iSv], norm);
}

// divide randnum array. randnums must be sorted in the ascending order.
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;
}

// sample bit strings
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] 此采样器上下文使用的最大 shots 数量
extraWorkspaceSizeInBytes – [out] 工作区大小

注意

nMaxShots 的最大值为 \(2^{31} - 1\)。如果该值超过限制，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 参数的指针将与采样器句柄关联，并且应在其生命周期内保留。 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] shots 的数量
output – [in] 采样比特串的顺序

`custatevecSamplerDestroy`¶

custatevecStatus_t custatevecSamplerDestroy(custatevecSamplerDescriptor_t sampler)¶

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

参数: sampler – [in] 采样器描述符

访问器¶

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

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

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

用例¶

提取¶

// create accessor and check the size of external workspace
custatevecAccessorCreateView(
    handle, d_sv, CUDA_C_64F, nIndexBits, &accessor, bitOrdering, bitOrderingLen,
    maskBitString, maskOrdering, maskLen, &extraWorkspaceSizeInBytes);

// allocate external workspace if necessary
if (extraWorkspaceSizeInBytes > 0)
    cudaMalloc(&extraWorkspace, extraWorkspaceSizeInBytes);

// set external workspace
custatevecAccessorSetExtraWorkspace(
    handle, &accessor, extraWorkspace, extraWorkspaceSizeInBytes);

// get state vector elements
custatevecAccessorGet(
    handle, &accessor, buffer, accessBegin, accessEnd);

// deallocate the accessor
custatevecAccessorDestroy(accessor);

更新¶

// create accessor and check the size of external workspace
custatevecAccessorCreate(
    handle, d_sv, CUDA_C_64F, nIndexBits, &accessor, bitOrdering, bitOrderingLen,
    maskBitString, maskOrdering, maskLen, &extraWorkspaceSizeInBytes);

// allocate external workspace if necessary
if (extraWorkspaceSizeInBytes > 0)
    cudaMalloc(&extraWorkspace, extraWorkspaceSizeInBytes);

// set external workspace
custatevecAccessorSetExtraWorkspace(
    handle, &accessor, extraWorkspace, extraWorkspaceSizeInBytes);

// set state vector elements
custatevecAccessorSet(
    handle, &accessor, buffer, 0, nSvSize);

// deallocate the accessor
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)th 索引位是 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() 用于多设备，以重新排序状态向量元素。

用例¶

单设备¶

// This example uses 3 qubits.
const int nIndexBits = 3;

// swap 0th and 2nd qubits
const int nBitSwaps  = 1;
const int2 bitSwaps[] = {{0, 2}}; // specify the qubit pairs

// swap the state vector elements only if 1st qubit is 1
const int maskLen = 1;
int maskBitString[] = {1}; // specify the values of mask qubits
int maskOrdering[] = {1};  // specify the mask qubits

// Swap index bit pairs.
// {|000>, |001>, |010>, |011>, |100>, |101>, |110>, |111>} will be permuted to
// {|000>, |001>, |010>, |110>, |100>, |101>, |011>, |111>}.
custatevecSwapIndexBits(handle, sv, svDataType, nIndexBits, bitSwaps, nBitSwaps,
    maskBitString, maskOrdering, maskLen);

多设备¶

// This example uses 2 GPUs and each GPU stores 2-qubit sub state vector.
const int nGlobalIndexBits = 1;
const int nLocalIndexBits = 2;
const int nHandles = 1 << nGlobalIndexBits;

// Users are required to enable direct access on a peer device prior to the swap API call.
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);

// specify the type of device network topology to optimize the data transfer sequence.
// Here, devices are assumed to be connected via NVLink with an NVSwitch or
// PCIe device network with a single PCIe switch.
const custatevecDeviceNetworkType_t deviceNetworkType = CUSTATEVEC_DEVICE_NETWORK_TYPE_SWITCH;

// swap 0th and 2nd qubits
const int nIndexBitSwaps  = 1;
const int2 indexBitSwaps[] = {{0, 2}}; // specify the qubit pairs

// swap the state vector elements only if 1st qubit is 1
const int maskLen = 1;
int maskBitString[] = {1}; // specify the values of mask qubits
int maskOrdering[] = {1};  // specify the mask qubits

// Swap index bit pairs.
// {|000>, |001>, |010>, |011>, |100>, |101>, |110>, |111>} will be permuted to
// {|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)th 索引位是 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 调用都在设置为 handles 的流上发出，则这些调用将被正确排序。此函数是异步执行的。请将流设置为当前设备的句柄，并使用 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 库直接链接到应用程序，并且 CUSTATEVEC_COMMUNICATOR_TYPE_OPENMPI 或 CUSTATEVEC_COMMUNICATOR_TYPE_MPICH 被指定给 communicatorType 参数，则应将 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 参数给出。根据系统情况，增加数据传输工作区的大小可以提高性能。

如果在单个进程中使用 SVSwapWorker，则可以将 communicator 参数设置为 null。在这种情况下，内部 CUDA 调用在由 stream 参数指定的流上串行化。

如果子状态向量分布到多个进程，则应使用 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] 传输工作区的最小必需大小

`custatevecSVSwapWorkerCreateWithSemaphore`¶

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

使用信号量创建状态向量交换工作器。

此函数创建一个 custatevecSVSwapWorkerDescriptor_t，用于在多个子状态向量之间交换/发送/接收状态向量元素。此函数是 custatevecSVSwapWorkerCreate 的替代版本，它使用信号量而不是 CUDA IPC 事件进行同步。作为 communicator 参数指定的通信器用于进程间通信，因此状态向量元素在分布到多个进程和节点的子状态向量之间传输。

创建的描述符在创建句柄的设备上工作。由 orgSubSV 参数指定的原始子状态向量应分配在同一设备上。这同样适用于分别由 orgSemaphore 和 stream 参数指定的设备内存和流。

orgSemaphore 参数应是指向设备内存块的指针，该内存块的大小为 4 字节或更大。由于信号量用于进程之间的同步，因此应通过在 CUDA Runtime API 中使用 cudaIpcGetMemHandle() 和 cudaIpcOpenMemHandle()，或者在 CUDA Driver API 中使用 cuMemExportToShareableHandle() 和 cuMemImportFromSharableHandle() 在进程之间共享分配。

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

SVSwapWorker 可在单个进程中使用。对于这种情况，可以将 \communicator 参数设置为 NULL。内部 CUDA 调用在作为 stream 参数给出的流上串行化。如果将 NULL 传递给 \communicator 参数，则应将 \orgSemaphore 参数设置为 NULL。

可以将 orgSemaphore 设置为 nullptr 以禁用 SVSwapWorker 实例之间的同步。

参数

handle – [in] 指向 cuStateVec 库的句柄
svSwapWorker – [out] 状态向量交换工作器
communicator – [in] 指向 MPI 通信器的指针
orgSubSV – [in] 指向子状态向量的指针
orgSubSVIndex – [in] 由 orgSubSV 参数指定的子状态向量的索引
orgSemaphore – [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)¶

使用 CUDA IPC 事件设置可通过 GPUDirect P2P 访问的子状态向量指针。

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

如果子状态向量分配在不同的进程中，则应通过在 CUDA Runtime API 中使用 cudaIpcGetMemHandle() 和 cudaIpcOpenMemHandle()，或者在 CUDA Driver API 中使用 cuMemExportToShareableHandle() 和 cuMemImportFromSharableHandle() 在进程之间共享子状态向量指针。相应地，应通过 CUDA IPC 重新分配 dstEvents 参数中的 CUDA 事件。

参数

handle – [in] 指向 cuStateVec 库的句柄
svSwapWorker – [in] 状态向量交换工作器
dstSubSVsP2P – [in] 指向通过 GPUDirect P2P 访问的子状态向量的指针数组
dstSubSVIndicesP2P – [in] 由 dstSubSVsP2P 参数指定的子状态向量指针的子状态向量索引
dstEvents – [in] 用于创建对等工作器的事件
nDstSubSVsP2P – [in] 由 dstSubSVsP2P 参数指定的子状态向量指针的数量

`custatevecSVSwapWorkerSetSubSVsP2PWithSemaphores`¶

custatevecStatus_t custatevecSVSwapWorkerSetSubSVsP2PWithSemaphores(custatevecHandle_t handle, custatevecSVSwapWorkerDescriptor_t svSwapWorker, void **dstSubSVsP2P, const int32_t *dstSubSVIndicesP2P, void **dstSemaphores, const uint32_t nDstSubSVsP2P)¶

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

此函数设置可由状态向量交换工作器工作的设备通过 GPUDirect P2P 访问的子状态向量指针。应将子状态向量指针与子状态向量索引和信号量一起指定，这些索引和信号量传递给 custatevecSVSwapWorkerCreateWithSemaphore() 以创建对等 SV 交换工作器实例。

如果子状态向量分配在不同的进程中，则应通过在 CUDA Runtime API 中使用 cudaIpcGetMemHandle() 和 cudaIpcOpenMemHandle()，或者在 CUDA Driver API 中使用 cuMemExportToShareableHandle() 和 cuMemImportFromSharableHandle() 从其他进程导入子状态向量指针和信号量。

如果在调用 custatevecSVSwapWorkerCreateWithSemaphore() 时将 the orgSemaphore 参数设置为 NULL，则应将 dstSemaphores 参数设置为 NULL。

参数

handle – [in] 指向 cuStateVec 库的句柄
svSwapWorker – [in] 状态向量交换工作器
dstSubSVsP2P – [in] 指向通过 GPUDirect P2P 访问的子状态向量的指针数组
dstSubSVIndicesP2P – [in] 由 dstSubSVsP2P 参数指定的子状态向量指针的子状态向量索引
dstSemaphores – [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 – [输入] 开始传输的索引
end – [输入] 结束传输的索引

子状态向量迁移¶

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

API 参考¶

`custatevecSubSVMigratorCreate`¶

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

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

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

参数

handle – [in] cuStateVec 库的句柄
migrator – [输出] 指向新迁移器描述符的指针
deviceSlots – [输入] 指向设备上子状态向量的指针
svDataType – [in] 状态向量的数据类型
nDeviceSlots – [输入] deviceSlots 中的子状态向量的数量
nLocalIndexBits – [输入] 子状态向量的索引位数

`custatevecSubSVMigratorDestroy`¶

custatevecStatus_t custatevecSubSVMigratorDestroy(custatevecHandle_t handle, custatevecSubSVMigratorDescriptor_t migrator)¶

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

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

参数

handle – [in] cuStateVec 库的句柄
migrator – [输入/输出] 迁移器描述符

`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 – [输入] 迁移器描述符
deviceSlotIndex – [输入] 指定要迁移的子状态向量的索引
srcSubSV – [输入] 指向要迁移到 deviceSlots 的子状态向量的指针
dstSubSV – [输出] 指向要从 deviceSlots 迁移的子状态向量的指针
begin – [输入] 开始迁移的索引
end – [输入] 结束迁移的索引

cuStateVec 函数¶

库管理¶

句柄管理 API¶

custatevecCreate¶

custatevecDestroy¶

custatevecGetDefaultWorkspaceSize¶

custatevecSetWorkspace¶

CUDA 流管理 API¶

custatevecSetStream¶

custatevecGetStream¶

错误管理 API¶

custatevecGetErrorName¶

custatevecGetErrorString¶

日志记录器 API¶

custatevecLoggerSetCallback¶

custatevecLoggerSetCallbackData¶

custatevecLoggerSetFile¶

custatevecLoggerOpenFile¶

custatevecLoggerSetLevel¶

custatevecLoggerSetMask¶

custatevecLoggerForceDisable¶

版本控制 API¶

custatevecGetProperty¶

custatevecGetVersion¶

内存管理 API¶

custatevecSetDeviceMemHandler¶

custatevecGetDeviceMemHandler¶

初始化¶

用例¶

API 参考¶

custatevecInitializeStateVector¶

门应用¶

通用矩阵¶

用例¶

API 参考¶

custatevecApplyMatrixGetWorkspaceSize¶

custatevecApplyMatrix¶

custatevecApplyMatrixBatchedGetWorkspaceSize¶

custatevecApplyMatrixBatched¶

泡利矩阵¶

用例¶

API 参考¶

custatevecApplyPauliRotation¶

广义置换矩阵¶

用例¶

API 参考¶

custatevecApplyGeneralizedPermutationMatrixGetWorkspaceSize¶

custatevecApplyGeneralizedPermutationMatrix¶

测量¶

Z 基测量¶

用例¶

API 参考¶

custatevecAbs2SumOnZBasis¶

custatevecCollapseOnZBasis¶

custatevecMeasureOnZBasis¶

量子比特测量¶

用例¶

API 参考¶

custatevecAbs2SumArray¶

custatevecCollapseByBitString¶

custatevecBatchMeasure¶

custatevecAbs2SumArrayBatched¶

custatevecCollapseByBitStringBatchedGetWorkspaceSize¶

custatevecCollapseByBitStringBatched¶

custatevecMeasureBatched¶

custatevecBatchMeasureWithOffset¶

期望值¶

通过矩阵计算期望值¶

用例¶

API 参考¶

custatevecComputeExpectationGetWorkspaceSize¶

custatevecComputeExpectation¶

custatevecComputeExpectationBatchedGetWorkspaceSize¶

custatevecComputeExpectationBatched¶

保 Pauli 基上的期望值¶

用例¶

API 参考¶

custatevecComputeExpectationsOnPauliBasis¶

矩阵属性测试¶

用例¶

`custatevecCreate`¶

`custatevecDestroy`¶

`custatevecGetDefaultWorkspaceSize`¶

`custatevecSetWorkspace`¶

`custatevecSetStream`¶

`custatevecGetStream`¶

`custatevecGetErrorName`¶

`custatevecGetErrorString`¶

`custatevecLoggerSetCallback`¶

`custatevecLoggerSetCallbackData`¶

`custatevecLoggerSetFile`¶

`custatevecLoggerOpenFile`¶

`custatevecLoggerSetLevel`¶

`custatevecLoggerSetMask`¶

`custatevecLoggerForceDisable`¶

`custatevecGetProperty`¶

`custatevecGetVersion`¶

`custatevecSetDeviceMemHandler`¶

`custatevecGetDeviceMemHandler`¶

`custatevecInitializeStateVector`¶

`custatevecApplyMatrixGetWorkspaceSize`¶

`custatevecApplyMatrix`¶

`custatevecApplyMatrixBatchedGetWorkspaceSize`¶

`custatevecApplyMatrixBatched`¶

`custatevecApplyPauliRotation`¶

`custatevecApplyGeneralizedPermutationMatrixGetWorkspaceSize`¶

`custatevecApplyGeneralizedPermutationMatrix`¶

`custatevecAbs2SumOnZBasis`¶

`custatevecCollapseOnZBasis`¶

`custatevecMeasureOnZBasis`¶

`custatevecAbs2SumArray`¶

`custatevecCollapseByBitString`¶

`custatevecBatchMeasure`¶

`custatevecAbs2SumArrayBatched`¶

`custatevecCollapseByBitStringBatchedGetWorkspaceSize`¶

`custatevecCollapseByBitStringBatched`¶

`custatevecMeasureBatched`¶

`custatevecBatchMeasureWithOffset`¶

`custatevecComputeExpectationGetWorkspaceSize`¶

`custatevecComputeExpectation`¶

`custatevecComputeExpectationBatchedGetWorkspaceSize`¶

`custatevecComputeExpectationBatched`¶

`custatevecComputeExpectationsOnPauliBasis`¶

`custatevecTestMatrixTypeGetWorkspaceSize`¶

`custatevecTestMatrixType`¶

`custatevecSamplerCreate`¶

`custatevecSamplerPreprocess`¶

`custatevecSamplerGetSquaredNorm`¶

`custatevecSamplerApplySubSVOffset`¶

`custatevecSamplerSample`¶

`custatevecSamplerDestroy`¶

`custatevecAccessorCreate`¶

`custatevecAccessorCreateView`¶

`custatevecAccessorDestroy`¶

`custatevecAccessorSetExtraWorkspace`¶

`custatevecAccessorGet`¶

`custatevecAccessorSet`¶

`custatevecSwapIndexBits`¶

`custatevecMultiDeviceSwapIndexBits`¶

`custatevecCommunicatorCreate`¶

`custatevecCommunicatorDestroy`¶

`custatevecDistIndexBitSwapSchedulerCreate`¶

`custatevecDistIndexBitSwapSchedulerDestroy`¶

`custatevecDistIndexBitSwapSchedulerSetIndexBitSwaps`¶

`custatevecDistIndexBitSwapSchedulerGetParameters`¶

`custatevecSVSwapWorkerCreate`¶

`custatevecSVSwapWorkerCreateWithSemaphore`¶

`custatevecSVSwapWorkerDestroy`¶

`custatevecSVSwapWorkerSetExtraWorkspace`¶

`custatevecSVSwapWorkerSetTransferWorkspace`¶

`custatevecSVSwapWorkerSetSubSVsP2P`¶

`custatevecSVSwapWorkerSetSubSVsP2PWithSemaphores`¶

`custatevecSVSwapWorkerSetParameters`¶

`custatevecSVSwapWorkerExecute`¶

`custatevecSubSVMigratorCreate`¶

`custatevecSubSVMigratorDestroy`¶

`custatevecSubSVMigratorMigrate`¶