cuDensityMat 函数¶

库上下文管理 API¶

`cudensitymatCreate`¶

cudensitymatStatus_t cudensitymatCreate(cudensitymatHandle_t *handle)¶

创建并初始化库上下文。

参数: handle – [out] 库句柄。
返回: cudensitymatStatus_t

`cudensitymatDestroy`¶

cudensitymatStatus_t cudensitymatDestroy(cudensitymatHandle_t handle)¶

销毁库上下文。

参数: handle – [in] 库句柄。
返回: cudensitymatStatus_t

`cudensitymatResetRandomSeed`¶

cudensitymatStatus_t cudensitymatResetRandomSeed(cudensitymatHandle_t handle, int32_t randomSeed)¶

重置库上下文中随机数生成器使用的随机种子。

参数

handle – [inout] 库句柄。
randomSeed – [in] 随机种子值。

返回

cudensitymatStatus_t

分布式并行化 API¶

`cudensitymatResetDistributedConfiguration`¶

cudensitymatStatus_t cudensitymatResetDistributedConfiguration(cudensitymatHandle_t handle, cudensitymatDistributedProvider_t provider, const void *commPtr, size_t commSize)¶

重置与给定库上下文关联的当前分布式执行配置。

接受并存储提供的通信器的副本，该通信器将用于在所有涉及的分布式进程中分发数值运算。

参数

handle – [inout] 库句柄。
provider – [in] 通信服务提供商。
commPtr – [in] 指向类型擦除形式的通信器的指针。
commSize – [in] 通信器的大小（以字节为单位）。

返回

cudensitymatStatus_t

`cudensitymatGetNumRanks`¶

cudensitymatStatus_t cudensitymatGetNumRanks(const cudensitymatHandle_t handle, int32_t *numRanks)¶

返回与给定库上下文关联的分布式进程总数。

参数

handle – [in] 库句柄。
numRanks – [out] 分布式进程数。

返回

cudensitymatStatus_t

`cudensitymatGetProcRank`¶

cudensitymatStatus_t cudensitymatGetProcRank(const cudensitymatHandle_t handle, int32_t *procRank)¶

返回与给定库上下文关联的分布式配置中当前进程的排名。

参数

handle – [in] 库句柄。
procRank – [out] 当前分布式进程的排名。

返回

cudensitymatStatus_t

工作区管理 API¶

`cudensitymatCreateWorkspace`¶

cudensitymatStatus_t cudensitymatCreateWorkspace(const cudensitymatHandle_t handle, cudensitymatWorkspaceDescriptor_t *workspaceDescr)¶

创建工作区描述符。

参数

handle – [in] 库句柄。
workspaceDescr – [out] 工作区描述符。

返回

cudensitymatStatus_t

`cudensitymatDestroyWorkspace`¶

cudensitymatStatus_t cudensitymatDestroyWorkspace(cudensitymatWorkspaceDescriptor_t workspaceDescr)¶

销毁工作区描述符。

参数: workspaceDescr – [inout] 工作区描述符。
返回: cudensitymatStatus_t

`cudensitymatWorkspaceGetMemorySize`¶

cudensitymatStatus_t cudensitymatWorkspaceGetMemorySize(const cudensitymatHandle_t handle, const cudensitymatWorkspaceDescriptor_t workspaceDescr, cudensitymatMemspace_t memSpace, cudensitymatWorkspaceKind_t workspaceKind, size_t *memoryBufferSize)¶

查询所需的工作区缓冲区大小。

参数

handle – [in] 库句柄。
workspaceDescr – [in] 工作区描述符。
memSpace – [in] 内存空间。
workspaceKind – [in] 工作区类型。
memoryBufferSize – [out] 所需的工作区缓冲区大小（以字节为单位）。

返回

cudensitymatStatus_t

`cudensitymatWorkspaceSetMemory`¶

cudensitymatStatus_t cudensitymatWorkspaceSetMemory(const cudensitymatHandle_t handle, cudensitymatWorkspaceDescriptor_t workspaceDescr, cudensitymatMemspace_t memSpace, cudensitymatWorkspaceKind_t workspaceKind, void *memoryBuffer, size_t memoryBufferSize)¶

将内存附加到工作区缓冲区。

参数

handle – [in] 库句柄。
workspaceDescr – [inout] 工作区描述符。
memSpace – [in] 内存空间。
workspaceKind – [in] 工作区类型。
memoryBuffer – [in] 指向用户拥有的内存缓冲区的指针，该缓冲区将由指定的工作区使用。
memoryBufferSize – [in] 提供的内存缓冲区的大小（以字节为单位）。

返回

cudensitymatStatus_t

`cudensitymatWorkspaceGetMemory`¶

cudensitymatStatus_t cudensitymatWorkspaceGetMemory(const cudensitymatHandle_t handle, const cudensitymatWorkspaceDescriptor_t workspaceDescr, cudensitymatMemspace_t memSpace, cudensitymatWorkspaceKind_t workspaceKind, void **memoryBuffer, size_t *memoryBufferSize)¶

检索工作区缓冲区。

参数

handle – [in] 库句柄。
workspaceDescr – [in] 工作区描述符。
memSpace – [in] 内存空间。
workspaceKind – [in] 工作区类型。
memoryBuffer – [输出] 指向用户拥有的内存缓冲区的指针，该缓冲区由指定的工作区使用。
memoryBufferSize – [输出] 内存缓冲区的大小（以字节为单位）。

返回

cudensitymatStatus_t

量子态 API¶

`cudensitymatCreateState`¶

