cuquantum.cutensornet.experimental.NetworkState

class cuquantum.cutensornet.experimental.NetworkState(state_mode_extents, *, dtype='complex128', config=None, state_labels=None, options=None)

创建一个空的张量网络状态。

参数

• state_mode_extents – 一个整数序列，指定所有状态模式的范围。

• dtype –

  一个字符串，指定网络状态的数据类型，当前支持以下数据类型

  • 'float32'

  • 'float64'

  • 'complex64'

  • 'complex128' (默认)

• config –

  状态的模拟配置。可以是

  • 用于基于收缩的张量网络模拟的 TNConfig 对象（默认）。

  • 用于基于 MPS 的张量网络模拟的 MPSConfig 对象。

  • 一个 dict，包含 TNConfig 或 MPSConfig 构造函数的参数。

• state_labels – 可选，与每个状态维度对应的不同标签序列。如果提供，用户可以选择提供这些标签序列作为以下 API 的输入参数，包括 apply_tensor_operator()、apply_mpo()、compute_batched_amplitudes()、compute_reduced_density_matrix() 和 compute_sampling()。有关更多详细信息，请参阅每个 API 的文档字符串。

• options – 将状态计算的选项指定为 NetworkOptions 对象。或者，也可以提供一个 dict，其中包含 NetworkOptions 构造函数的参数。如果未指定，则值将设置为默认构造的 NetworkOptions 对象。

注释

• 目前 NetworkState 仅支持纯态表示。

• 如果用户希望使用与默认当前设备不同的设备，则必须通过 NetworkOptions.device_id 显式指定。

• 对于 MPS 模拟，目前仅支持开放边界条件。

示例

在此示例中，我们的目标是使用张量网络收缩方法直接对量子电路实例执行模拟。

>>> from cuquantum.cutensornet.experimental import NetworkState, TNConfig
>>> import cirq

定义一个随机 cirq.Circuit，请注意，使用相同的 API 调用也支持 qiskit.QuantumCircuit

>>> n_qubits = 4
>>> n_moments = 4
>>> op_density = 0.9
>>> circuit = cirq.testing.random_circuit(n_qubits, n_moments, op_density, random_state=2024)

使用张量网络收缩作为模拟方法

>>> config = TNConfig(num_hyper_samples=4)

通过 from_circuit() 方法创建网络状态对象

>>> state = NetworkState.from_circuit(circuit, dtype='complex128', backend='cupy', config=config)

计算位串 0000 的幅度

>>> amplitude = state.compute_amplitude('0000')

计算一系列具有系数的泡利串的期望值

>>> pauli_strings = {'IXIX': 0.4, 'IZIZ': 0.1}
>>> expec = state.compute_expectation(pauli_strings)

计算前两个量子比特的约化密度矩阵。由于后端指定为 cupy，因此返回的 rdm 操作数将是 cupy.ndarray。

>>> where = (0, 1)
>>> rdm = state.compute_reduced_density_matrix(where)
>>> print(f"RDM shape for {where}: {rdm.shape}")
RDM shape for (0, 1): (2, 2, 2, 2)

从状态中抽取 1000 个样本

>>> shots = 1000
>>> samples = state.compute_sampling(shots)

最后，释放网络状态资源。如果不进行此调用，可能会阻碍进一步的操作（特别是当网络状态很大时），因为内存只有在对象超出作用域时才会被释放。（为了避免必须显式进行此调用，建议将 NetworkState 对象用作上下文管理器。）

>>> state.free()

除了从电路实例初始化状态之外，用户还可以通过使用 apply_tensor_operator() 顺序应用张量算符和使用 apply_mpo() 或 apply_network_operator() 应用矩阵乘积算符 (MPO) 来构造状态。或者，模拟可以通过指定 options 作为 MPSConfig 实例来利用精确或近似矩阵乘积态 (MPS) 方法。更多详细示例可以在我们的 NetworkState 示例目录中找到。

