Gradient Result Classes
These classes hold the results of gradient and expectation value computations performed by VQCircuit.get_gradients and VQCircuit.get_gradients_and_expectation. They provide indexed and bulk access to gradient values and, where applicable, expectation values.
ResGradients
ResGradients stores the gradient values computed for a single group of parameters. When a variational quantum circuit uses one set of parameter values [val_0, val_1, ..., val_n], this object holds the corresponding gradient values [gradient_0, gradient_1, ..., gradient_n], where gradient_i is the derivative of the expectation value with respect to val_i.
Methods
at (by flat index)
Returns the gradient value corresponding to the parameter at the given flat index.
res.at(idx: int) -> float| Parameter | Type | Description |
|---|---|---|
| idx | int | Flat index i into the parameter array. The returned gradient corresponds to val_i. |
Returns: float -- the gradient value.
at (by multi-dimensional index)
Returns the gradient value at a specific multi-dimensional position in the parameter array.
res.at(idx_s: list[int]) -> float| Parameter | Type | Description |
|---|---|---|
| idx_s | list[int] | Multi-dimensional index [idx_dim0, idx_dim1, ..., idx_dimN], matching the shape set by VQCircuit.set_Param. |
Returns: float -- the gradient value at the specified position.
gradients
Returns all gradient values as a flat list.
res.gradients() -> list[float]Returns: list[float] -- all gradient values in the form [gradient_0, gradient_1, ..., gradient_n].
__len__
Returns the number of gradient values, which equals the number of parameters.
len(res) -> intReturns: int -- the total number of gradient values.
__str__
Returns a human-readable string representation of all gradient values with their multi-dimensional indices.
ResNGradients
ResNGradients stores gradient values for N groups of parameters. When N groups of parameter values are provided to VQCircuit.get_gradients, this object holds N groups of gradient values.
Methods
at
Returns the gradient values for the group at the given index as a ResGradients object.
res.at(idx: int) -> ResGradients| Parameter | Type | Description |
|---|---|---|
| idx | int | Index of the parameter group (0-based). |
Returns: ResGradients -- the gradient values for the specified group.
data
Returns all gradient data as nested lists of built-in types.
res.data() -> list[list[float]]Returns: list[list[float]] -- a list where each element is a list of gradient values corresponding to one parameter group.
__len__
Returns the total number of parameter groups (N).
len(res) -> intReturns: int -- the number of gradient groups.
__str__
Returns a human-readable string representation of all gradient groups.
ResGradientsAndExpectation
ResGradientsAndExpectation stores both gradient values and an expectation value computed for a single group of parameters. It corresponds to one call of VQCircuit.get_gradients_and_expectation with a single parameter group.
Methods
expectation_val
Returns the expectation value.
res.expectation_val() -> floatReturns: float -- the expectation value of the Hamiltonian under the given parameters.
gradients
Returns all gradient values as a flat list.
res.gradients() -> list[float]Returns: list[float] -- all gradient values [gradient_0, gradient_1, ..., gradient_n].
at (by flat index)
Returns the gradient value at the given flat index.
res.at(idx: int) -> float| Parameter | Type | Description |
|---|---|---|
| idx | int | Flat index into the parameter array. |
Returns: float -- the gradient value.
at (by multi-dimensional index)
Returns the gradient value at the given multi-dimensional position.
res.at(idx_s: list[int]) -> float| Parameter | Type | Description |
|---|---|---|
| idx_s | list[int] | Multi-dimensional index. |
Returns: float -- the gradient value.
data
Returns the expectation value and gradient values as a tuple of built-in types.
res.data() -> tuple[float, list[float]]Returns: tuple[float, list[float]] -- the first element is the expectation value, the second is the list of gradient values.
__str__
Returns a human-readable string representation of the expectation value and all gradients.
ResNResGradientsAndExpectation
ResNResGradientsAndExpectation stores gradient values and expectation values for N groups of parameters. It is returned by VQCircuit.get_gradients_and_expectation when param_group_total is specified.
Methods
at
Returns the gradient and expectation data for the group at the given index as a ResGradientsAndExpectation object.
res.at(idx: int) -> ResGradientsAndExpectation| Parameter | Type | Description |
|---|---|---|
| idx | int | Index of the parameter group (0-based). |
Returns: ResGradientsAndExpectation -- the gradient and expectation data for the specified group.
data
Returns all data as a list of tuples of built-in types.
res.data() -> list[tuple[float, list[float]]]Returns: list[tuple[float, list[float]]] -- a list where each element is a tuple. The first element of each tuple is the expectation value, and the second is the list of gradient values for that parameter group.
__len__
Returns the total number of parameter groups (N).
len(res) -> intReturns: int -- the number of gradient-and-expectation groups.
__str__
Returns a human-readable string representation of all groups.
Example
import numpy as np
from pyqpanda3.vqcircuit import VQCircuit, DiffMethod
from pyqpanda3.hamiltonian import Hamiltonian
vqc = VQCircuit()
# ... build ansatz ...
params = np.array([0.1, 0.2, 0.3, 0.4])
hamiltonian = Hamiltonian(...)
# Single-group gradients
grads = vqc.get_gradients(params, hamiltonian, DiffMethod.ADJOINT_DIFF)
print(len(grads)) # 4
print(grads.at(0)) # gradient w.r.t. first parameter
print(grads.gradients()) # [g0, g1, g2, g3]
# Single-group gradients + expectation
res = vqc.get_gradients_and_expectation(params, hamiltonian, DiffMethod.ADJOINT_DIFF)
print(res.expectation_val()) # e.g. -0.5234
print(res.gradients()) # [g0, g1, g2, g3]
exp_val, grad_list = res.data()
# Multi-group gradients (2 groups of 4 parameters each)
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()) # gradients for first group
print(grads_n.data()) # [[g0,g1,g2,g3], [g4,g5,g6,g7]]See Also
- VQCircuit -- the class that produces these gradient results
- DiffMethod -- available differentiation methods
- Parameter -- parameter placeholder system