cudensitymatStatus_t cudensitymatCreateState(const cudensitymatHandle_t handle, cudensitymatStatePurity_t purity, int32_t numSpaceModes, const int64_t spaceModeExtents[], int64_t batchSize, cudaDataType_t dataType, cudensitymatState_t *state)¶

定义给定纯度和形状的空量子态，或此类量子态的批次。

定义状态空间的空间模式数量始终是用于定义相应复合张量积空间的的量子自由度数量。这样，纯态张量中的模式数量等于空间模式（量子自由度）的数量。混合态张量中的模式数量等于空间模式数量的两倍，包括 ket 模式集和 bra 模式集，这两个集合在范围方面相同，并且 ket 模式在 bra 模式之前，例如：S[i0, i1, j0, j1] 张量表示具有两个自由度的混合量子态，其中模式 {i0, i1} 形成 ket 集，模式 {j0, j1} 形成 bra 集，使得 ket 模式 i0 对应于 bra 模式 j0，并且 ket 模式 i1 对应于 bra 模式 j1。相比之下，具有两个自由度的纯量子态由张量 S[i0, i1] 表示，该张量仅具有 ket 模式（没有 bra 模式）。此外，批处理的纯/混合态在其密集张量表示中添加了一个额外的（批处理）模式，即：纯态为 S[i0, i1, b]，混合态为 S[i0, i1, j0, j1, b]，其中 b 是批次的大小（批处理维度）。

参数

handle – [in] 库句柄。
purity – [输入] 所需的量子态纯度。
numSpaceModes – [输入] 空间模式的数量（自由度的数量）。
spaceModeExtents – [输入] 空间模式的范围（自由度的维度）。
batchSize – [输入] 批次大小（形状相同的量子态的数量）。将批次大小设置为零与将其设置为 1 相同。
dataType – [输入] 表示数据类型（张量元素的类型）。
state – [输出] 空量子态（或一批量子态）。

返回

cudensitymatStatus_t

`cudensitymatDestroyState`¶

cudensitymatStatus_t cudensitymatDestroyState(cudensitymatState_t state)¶

销毁量子态。

参数: state – [输入] 量子态（或一批量子态）。
返回: cudensitymatStatus_t

`cudensitymatStateGetNumComponents`¶

cudensitymatStatus_t cudensitymatStateGetNumComponents(const cudensitymatHandle_t handle, const cudensitymatState_t state, int32_t *numStateComponents)¶

查询构成所选量子态表示的组件（张量）的数量（在多进程运行的当前进程上）。

量子态表示可以包括一个或多个组件（张量），这些组件（张量）分布在一个或多个并行进程上（在分布式多 GPU 运行中）。完整的状态向量或密度矩阵表示仅由一个组件组成，即完整的状态张量，可以对其进行切片并分布在所有并行进程上（在分布式多 GPU 运行中）。分解的量子态表示包括多个组件，并且这些组件（张量）通常分布在所有并行进程上（在分布式多 GPU 运行中）。

注意

在多进程运行中，此函数返回本地存储的组件数量，通常，该数量可能小于跨所有并行进程存储的组件总数。可以使用 API 函数 cudensitymatStateGetComponentInfo 通过提供其本地 ID 来获取有关给定本地组件的更多信息。

注意

批处理不会向量子态表示添加新组件，它只是使所有现有组件都进行批处理。相应的张量获得一个额外的（最重要）模式，该模式表示批处理维度。

参数

handle – [in] 库句柄。
state – [输入] 量子态（或一批量子态）。
numStateComponents – [输出] 量子态表示中的组件（张量）数量（在当前进程上）。

返回

cudensitymatStatus_t

`cudensitymatStateGetComponentStorageSize`¶

cudensitymatStatus_t cudensitymatStateGetComponentStorageSize(const cudensitymatHandle_t handle, const cudensitymatState_t state, int32_t numStateComponents, size_t componentBufferSize[])¶

查询构成量子态表示的每个组件（张量）的存储大小（以字节为单位）（在多进程运行的当前进程上）。

参数

handle – [in] 库句柄。
state – [输入] 量子态（或一批量子态）。
numStateComponents – [输入] 量子态表示中的组件（张量）数量（在当前进程上）。
componentSize – [输出] 构成量子态表示的每个组件（张量）的存储大小（字节）（在当前进程上）。

返回

cudensitymatStatus_t

`cudensitymatStateGetComponentNumModes`¶

cudensitymatStatus_t cudensitymatStateGetComponentNumModes(const cudensitymatHandle_t handle, cudensitymatState_t state, int32_t stateComponentLocalId, int32_t *stateComponentGlobalId, int32_t *stateComponentNumModes, int32_t *batchModeLocation)¶

查询本地组件张量中的模式数量（在多进程运行的当前进程上）。

参数

handle – [in] 库句柄。
state – [输入] 量子态（或一批量子态）。
stateComponentLocalId – [输入] 组件本地 ID（在当前并行进程上）。
stateComponentGlobalId – [输出] 组件全局 ID（跨所有并行进程）。
stateComponentNumModes – [输出] 组件张量阶数（模式数量）。
batchModeLocation – [输出] 批处理模式的位置（如果不存在批处理模式，则为 -1）。

返回

cudensitymatStatus_t

`cudensitymatStateGetComponentInfo`¶

cudensitymatStatus_t cudensitymatStateGetComponentInfo(const cudensitymatHandle_t handle, cudensitymatState_t state, int32_t stateComponentLocalId, int32_t *stateComponentGlobalId, int32_t *stateComponentNumModes, int64_t stateComponentModeExtents[], int64_t stateComponentModeOffsets[])¶