方法

__init__(state_mode_extents, *, dtype='complex128', config=None, state_labels=None, options=None)

apply_mpo(modes, mpo_tensors, *, immutable=False, adjoint=False, unitary=False, stream=None)

将由 mpo_tensors 和 modes 指定的 MPO 算符应用于网络状态。

参数

• modes – 一个整数序列，指定 MPO 作用的每个模式。如果在初始化期间提供了 state_labels，则 modes 也可以作为标签序列提供。

• mpo_tensors – 每个 MPO 操作数的一系列张量（类 ndarray 对象）。当前支持的类型为 numpy.ndarray、cupy.ndarray 和 torch.Tensor。pknb 其中 p 表示连接到上一个 MPO 张量的模式，n 表示连接到下一个 MPO 张量的模式，k 表示 ket 模式，b 表示 bra 模式。请注意，目前仅支持具有开放边界条件的 MPO，因此 p 和 n 模式不应分别出现在第一个和最后一个 MPO 张量中。请注意，此处 bra 和 ket 模式的相对顺序与 apply_tensor_operator() 中的 operand 不同。

• immutable – 完整 MPO 是否不可变（默认为 False）。

• adjoint – 是否应以伴随形式应用完整 MPO（默认为 False）。

• unitary – 是否全 MPO 是酉矩阵（默认值 False）。

• stream – 提供 CUDA 流以用于追加 MPO（这用于在 CPU 上提供操作数时将其复制到 GPU）。可接受的输入包括 cudaStream_t （作为 Python int），cupy.cuda.Stream 和 torch.cuda.Stream。如果未提供流，则将使用当前流。

返回值

指定 MPO 位置的整数 network_id。

apply_network_operator(network_operator, *, immutable=False, adjoint=False, unitary=False)

将网络算符应用于网络状态。

参数

• network_operator – 输入网络算符的 NetworkOperator 对象。必须仅包含一个 MPO 项或一个张量积项。

• immutable – 网络算符是否为不可变的（默认值 False）。

• adjoint – 是否应以伴随形式应用网络算符（默认值 False）。

• unitary – 网络算符是否为酉矩阵（默认值 False）。

返回值

指定网络算符位置的整数 network_id。

apply_tensor_operator(modes, operand, *, control_modes=None, control_values=None, immutable=False, adjoint=False, unitary=False, stream=None)

将张量算符应用于网络状态。

参数

• modes – 表示张量算符作用的模式的整数序列。如果在初始化期间提供了 state_labels，则 modes 也可以作为标签序列提供。

• operand – 张量算符的类似 ndarray 的对象。操作数的模式应按 ABC...abc... 排序，其中 ABC... 表示输出 bra 模式，abc... 表示与 modes 对应的输入 ket 模式

• control_modes – 表示控制操作作用的模式的整数序列（默认值：无控制模式）。如果在初始化期间提供了 state_labels，则 control_modes 也可以作为标签序列提供。

• control_values – 指定与 control_modes 对应的控制值的整数序列。如果指定了 control_modes 但未提供 control_values，则所有控制模式的控制值都将设置为 1。

• immutable – 算符是否为不可变的（默认值 False）。

• adjoint – 是否应以伴随形式应用算符（默认值 False）。

• unitary – 算符是否为酉矩阵（默认值 False）。

• stream – 提供 CUDA 流以用于应用张量算符（这用于在 CPU 上提供操作数时将其复制到 GPU）。可接受的输入包括 cudaStream_t （作为 Python int），cupy.cuda.Stream 和 torch.cuda.Stream。如果未提供流，则将使用当前流。

返回值

指定输入算符位置的整数 tensor_id。

注释

• 对于 MPS 模拟，modes 的大小应限制为不大于 2（双体算符）。

• 对于受控张量算符，此方法目前仅支持不可变算符。

apply_unitary_tensor_channel(modes, operands, probabilities, *, stream=None)

