梯度结果类
这些类保存由 VQCircuit.get_gradients 和 VQCircuit.get_gradients_and_expectation 执行的梯度和期望值计算结果。它们提供对梯度值的索引访问和批量访问，以及在适用情况下对期望值的访问。
ResGradients
ResGradients 存储为单组参数计算的梯度值。当变分量子线路使用一组参数值 [val_0, val_1, ..., val_n] 时，此对象保存对应的梯度值 [gradient_0, gradient_1, ..., gradient_n]，其中 gradient_i 是期望值对 val_i 的导数。
方法
at（按扁平索引）
返回与给定扁平索引处参数对应的梯度值。
res.at(idx: int) -> float| 参数 | 类型 | 描述 |
|---|---|---|
| idx | int | 参数数组的扁平索引 i。返回的梯度对应于 val_i。 |
返回值： float -- 梯度值。
at（按多维索引）
返回参数数组中特定多维位置的梯度值。
res.at(idx_s: list[int]) -> float| 参数 | 类型 | 描述 |
|---|---|---|
| idx_s | list[int] | 多维索引 [idx_dim0, idx_dim1, ..., idx_dimN]，与 VQCircuit.set_Param 设置的形状匹配。 |
返回值： float -- 指定位置的梯度值。
gradients
以扁平列表形式返回所有梯度值。
res.gradients() -> list[float]返回值： list[float] -- 所有梯度值，形式为 [gradient_0, gradient_1, ..., gradient_n]。
__len__
返回梯度值的数量，等于参数的数量。
len(res) -> int返回值： int -- 梯度值的总数。
__str__
返回所有梯度值及其多维索引的可读字符串表示。
ResNGradients
ResNGradients 存储 N 组参数的梯度值。当向 VQCircuit.get_gradients 提供 N 组参数值时，此对象保存 N 组梯度值。
方法
at
以 ResGradients 对象的形式返回给定索引处组的梯度值。
res.at(idx: int) -> ResGradients| 参数 | 类型 | 描述 |
|---|---|---|
| idx | int | 参数组的索引（从 0 开始）。 |
返回值： ResGradients -- 指定组的梯度值。
data
以嵌套列表形式返回所有梯度数据。
res.data() -> list[list[float]]返回值： list[list[float]] -- 一个列表，其中每个元素是对应一个参数组的梯度值列表。
__len__
返回参数组的总数（N）。
len(res) -> int返回值： int -- 梯度组的数量。
__str__
返回所有梯度组的可读字符串表示。
ResGradientsAndExpectation
ResGradientsAndExpectation 存储为单组参数计算的梯度值和期望值。它对应于使用单个参数组调用 VQCircuit.get_gradients_and_expectation 的结果。
方法
expectation_val
返回期望值。
res.expectation_val() -> float返回值： float -- 给定参数下哈密顿量的期望值。
gradients
以扁平列表形式返回所有梯度值。
res.gradients() -> list[float]返回值： list[float] -- 所有梯度值 [gradient_0, gradient_1, ..., gradient_n]。
at（按扁平索引）
返回给定扁平索引处的梯度值。
res.at(idx: int) -> float| 参数 | 类型 | 描述 |
|---|---|---|
| idx | int | 参数数组的扁平索引。 |
返回值： float -- 梯度值。
at（按多维索引）
返回给定多维位置处的梯度值。
res.at(idx_s: list[int]) -> float| 参数 | 类型 | 描述 |
|---|---|---|
| idx_s | list[int] | 多维索引。 |
返回值： float -- 梯度值。
data
以元组形式返回期望值和梯度值。
res.data() -> tuple[float, list[float]]返回值： tuple[float, list[float]] -- 第一个元素是期望值，第二个是梯度值列表。
__str__
返回期望值和所有梯度的可读字符串表示。
ResNResGradientsAndExpectation
ResNResGradientsAndExpectation 存储 N 组参数的梯度值和期望值。当指定 param_group_total 时，由 VQCircuit.get_gradients_and_expectation 返回。
方法
at
以 ResGradientsAndExpectation 对象的形式返回给定索引处组的梯度和期望数据。
res.at(idx: int) -> ResGradientsAndExpectation| 参数 | 类型 | 描述 |
|---|---|---|
| idx | int | 参数组的索引（从 0 开始）。 |
返回值： ResGradientsAndExpectation -- 指定组的梯度和期望数据。
data
以元组列表形式返回所有数据。
res.data() -> list[tuple[float, list[float]]]返回值： list[tuple[float, list[float]]] -- 一个列表，其中每个元素是一个元组。每个元组的第一个元素是期望值，第二个是该参数组的梯度值列表。
__len__
返回参数组的总数（N）。
len(res) -> int返回值： int -- 梯度和期望组的数量。
__str__
返回所有组的可读字符串表示。
示例
import numpy as np
from pyqpanda3.vqcircuit import VQCircuit, DiffMethod
from pyqpanda3.hamiltonian import Hamiltonian
vqc = VQCircuit()
# ... 构建 ansatz ...
params = np.array([0.1, 0.2, 0.3, 0.4])
hamiltonian = Hamiltonian(...)
# 单组梯度
grads = vqc.get_gradients(params, hamiltonian, DiffMethod.ADJOINT_DIFF)
print(len(grads)) # 4
print(grads.at(0)) # 对第一个参数的梯度
print(grads.gradients()) # [g0, g1, g2, g3]
# 单组梯度 + 期望值
res = vqc.get_gradients_and_expectation(params, hamiltonian, DiffMethod.ADJOINT_DIFF)
print(res.expectation_val()) # 例如 -0.5234
print(res.gradients()) # [g0, g1, g2, g3]
exp_val, grad_list = res.data()
# 多组梯度（2 组，每组 4 个参数）
params_2 = np.array([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8])
grads_n = vqc.get_gradients(params_2, hamiltonian, 2, DiffMethod.ADJOINT_DIFF)
print(len(grads_n)) # 2
print(grads_n.at(0).gradients()) # 第一组的梯度
print(grads_n.data()) # [[g0,g1,g2,g3], [g4,g5,g6,g7]]