查询本地存储的组件张量的信息，该张量表示完整组件或其切片（在多进程运行的当前进程上）。

此 API 函数查询全局组件 ID（跨所有并行进程）、张量模式的数量（包括批处理模式（如果存在））、所有模式的范围以及所有模式的基本偏移量，如果本地存储的组件张量表示完整组件张量的切片，则基本偏移量可能不为零。切片模式的基本偏移量是该模式在完整张量模式内的起始索引值。

参数

handle – [in] 库句柄。
state – [输入] 量子态（或一批量子态）。
stateComponentLocalId – [输入] 组件本地 ID（在当前并行进程上）。
stateComponentGlobalId – [输出] 组件全局 ID（跨所有并行进程）。
stateComponentNumModes – [输出] 组件张量阶数（模式数量）。
stateComponentModeExtents – [输出] 组件张量模式范围（数组的大小必须足够，请参阅 cudensitymatStateGetComponentNumModes）
stateComponentModeOffsets – [输出] 组件张量模式偏移量（数组的大小必须足够，请参阅 cudensitymatStateGetComponentNumModes）

返回

cudensitymatStatus_t

`cudensitymatStateAttachComponentStorage`¶

cudensitymatStatus_t cudensitymatStateAttachComponentStorage(const cudensitymatHandle_t handle, cudensitymatState_t state, int32_t numStateComponents, void *componentBuffer[], const size_t componentBufferSize[])¶

为构成量子态表示的每个组件（张量）附加用户拥有的 GPU 可访问的存储缓冲区（在多进程运行的当前进程上）。

提供的用户拥有的 GPU 可访问的存储缓冲区将用于存储构成量子态表示的组件（张量）（在多进程运行的当前进程上）。库将尊重提供的存储缓冲区的初始值，从而为在其选择的表示形式中指定量子态的任何初始值提供机制。在多进程运行中，API 函数 cudensitymatGetComponentInfo 将返回有关请求的组件（张量）的哪个切片存储在当前进程上的信息。

注意

提供的存储缓冲区的大小必须等于或大于通过 cudensitymatStateGetComponentStorageSize 检索的所需大小。

参数

handle – [in] 库句柄。
state – [输入/输出] 量子态（或一批量子态）
numStateComponents – [输入] 量子态表示中的组件（张量）数量（在当前进程上）。
componentBuffer – [输入] 指向用户拥有的 GPU 可访问的存储缓冲区的指针，这些缓冲区用于构成量子态表示的所有组件（张量）（在当前进程上）。
componentBufferSize – [输入] 构成量子态表示的所有组件（张量）的提供的存储缓冲区的大小（在当前进程上）。

返回

cudensitymatStatus_t

`cudensitymatStateInitializeZero`¶

cudensitymatStatus_t cudensitymatStateInitializeZero(const cudensitymatHandle_t handle, cudensitymatState_t state, cudaStream_t stream)¶

将量子态初始化为零（空状态）。

参数

handle – [in] 库句柄。
state – [输入/输出] 量子态（或一批量子态）。
stream – [输入] CUDA 流。

返回

cudensitymatStatus_t

`cudensitymatStateComputeScaling`¶

cudensitymatStatus_t cudensitymatStateComputeScaling(const cudensitymatHandle_t handle, cudensitymatState_t state, const void *scalingFactors, cudaStream_t stream)¶

将量子态初始化为随机值。

计算量子态乘以标量因子。

参数

handle – [in] 库句柄。
state – [输入/输出] 量子态（或一批量子态）。
stream – [输入] CUDA 流。
handle – [in] 库句柄。
state – [输入/输出] 量子态（或一批量子态）。
scalingFactors – [输入] 缩放因子数组，其维度等于 GPU 可访问的 RAM 中的批次大小（与状态使用的数据类型相同）。
stream – [输入] CUDA 流。

返回

cudensitymatStatus_t

返回

cudensitymatStatus_t

`cudensitymatStateComputeNorm`¶

cudensitymatStatus_t cudensitymatStateComputeNorm(const cudensitymatHandle_t handle, const cudensitymatState_t state, void *norm, cudaStream_t stream)¶

计算量子态的平方 Frobenius 范数。

结果通常是维度等于状态批次大小的向量。

注意

对于以复数数据类型表示的量子态，返回的范数的实际数据类型分别为 cuFloatComplex 的 float 和 cuDoubleComplex 的 double。

注意

对于以 FP32 复数表示的量子态，范数类型为 float；对于以 FP64 复数表示的量子态，范数类型为 double。

参数

handle – [in] 库句柄。
state – [输入] 量子态（或一批量子态）。
norm – [输出] 指向 GPU 可访问的 RAM 中的平方 Frobenius 范数向量存储的指针（float 或 double 实数数据类型）。
stream – [输入] CUDA 流。

返回

cudensitymatStatus_t

`cudensitymatStateComputeTrace`¶

cudensitymatStatus_t cudensitymatStateComputeTrace(const cudensitymatHandle_t handle, const cudensitymatState_t state, void *trace, cudaStream_t stream)¶

计算量子态的迹。

纯态的迹定义为其平方范数。混合态的迹等于其密度矩阵的迹。结果通常是维度等于状态批次大小的向量。

参数

handle – [in] 库句柄。
state – [输入] 量子态（或一批量子态）。
norm – [输出] 指向 GPU 可访问的 RAM 中的迹向量存储的指针（与状态使用的数据类型相同）。
stream – [输入] CUDA 流。