将酉张量通道应用于网络状态。

参数

• modes – 表示张量算符作用的模式的整数序列。如果在初始化期间提供了 state_labels，则 modes 也可以作为标签序列提供。

• operands – 定义酉通道的酉张量算符的 ndarray 类对象序列。操作数的模式应按 ABC...abc... 排序，其中 ABC... 表示输出 bra 模式，abc... 表示与 modes 对应的输入 ket 模式

• probabilities – 表示每个操作数概率的正浮点数序列。

• stream – 提供 CUDA 流以用于应用张量算符（这用于在 CPU 上提供操作数时将其复制到 GPU）。可接受的输入包括 cudaStream_t （作为 Python int），cupy.cuda.Stream 和 torch.cuda.Stream。如果未提供流，则将使用当前流。

返回值

指定酉通道位置的整数 channel_id。

注释

• 对于 MPS 模拟，modes 的大小应限制为不大于 2（双体算符）。

compute_amplitude(bitstring, *, return_norm=False, stream=None, release_workspace=False)

计算位串的概率幅值。

参数

• bitstring – 指定所需测量状态维度的整数序列。

• return_norm – 如果为 true，还将返回状态的平方范数。

• stream – 提供用于计算的 CUDA 流。可接受的输入包括 cudaStream_t （作为 Python int），cupy.cuda.Stream 和 torch.cuda.Stream。如果未提供流，则将使用当前流。

• release_workspace – 值 True 指定状态对象应在函数返回时将工作区内存释放回包内存池，而值 False 指定状态对象应保留内存。如果应用程序在连续调用（相同或不同的）执行 API（例如 compute_sampling()、compute_reduced_density_matrix()、compute_amplitude()、compute_batched_amplitudes() 或 compute_expectation()）之间执行其他消耗大量内存的操作，则可以将此选项设置为 True，但这会因每次调用时从包内存池获取和释放工作区内存而产生少量开销。默认值为 False。

返回值

如果 return_norm 为 False，则为位串幅值的标量；否则，为包含位串幅值和状态平方范数（即 bra 和 ket 状态的内积）的标量的 2 元组。

compute_batched_amplitudes(fixed, *, return_norm=False, stream=None, release_workspace=False)

计算给定切片的批量幅值。

参数

• fixed – 将状态维度子集映射到相应固定状态的字典。如果在初始化期间提供了 state_labels，则 fixed 也可以作为将标签子集映射到相应固定状态的字典提供。

• return_norm – 如果为 true，还将返回状态的平方范数。

• stream – 提供用于计算的 CUDA 流。可接受的输入包括 cudaStream_t （作为 Python int），cupy.cuda.Stream 和 torch.cuda.Stream。如果未提供流，则将使用当前流。

• release_workspace – 值 True 指定状态对象应在函数返回时将工作区内存释放回包内存池，而值 False 指定状态对象应保留内存。如果应用程序在连续调用（相同或不同的）执行 API（例如 compute_sampling()、compute_reduced_density_matrix()、compute_amplitude()、compute_batched_amplitudes() 或 compute_expectation()）之间执行其他消耗大量内存的操作，则可以将此选项设置为 True，但这会因每次调用时从包内存池获取和释放工作区内存而产生少量开销。默认值为 False。

返回值

如果 return_norm 为 False，则为 ndarray 类对象作为批量幅值。ndarray 的包和存储位置将与 apply_tensor_operator()、apply_mpo() 和 set_initial_mps() 中提供的操作数相同；否则，为包含批量幅值和状态平方范数（即 bra 和 ket 状态的内积）的标量的 2 元组。

compute_expectation(operators, *, return_norm=False, stream=None, release_workspace=False)

计算给定张量网络算符的期望值（未归一化）。

参数

• operators –

  要在其上计算期望值的 NetworkOperator 算符对象。如果底层状态维度均为 2（量子比特），则它也可以是

  • 指定每个量子比特的泡利算符的单个泡利字符串。

  • 将每个单个泡利字符串映射到相应系数的字典。

• return_norm – 如果为 true，还将返回状态的平方范数。

• stream – 提供用于计算的 CUDA 流。可接受的输入包括 cudaStream_t （作为 Python int），cupy.cuda.Stream 和 torch.cuda.Stream。如果未提供流，则将使用当前流。

• release_workspace – 值 True 指定状态对象应在函数返回时将工作区内存释放回包内存池，而值 False 指定状态对象应保留内存。如果应用程序在连续调用（相同或不同的）执行 API（例如 compute_sampling()、compute_reduced_density_matrix()、compute_amplitude()、compute_batched_amplitudes() 或 compute_expectation()）之间执行其他消耗大量内存的操作，则可以将此选项设置为 True，但这会因每次调用时从包内存池获取和释放工作区内存而产生少量开销。默认值为 False。

返回值

如果 return_norm 为 False，则为总期望值的标量；否则，为包含总期望值和状态平方范数（即 bra 和 ket 状态的内积）的标量的 2 元组。

注意

• 如果用户希望对同一算符多次执行期望值计算，建议显式提供 NetworkOperator 对象以获得最佳性能。有关详细示例，请参阅 变分期望示例。

compute_output_state(*, stream=None, release_workspace=False, release_operators=False)

计算底层网络状态对象的最终输出状态。此方法目前仅对基于 MPS 的模拟有效。

参数

• stream – 提供用于计算的 CUDA 流。可接受的输入包括 cudaStream_t （作为 Python int），cupy.cuda.Stream 和 torch.cuda.Stream。如果未提供流，则将使用当前流。

• release_workspace – 值 True 指定状态对象应在函数返回时将工作区内存释放回包内存池，而值 False 指定状态对象应保留内存。如果应用程序在连续调用（相同或不同的）执行 API（例如 compute_sampling()、compute_reduced_density_matrix()、compute_amplitude()、compute_batched_amplitudes() 或 compute_expectation()）之间执行其他消耗大量内存的操作，则可以将此选项设置为 True，但这会因每次调用时从包内存池获取和释放工作区内存而产生少量开销。默认值为 False。

• release_operators – 值 True 将释放所有底层张量算符和 NetworkOperator 对象的引用。apply_tensor_operator()、apply_network_operator() 和 apply_mpo() 返回的先前 tensor_id 将无效。如果输出状态已被计算（这是其他 compute_xxx 方法的中间步骤），则输出状态将被缓存并直接返回。因此，传递 release_operators=True 可用于重置底层 NetworkState 对象。

返回值

当使用对象初始化期间的 options 参数指定 MPS 模拟时，将返回表示底层 MPS 状态的操作数序列。每个 MPS 操作数的模式应遵循 pkn 的顺序，其中 p 表示连接到先前 MPS 张量的模式，k 表示 ket 模式，n 表示连接到下一个 MPS 张量的模式。请注意，p 和 n 模式不应分别存在于第一个和最后一个 MPS 张量中。

compute_reduced_density_matrix(where, *, fixed=mappingproxy({}), stream=None, release_workspace=False)

计算给定边缘模式和固定模式的约化密度矩阵。

参数

• where – 目标模式的整数序列。如果在初始化期间提供了 state_labels，则 where 也可以作为标签序列提供。

• fixed – 将固定模式子集映射到固定值的字典。如果在初始化期间提供了 state_labels，则 fixed 也可以作为将标签映射到相应固定值的字典提供。

• stream – 提供用于计算的 CUDA 流。可接受的输入包括 cudaStream_t （作为 Python int），cupy.cuda.Stream 和 torch.cuda.Stream。如果未提供流，则将使用当前流。