返回

cudensitymatStatus_t

`cudensitymatStateComputeAccumulation`¶

cudensitymatStatus_t cudensitymatStateComputeAccumulation(const cudensitymatHandle_t handle, const cudensitymatState_t stateIn, cudensitymatState_t stateOut, const void *scalingFactors, cudaStream_t stream)¶

计算一个量子态累积到另一个形状兼容的量子态中。

参数

handle – [in] 库句柄。
stateIn – [输入] 累积的量子态（或一批量子态）。
stateOut – [输入/输出] 累加量子态（或一批量子态）。
scalingFactors – [输入] 缩放因子数组，其维度等于 GPU 可访问的 RAM 中的批次大小（与状态使用的数据类型相同）。
stream – [输入] CUDA 流。

返回

cudensitymatStatus_t

`cudensitymatStateComputeInnerProduct`¶

cudensitymatStatus_t cudensitymatStateComputeInnerProduct(const cudensitymatHandle_t handle, const cudensitymatState_t stateLeft, const cudensitymatState_t stateRight, void *innerProduct, cudaStream_t stream)¶

计算左量子态和右量子态之间的内积：< state(s)Left | state(s)Right >

对于纯量子态，此函数计算常规希尔伯特空间内积。对于混合量子态，它计算由 Frobenius 矩阵范数引起的矩阵内积：两个密度矩阵的所有列的常规希尔伯特空间内积之和。

结果通常是维度等于两个状态的批次大小的向量，这两个状态的批次大小必须相同。参与的量子态必须具有兼容的形状。

参数

handle – [in] 库句柄。
stateLeft – [输入] 左量子态（或一批量子态）。
stateRight – [输入] 右量子态（或一批量子态）。
innerProduct – [输出] 指向 GPU 可访问的 RAM 中的内积向量存储的指针（与量子态使用的数据类型相同）。
stream – [输入] CUDA 流。

返回

cudensitymatStatus_t

量子算符 API¶

`cudensitymatCreateElementaryOperator`¶

cudensitymatStatus_t cudensitymatCreateElementaryOperator(const cudensitymatHandle_t handle, int32_t numSpaceModes, const int64_t spaceModeExtents[], cudensitymatElementaryOperatorSparsity_t sparsity, int32_t numDiagonals, const int32_t diagonalOffsets[], cudaDataType_t dataType, void *tensorData, cudensitymatWrappedTensorCallback_t tensorCallback, cudensitymatElementaryOperator_t *elemOperator)¶

创建作用于给定数量量子态模式（又称空间模式）的基本张量算符。

基本张量算符是作用于空间模式（量子自由度）特定子集的单个张量算符。该张量算符由一组ket模式和一组对应的bra模式组成，它们的范围匹配，两组模式的数量相同，并且ket模式在bra模式之前，两者顺序相同。例如，T[i0, i1, j0, j1] 是一个二体张量算符，其中模式 {i0, i1} 构成一组 ket 模式，而模式 {j0, j1} 构成一组对应的 bra 模式，其中 ket 模式 i0 对应于 bra 模式 j0，ket 模式 i1 对应于 bra 模式 j1（模式总是以这种方式配对）。每对对应模式中只有一个模式与量子态张量收缩，从左侧或右侧收缩。例如，bra 模式 j0 与量子态的特定 ket 模式收缩（表示从左侧的算符作用），或者 ket 模式 i0 与量子态的特定 bra 模式收缩（表示从右侧的算符作用）。然后，剩余的未收缩模式替换量子态的收缩模式。

张量元素在内存中的存储

CUDENSITYMAT_OPERATOR_SPARSITY_NONE：使用广义列优先布局存储的稠密张量。
CUDENSITYMAT_OPERATOR_SPARSITY_MULTIDIAGONAL：完整的非零对角线以串联形式存储，顺序与 diagonalOffsets 参数中出现的顺序相同。

警告

不同的基本张量算符不得使用相同或重叠的 GPU 存储缓冲区，否则会导致未定义的行为。

参数

handle – [in] 库句柄。
numSpaceModes – [in] 作用的（状态）空间模式的数量。
spaceModeExtents – [in] 作用的（状态）空间模式的范围。
sparsity – [in] 张量算符稀疏性，定义存储方案。
numDiagonals – [in] 对于多对角线张量算符矩阵，指定非零对角线的总数。
diagonalOffsets – [in] 非零对角线的偏移量（例如，主对角线的偏移量为 0，主对角线上方的对角线的偏移量为 +1，主对角线下方的对角线的偏移量为 -1，依此类推）。
dataType – [in] 张量算符数据类型。
tensorData – [in] GPU 可访问的指针，指向张量算符元素存储。
tensorCallback – [in] 可选的用户定义张量回调函数，稍后可以调用该函数以填充提供的存储中的张量元素，或 NULL。
elemOperator – [out] 基本张量算符。

返回

cudensitymatStatus_t

`cudensitymatDestroyElementaryOperator`¶

cudensitymatStatus_t cudensitymatDestroyElementaryOperator(cudensitymatElementaryOperator_t elemOperator)¶

销毁基本张量算符。

参数: elemOperator – [in] 基本张量算符。
返回: cudensitymatStatus_t

`cudensitymatCreateOperatorTerm`¶

cudensitymatStatus_t cudensitymatCreateOperatorTerm(const cudensitymatHandle_t handle, int32_t numSpaceModes, const int64_t spaceModeExtents[], cudensitymatOperatorTerm_t *operatorTerm)¶

创建一个空的算符项，它将是各个张量算符的张量积之和，其中乘积中的每个单独的张量算符作用于不相交的量子态模式（量子自由度）。

注意

创建的算符项将只能作用于驻留在与算符设置作用的相同空间中的量子态。

参数

handle – [in] 库句柄。
numSpaceModes – [in] 定义算符项将作用于其中的主/对偶张量积空间的模式（自由度）数量。
spaceModeExtents – [in] 定义算符项将作用于其中的主/对偶张量积空间的模式（自由度）范围。
operatorTerm – [out] 算符项。

返回

cudensitymatStatus_t

`cudensitymatDestroyOperatorTerm`¶

cudensitymatStatus_t cudensitymatDestroyOperatorTerm(cudensitymatOperatorTerm_t operatorTerm)¶

销毁算符项。

参数: operatorTerm – [in] 算符项。
返回: cudensitymatStatus_t

`cudensitymatOperatorTermAppendElementaryProduct`¶

cudensitymatStatus_t cudensitymatOperatorTermAppendElementaryProduct(const cudensitymatHandle_t handle, cudensitymatOperatorTerm_t operatorTerm, int32_t numElemOperators, const cudensitymatElementaryOperator_t elemOperators[], const int32_t stateModesActedOn[], const int32_t modeActionDuality[], cuDoubleComplex coefficient, cudensitymatWrappedScalarCallback_t coefficientCallback)¶

将作用于量子态模式的基本张量算符的乘积附加到算符项。

参数

handle – [in] 库句柄。
operatorTerm – [inout] 算符项。
numElemOperators – [in] 张量算符乘积中基本张量算符的数量。
elemOperators – [in] 构成张量算符乘积的基本张量算符。
stateModesActedOn – [in] 张量算符乘积作用的状态模式。这是作用于所有构成基本张量算符的状态模式的串联列表，顺序与它们在 elemOperators 参数中出现的顺序相同。
modeActionDuality – [in] 每个模式作用的对偶状态，即作用是应用于量子态的 ket 模式（值 0）还是量子态的 bra 模式（值 1 或其他非零值）。
coefficient – [in] 与张量算符乘积关联的常数复标量系数。
coefficientCallback – [in] 用户定义的复标量回调函数，稍后可以调用该函数以更新与张量算符乘积关联的标量系数，或 NULL。与张量算符乘积关联的总系数是常数系数和标量回调函数结果的乘积（如果已定义）。

返回

cudensitymatStatus_t

`cudensitymatOperatorTermAppendGeneralProduct`¶

cudensitymatStatus_t cudensitymatOperatorTermAppendGeneralProduct(const cudensitymatHandle_t handle, cudensitymatOperatorTerm_t operatorTerm, int32_t numElemOperators, const int32_t numOperatorModes[], const int64_t *operatorModeExtents[], const int64_t *operatorModeStrides[], const int32_t stateModesActedOn[], const int32_t modeActionDuality[], cudaDataType_t dataType, void *tensorData[], cudensitymatWrappedTensorCallback_t tensorCallbacks[], cuDoubleComplex coefficient, cudensitymatWrappedScalarCallback_t coefficientCallback)¶

将作用于不同量子态模式的通用稠密张量算符的乘积附加到算符项。

这是 cudensitymatOperatorTermAppendElementaryProduct 的稍微更通用的版本，它不需要显式构造 cudensitymatElementaryOperator_t 对象。此外，它接受在描述张量算符乘积中表示张量算符的原始稠密张量时指定张量存储步幅。另一方面，它不允许指定张量算符稀疏性，因此在这些情况下会导致性能降低。

警告

来自附加张量乘积的稠密张量算符不得共享 GPU 存储缓冲区。通过此 API 函数作为张量乘积的一部分附加到算符项的每个张量算符都必须有自己的 GPU 存储缓冲区。

参数

handle – [in] 库句柄。
operatorTerm – [inout] 算符项。
numElemOperators – [in] 给定张量算符乘积中稠密张量算符的数量。
numOperatorModes – [in] 每个张量算符中的模式数量（其作用的状态模式数量的两倍）。
operatorModeExtents – [in] 每个稠密张量算符的模式范围。
operatorModeStrides – [in] 每个稠密张量算符的模式步幅。如果特定元素设置为 NULL，则相应的稠密张量算符将假定默认的广义列优先存储步幅。
stateModesActedOn – [in] 张量算符乘积作用的状态模式。这是作用于所有构成稠密张量算符的状态模式的串联列表，顺序与上述参数中出现的顺序相同。
modeActionDuality – [in] 每个模式作用的对偶状态，即作用是应用于量子态的 ket 模式（值 0）还是量子态的 bra 模式（值 1 或其他非零值）。
dataType – [in] 数据类型（对于所有稠密张量算符）。
tensorData – [in] GPU 可访问的指针，指向构成张量算符乘积的每个稠密张量算符的元素。
tensorCallbacks – [in] 用户定义的张量回调函数，稍后可以调用这些函数以更新每个稠密张量算符的元素（任何回调都可以为 NULL）。
coefficient – [in] 与张量算符乘积关联的常数复标量系数。
coefficientCallback – [in] 用户定义的复标量回调函数，稍后可以调用该函数以更新与张量算符乘积关联的标量系数，或 NULL。与张量算符乘积关联的总系数是常数系数和标量回调函数结果的乘积（如果已定义）。

返回

cudensitymatStatus_t

`cudensitymatCreateOperator`¶