• release_workspace – 值 True 指定状态对象应在函数返回时将工作区内存释放回包内存池，而值 False 指定状态对象应保留内存。如果应用程序在连续调用（相同或不同的）执行 API（例如 compute_sampling()、compute_reduced_density_matrix()、compute_amplitude()、compute_batched_amplitudes() 或 compute_expectation()）之间执行其他消耗大量内存的操作，则可以将此选项设置为 True，但这会因每次调用时从包内存池获取和释放工作区内存而产生少量开销。默认值为 False。

返回值

ndarray 类对象作为约化密度矩阵。张量将遵循 AB...ab... 的模式，其中 AB... 和 ab... 表示相应的输出和输入边缘模式。

compute_sampling(nshots, *, modes=None, seed=None, stream=None, release_workspace=False)

对给定模式执行采样。

参数

• nshots – 要收集的样本数。

• modes – 要采样的目标模式。如果未提供，将对所有模式进行采样。如果在初始化期间提供了 state_labels，则 modes 也可以作为标签序列提供。

• seed – 表示用于生成样本的随机种子的正整数。如果未提供，生成器将从先前的种子状态继续，如果先前未设置种子，则从未播种状态继续。

• stream – 提供用于计算的 CUDA 流。可接受的输入包括 cudaStream_t （作为 Python int），cupy.cuda.Stream 和 torch.cuda.Stream。如果未提供流，则将使用当前流。

• release_workspace – 值 True 指定状态对象应在函数返回时将工作区内存释放回包内存池，而值 False 指定状态对象应保留内存。如果应用程序在连续调用（相同或不同的）执行 API（例如 compute_sampling()、compute_reduced_density_matrix()、compute_amplitude()、compute_batched_amplitudes() 或 compute_expectation()）之间执行其他消耗大量内存的操作，则可以将此选项设置为 True，但这会因每次调用时从包内存池获取和释放工作区内存而产生少量开销。默认值为 False。

返回值

将位串映射到相应计数的字典。

compute_state_vector(*, return_norm=False, stream=None, release_workspace=False)

计算状态向量。

参数

• return_norm – 如果为 true，还将返回状态的平方范数。

• stream – 提供用于计算的 CUDA 流。可接受的输入包括 cudaStream_t （作为 Python int），cupy.cuda.Stream 和 torch.cuda.Stream。如果未提供流，则将使用当前流。

• release_workspace – 值 True 指定状态对象应在函数返回时将工作区内存释放回包内存池，而值 False 指定状态对象应保留内存。如果应用程序在连续调用（相同或不同的）执行 API（例如 compute_sampling()、compute_reduced_density_matrix()、compute_amplitude()、compute_batched_amplitudes() 或 compute_expectation()）之间执行其他消耗大量内存的操作，则可以将此选项设置为 True，但这会因每次调用时从包内存池获取和释放工作区内存而产生少量开销。默认值为 False。

返回值

如果 return_norm 为 False，则为 ndarray 类对象作为状态向量。ndarray 的包和存储位置将与 apply_tensor_operator()、apply_mpo() 和 set_initial_mps() 中提供的操作数相同；否则，为包含状态向量和状态平方范数（即 bra 和 ket 状态的内积）的标量的 2 元组。

free()

释放状态资源。

建议 NetworkState 对象可以在上下文中使用，但如果不可能，则必须显式调用此方法以确保正确清理状态资源。

classmethod from_circuit(circuit, *, dtype='complex128', backend='cupy', config=None, options=None, stream=None)

从给定电路创建状态对象。

参数

• circuit – 完全参数化的 cirq.Circuit 或 qiskit.QuantumCircuit 对象。

• dtype –

  一个字符串，指定张量网络的数据类型，目前支持以下数据类型

  • 'complex64'

  • 'complex128' (默认)

• backend – 所有输出张量操作数的后端。如果未指定，则使用 cupy。