cudensitymatStatus_t cudensitymatCreateOperator(const cudensitymatHandle_t handle, int32_t numSpaceModes, const int64_t spaceModeExtents[], cudensitymatOperator_t *superoperator)¶

创建一个空的算符，它将是算符项的集合。

如果算符预计作用于纯量子态，则它只是一个常规算符，将从一侧作用于纯态向量。如果算符预计作用于混合量子态，则其作用可能会变得更复杂，它可能会作用于表示混合量子态的密度矩阵的两侧。在这种情况下，该算符专门称为超算符。但是，应该注意的是，在这两种情况下，它仍然是一个数学算符，只是作用于不同类型的数学向量。

注意

创建的算符将只能作用于驻留在与算符设置作用的相同空间中的量子态。

参数

handle – [in] 库句柄。
numSpaceModes – [in] 定义算符项将作用于其中的主/对偶张量积空间的模式（自由度）数量。
spaceModeExtents – [in] 定义算符项将作用于其中的主/对偶张量积空间的模式（自由度）范围。
superoperator – [out] 算符。

返回

cudensitymatStatus_t

`cudensitymatDestroyOperator`¶

cudensitymatStatus_t cudensitymatDestroyOperator(cudensitymatOperator_t superoperator)¶

销毁算符。

参数: superoperator – [in] 算符。
返回: cudensitymatStatus_t

`cudensitymatOperatorAppendTerm`¶

cudensitymatStatus_t cudensitymatOperatorAppendTerm(const cudensitymatHandle_t handle, cudensitymatOperator_t superoperator, cudensitymatOperatorTerm_t operatorTerm, int32_t duality, cuDoubleComplex coefficient, cudensitymatWrappedScalarCallback_t coefficientCallback)¶

将算符项附加到算符。

参数

handle – [in] 库句柄。
superoperator – [inout] 算符。
operatorTerm – [in] 算符项。
duality – [in] 整个算符项作用的对偶状态。如果非零，则将翻转算符项内部每个模式作用的对偶状态，即，从左侧的作用将替换为从右侧的作用，反之亦然。
coefficient – [in] 与算符项关联的常数复标量系数。
coefficientCallback – [in] 用户定义的复标量回调函数，稍后可以调用该函数以更新与算符项关联的标量系数，或 NULL。与算符项关联的总系数是常数系数和标量回调函数结果的乘积（如果已定义）。

返回

cudensitymatStatus_t

`cudensitymatOperatorPrepareAction`¶

cudensitymatStatus_t cudensitymatOperatorPrepareAction(const cudensitymatHandle_t handle, const cudensitymatOperator_t superoperator, const cudensitymatState_t stateIn, const cudensitymatState_t stateOut, cudensitymatComputeType_t computeType, size_t workspaceSizeLimit, cudensitymatWorkspaceDescriptor_t workspace, cudaStream_t stream)¶

准备算符以作用于量子态。

通常，在计算算符对特定量子态的作用之前，需要首先准备算符以进行计算，这是此 API 函数的目的。

注意

工作区描述符内返回的所需工作区缓冲区大小有时可能为零，在这种情况下，无需分配工作区缓冲区。

参数

handle – [in] 库句柄。
superoperator – [in] 算符。
stateIn – [in] 代表性的输入量子态，算符将作用于其上。计算期间作用的实际状态可能不同，但它必须具有相同的形状、种类和因子分解结构（拓扑、键维度等）。
stateOut – [in] 代表性的输出量子态，由算符对输入量子态的作用产生。计算期间作用的实际状态可能不同，但它必须具有相同的形状、种类和因子分解结构（拓扑、键维度等）。
computeType – [in] 期望的计算类型。
workspaceSizeLimit – [in] 工作区缓冲区大小限制（字节）。
workspace – [inout] 入口处的空工作区描述符。计算所需的工作区大小将在退出时设置。
stream – [输入] CUDA 流。

返回

cudensitymatStatus_t

`cudensitymatOperatorComputeAction`¶

cudensitymatStatus_t cudensitymatOperatorComputeAction(const cudensitymatHandle_t handle, const cudensitymatOperator_t superoperator, double time, int32_t numParams, const double params[], const cudensitymatState_t stateIn, cudensitymatState_t stateOut, cudensitymatWorkspaceDescriptor_t workspace, cudaStream_t stream)¶

计算算符对给定输入量子态的作用，并将结果累加到输出量子态中（累积作用）。

注意

提供的输入和输出量子态必须与先前准备阶段提供的量子态具有相同的种类、形状和结构。

警告

输出量子态不能与输入量子态相同。

参数

handle – [in] 库句柄。
superoperator – [in] 算符。
time – [in] 时间值。
numParams – [in] 用户定义的可变参数的数量。
params – [in] 用户定义的可变参数。
stateIn – [in] 输入量子态（或一批输入量子态）。
stateOut – [inout] 更新后的结果量子态，它累积了算符对输入量子态的作用。
workspace – [in] 已分配的工作区描述符。
stream – [输入] CUDA 流。

返回

cudensitymatStatus_t

`cudensitymatCreateOperatorAction`¶

cudensitymatStatus_t cudensitymatCreateOperatorAction(const cudensitymatHandle_t handle, int32_t numOperators, cudensitymatOperator_t operators[], cudensitymatOperatorAction_t *operatorAction)¶

为一个或多个算符创建操作描述符，从而定义算符对符合算符域的一组输入量子态的聚合操作，其中所有输入量子态也可以是批量的。

通常，仅指定算符本身不足以指定所需常微分方程 (ODE) 的右侧 (r.h.s.)，该方程定义了量子态随时间的演化。一般来说，ODE r.h.s. 规范需要指定一个或多个算符对一个或多个（批量）量子态（通常是密度矩阵）的作用。OperatorAction 的抽象正是为此目的服务。当计算聚合算符操作时，每个提供的算符将作用于其自身的输入量子态，从而对同一输出量子态产生贡献。

注意

有时，需要求解常微分方程的耦合系统，其中多个量子态同时随时间演化。在这种情况下，并非所有量子态都必须影响给定量子态的演化。为了处理这种情况，一些不贡献的算符-状态乘积可以通过将 operators[] 参数的相应条目设置为 NULL 来设置为零。

参数

handle – [in] 库句柄。
numOperators – [in] 涉及的算符数量（算符-状态乘积的数量）。
operators – [in] 具有相同作用域的组成算符。某些算符可以设置为 NULL，以表示对特定输入量子态的零作用。
operatorAction – [out] 算符操作。

返回

cudensitymatStatus_t

`cudensitymatDestroyOperatorAction`¶

cudensitymatStatus_t cudensitymatDestroyOperatorAction(cudensitymatOperatorAction_t operatorAction)¶

销毁算符操作描述符。

参数: operatorAction – [in] 算符操作。
返回: cudensitymatStatus_t

`cudensitymatOperatorActionPrepare`¶

cudensitymatStatus_t cudensitymatOperatorActionPrepare(const cudensitymatHandle_t handle, cudensitymatOperatorAction_t operatorAction, const cudensitymatState_t stateIn[], const cudensitymatState_t stateOut, cudensitymatComputeType_t computeType, size_t workspaceSizeLimit, cudensitymatWorkspaceDescriptor_t workspace, cudaStream_t stream)¶

准备（聚合）算符操作以进行计算。

一般来说，在计算特定量子态的（聚合）算符操作之前，需要首先准备好计算，这是此 API 函数的目的。

注意

工作区描述符内返回的所需工作区缓冲区大小有时可能为零，在这种情况下，无需分配工作区缓冲区。

参数

handle – [in] 库句柄。
operatorAction – [inout] 算符操作规范。
stateIn – [in] 定义当前算符操作的所有算符的输入量子态。每个输入量子态本身都可以是一批量子态（具有相同的批处理维度）。
stateOut – [in] 更新后的输出量子态（或批量），它累积了（聚合）算符对所有输入量子态的操作。
computeType – [in] 期望的计算类型。
workspaceSizeLimit – [in] 工作区缓冲区大小限制（字节）。
workspace – [inout] 入口处的空工作区描述符。计算所需的工作区大小将在退出时设置。
stream – [输入] CUDA 流。

返回

cudensitymatStatus_t

`cudensitymatOperatorActionCompute`¶

cudensitymatStatus_t cudensitymatOperatorActionCompute(const cudensitymatHandle_t handle, cudensitymatOperatorAction_t operatorAction, double time, int32_t numParams, const double params[], const cudensitymatState_t stateIn[], cudensitymatState_t stateOut, cudensitymatWorkspaceDescriptor_t workspace, cudaStream_t stream)¶

执行构成聚合算符操作的一个或多个算符对相同数量的输入量子态的操作，并将结果累加到单个输出量子态中。

注意

输出量子态不能是输入量子态之一。

参数

handle – [in] 库句柄。
operatorAction – [inout] 算符操作。
time – [in] 时间值。
numParams – [in] 用户定义的可变参数的数量。
params – [in] 用户定义的可变参数。
stateIn – [in] 输入量子态。一般来说，每个输入量子态都可以是一批量子态。
stateOut – [inout] 更新后的输出量子态，它累积了算符对所有输入量子态的操作。
workspace – [in] 已分配的工作区描述符。
stream – [输入] CUDA 流。

返回

cudensitymatStatus_t

算符期望值 API¶

`cudensitymatCreateExpectation`¶

cudensitymatStatus_t cudensitymatCreateExpectation(const cudensitymatHandle_t handle, cudensitymatOperator_t superoperator, cudensitymatExpectation_t *expectation)¶

创建算符期望值计算对象。

注意

非归一化的期望值将在计算期间产生。如果量子态未归一化，则需要额外计算状态范数或迹，以便获得归一化的算符期望值。

注意

在期望值对象的生命周期内，算符必须保持活动状态。

参数

handle – [in] 库句柄。
superoperator – [in] 算符。
expectation – [out] 期望值对象。

返回

cudensitymatStatus_t

`cudensitymatDestroyExpectation`¶

cudensitymatStatus_t cudensitymatDestroyExpectation(cudensitymatExpectation_t expectation)¶

销毁期望值对象。

参数: expectation – [in] 期望值对象。
返回: cudensitymatStatus_t

`cudensitymatExpectationPrepare`¶

cudensitymatStatus_t cudensitymatExpectationPrepare(const cudensitymatHandle_t handle, cudensitymatExpectation_t expectation, const cudensitymatState_t state, cudensitymatComputeType_t computeType, size_t workspaceSizeLimit, cudensitymatWorkspaceDescriptor_t workspace, cudaStream_t stream)¶

准备期望值对象以进行计算。

一般来说，在计算期望值之前，需要首先准备好计算，这是此 API 函数的目的。

注意

工作区描述符内返回的所需工作区缓冲区大小有时可能为零，在这种情况下，无需分配工作区缓冲区。

参数