• config –

  状态的模拟配置。可以是

  • 用于基于收缩的张量网络模拟的 TNConfig 对象（默认）。

  • 用于基于 MPS 的张量网络模拟的 MPSConfig 对象。

  • 一个 dict，包含 TNConfig 或 MPSConfig 构造函数的参数。

• options – 指定计算的选项，以 NetworkOptions 对象的形式。或者，也可以提供一个 dict，其中包含 NetworkOptions 构造函数的参数。如果未指定，则该值将设置为默认构造的 NetworkOptions 对象。

• stream – 提供 CUDA 流，用于状态初始化，这对于流顺序操作（如分配内存）是必需的。可接受的输入包括 cudaStream_t (作为 Python int), cupy.cuda.Stream, 和 torch.cuda.Stream。如果未提供流，将使用当前流。

注意

• 当从电路对象解析门时，所有门操作数都假定为酉矩阵。在目标电路对象包含自定义的非酉矩阵门的罕见情况下，建议用户使用 apply_tensor_operator() 来构造 NetworkState 对象。

classmethod from_converter(converter, *, config=None, options=None, stream=None)

从给定的 cuquantum.CircuitToEinsum 转换器创建一个 NetworkState 对象。

参数

• converter – 一个 cuquantum.CircuitToEinsum 对象。

• config –

  状态模拟器的模拟配置。它可以是

  • 用于基于收缩的张量网络模拟的 TNConfig 对象（默认）。

  • 用于基于 MPS 的张量网络模拟的 MPSConfig 对象。

  • 一个 dict，包含 TNConfig 或 MPSConfig 构造函数的参数。

• options – 将状态计算的选项指定为 NetworkOptions 对象。或者，也可以提供一个 dict，其中包含 NetworkOptions 构造函数的参数。如果未指定，则值将设置为默认构造的 NetworkOptions 对象。

• stream – 提供 CUDA 流，用于状态初始化，这对于流顺序操作（如分配内存）是必需的。可接受的输入包括 cudaStream_t (作为 Python int), cupy.cuda.Stream, 和 torch.cuda.Stream。如果未提供流，将使用当前流。

set_initial_mps(mps_tensors, *, stream=None)

将初始状态设置为 MPS 形式的非真空态。

参数

• mps_tensors – 每个 MPS 操作数的一系列张量（类似 ndarray 的对象）。当前支持的类型包括 numpy.ndarray, cupy.ndarray, 和 torch.Tensor。每个操作数的模式预计遵循 pkn 的顺序，其中 p 表示连接到前一个 MPS 张量的模式，k 表示 ket 模式，而 n 表示连接到下一个 MPS 张量的模式。请注意，此方法目前仅支持开放边界条件，因此应分别在第一个和最后一个 MPS 张量中删除 p 和 n 模式。

• stream – 提供 CUDA 流，用于将初始状态设置为指定的 MPS（这用于在操作数在 CPU 上提供时将其复制到 GPU）。可接受的输入包括 cudaStream_t (作为 Python int), cupy.cuda.Stream, 和 torch.cuda.Stream。如果未提供流，将使用当前流。

注意

• 此 API 仅将初始状态设置为提供的 MPS，不会改变模拟方法的性质，模拟方法的性质通过初始化期间的 options 参数提供。

update_tensor_operator(tensor_id, operand, *, unitary=False, stream=None)

更新状态中的张量算符。

参数

• tensor_id – 一个整数，用于指定在 NetworkState.apply_tensor_operator() 中分配的张量 ID。

• operand – 张量算符的类似 ndarray 的对象。操作数应遵循与原始操作数相同的模式顺序、数据类型和步幅。

• unitary – 算符是否为酉矩阵（默认值 False）。

• stream – 提供 CUDA 流，用于更新张量操作数（这用于在操作数在 CPU 上提供时将其复制到 GPU）。可接受的输入包括 cudaStream_t (作为 Python int), cupy.cuda.Stream, 和 torch.cuda.Stream。如果未提供流，将使用当前流。