handle – [in] 库句柄。
expectation – [inout] 期望值对象。
state – [输入] 量子态（或一批量子态）。
computeType – [in] 期望的计算类型。
workspaceSizeLimit – [in] 工作区缓冲区大小限制（字节）。
workspace – [inout] 入口处的空工作区描述符。计算所需的工作区大小将在退出时设置。
stream – [输入] CUDA 流。

返回

cudensitymatStatus_t

`cudensitymatExpectationCompute`¶

cudensitymatStatus_t cudensitymatExpectationCompute(const cudensitymatHandle_t handle, cudensitymatExpectation_t expectation, double time, int32_t numParams, const double params[], const cudensitymatState_t state, void *expectationValue, cudensitymatWorkspaceDescriptor_t workspace, cudaStream_t stream)¶

计算关于给定量子态的算符期望值。

结果通常是维度等于状态批次大小的向量。

参数

handle – [in] 库句柄。
expectation – [in] 期望值对象。
time – [in] 指定时间。
numParams – [in] 用户定义的可变参数的数量。
params – [in] 用户定义的可变参数。
state – [输入] 量子态（或一批量子态）。
expectationValue – [out] 指向 GPU 可访问 RAM 中期望值向量存储的指针，该存储的数据类型与状态和算符使用的数据类型相同。
workspace – [in] 已分配的工作区描述符。
stream – [输入] CUDA 流。

返回

cudensitymatStatus_t

cuDensityMat 函数¶

库上下文管理 API¶

cudensitymatCreate¶

cudensitymatDestroy¶

cudensitymatResetRandomSeed¶

分布式并行化 API¶

cudensitymatResetDistributedConfiguration¶

cudensitymatGetNumRanks¶

cudensitymatGetProcRank¶

工作区管理 API¶

cudensitymatCreateWorkspace¶

cudensitymatDestroyWorkspace¶

cudensitymatWorkspaceGetMemorySize¶

cudensitymatWorkspaceSetMemory¶

cudensitymatWorkspaceGetMemory¶

量子态 API¶

cudensitymatCreateState¶

cudensitymatDestroyState¶

cudensitymatStateGetNumComponents¶

cudensitymatStateGetComponentStorageSize¶

cudensitymatStateGetComponentNumModes¶

cudensitymatStateGetComponentInfo¶

cudensitymatStateAttachComponentStorage¶

cudensitymatStateInitializeZero¶

cudensitymatStateComputeScaling¶

cudensitymatStateComputeNorm¶

cudensitymatStateComputeTrace¶

cudensitymatStateComputeAccumulation¶

cudensitymatStateComputeInnerProduct¶

量子算符 API¶

cudensitymatCreateElementaryOperator¶

cudensitymatDestroyElementaryOperator¶

cudensitymatCreateOperatorTerm¶

cudensitymatDestroyOperatorTerm¶

cudensitymatOperatorTermAppendElementaryProduct¶

cudensitymatOperatorTermAppendGeneralProduct¶

cudensitymatCreateOperator¶

cudensitymatDestroyOperator¶

cudensitymatOperatorAppendTerm¶

cudensitymatOperatorPrepareAction¶

cudensitymatOperatorComputeAction¶

cudensitymatCreateOperatorAction¶

cudensitymatDestroyOperatorAction¶

cudensitymatOperatorActionPrepare¶

cudensitymatOperatorActionCompute¶

算符期望值 API¶

cudensitymatCreateExpectation¶

cudensitymatDestroyExpectation¶

cudensitymatExpectationPrepare¶

cudensitymatExpectationCompute¶

`cudensitymatCreate`¶

`cudensitymatDestroy`¶

`cudensitymatResetRandomSeed`¶

`cudensitymatResetDistributedConfiguration`¶

`cudensitymatGetNumRanks`¶

`cudensitymatGetProcRank`¶

`cudensitymatCreateWorkspace`¶

`cudensitymatDestroyWorkspace`¶

`cudensitymatWorkspaceGetMemorySize`¶

`cudensitymatWorkspaceSetMemory`¶

`cudensitymatWorkspaceGetMemory`¶

`cudensitymatCreateState`¶

`cudensitymatDestroyState`¶

`cudensitymatStateGetNumComponents`¶

`cudensitymatStateGetComponentStorageSize`¶

`cudensitymatStateGetComponentNumModes`¶

`cudensitymatStateGetComponentInfo`¶

`cudensitymatStateAttachComponentStorage`¶

`cudensitymatStateInitializeZero`¶

`cudensitymatStateComputeScaling`¶

`cudensitymatStateComputeNorm`¶

`cudensitymatStateComputeTrace`¶

`cudensitymatStateComputeAccumulation`¶

`cudensitymatStateComputeInnerProduct`¶

`cudensitymatCreateElementaryOperator`¶

`cudensitymatDestroyElementaryOperator`¶

`cudensitymatCreateOperatorTerm`¶

`cudensitymatDestroyOperatorTerm`¶

`cudensitymatOperatorTermAppendElementaryProduct`¶

`cudensitymatOperatorTermAppendGeneralProduct`¶

`cudensitymatCreateOperator`¶

`cudensitymatDestroyOperator`¶

`cudensitymatOperatorAppendTerm`¶

`cudensitymatOperatorPrepareAction`¶

`cudensitymatOperatorComputeAction`¶

`cudensitymatCreateOperatorAction`¶

`cudensitymatDestroyOperatorAction`¶

`cudensitymatOperatorActionPrepare`¶

`cudensitymatOperatorActionCompute`¶

`cudensitymatCreateExpectation`¶

`cudensitymatDestroyExpectation`¶

`cudensitymatExpectationPrepare`¶

`cudensitymatExpectationCompute`¶