Gradients with the primitives

qiskit/algorithms/gradients/base_estimator_gradient.py

@@ -11,7 +11,7 @@
 # that they have been altered from the originals.
 
 """
-Abstract Base class of Gradient for Estimator.
+Abstract base class of gradient for ``Estimator``.
 """
 
 from __future__ import annotations
@@ -30,7 +30,7 @@
 
 
 class BaseEstimatorGradient(ABC):
-    """Base class for an EstimatorGradient to compute the gradients of the expectation value."""
+    """Base class for an ``EstimatorGradient`` to compute the gradients of the expectation value."""
 
     def __init__(
         self,
@@ -45,7 +45,7 @@ def __init__(
                 setting. Higher priority setting overrides lower priority setting.
 
         Raises:
-            ValueError: If the estimator is not an instance of BaseEstimator.
+            ValueError: If the estimator is not an instance of ``BaseEstimator``.
         """
         if not isinstance(estimator, BaseEstimator):
             raise ValueError(
@@ -68,8 +68,8 @@ def run(
             circuits: The list of quantum circuits to compute the gradients.
             observables: The list of observables.
             parameter_values: The list of parameter values to be bound to the circuit.
-            parameters: The Sequence of Sequence of Parameters to calculate only the gradients of
-                the specified parameters. Each Sequence of Parameters corresponds to a circuit in
+            parameters: The sequence of parameters to calculate only the gradients of
+                the specified parameters. Each sequence of parameters corresponds to a circuit in
                 ``circuits``. Defaults to None, which means that the gradients of all parameters in
                 each circuit are calculated.
             run_options: Backend runtime options used for circuit execution. The order of priority is:

qiskit/algorithms/gradients/base_sampler_gradient.py

@@ -11,7 +11,7 @@
 # that they have been altered from the originals.
 
 """
-Abstract Base class of Gradient for Sampler.
+Abstract base class of gradient for ``Sampler``.
 """
 
 from __future__ import annotations
@@ -27,7 +27,7 @@
 
 
 class BaseSamplerGradient(ABC):
-    """Base class for a SamplerGradient to compute the gradients of the sampling probability."""
+    """Base class for a ``SamplerGradient`` to compute the gradients of the sampling probability."""
 
     def __init__(self, sampler: BaseSampler, **run_options):
         """
@@ -38,7 +38,7 @@ def __init__(self, sampler: BaseSampler, **run_options):
                 setting. Higher priority setting overrides lower priority setting.
 
         Raises:
-            ValueError: If the sampler is not an instance of BaseEstimator.
+            ValueError: If the sampler is not an instance of ``BaseSampler``.
         """
         if not isinstance(sampler, BaseSampler):
             raise ValueError(
@@ -59,8 +59,8 @@ def run(
         Args:
             circuits: The list of quantum circuits to compute the gradients.
             parameter_values: The list of parameter values to be bound to the circuit.
-            parameters: The Sequence of Sequence of Parameters to calculate only the gradients of
-                the specified parameters. Each Sequence of Parameters corresponds to a circuit in
+            parameters: The sequence of parameters to calculate only the gradients of
+                the specified parameters. Each sequence of parameters corresponds to a circuit in
                 ``circuits``. Defaults to None, which means that the gradients of all parameters in
                 each circuit are calculated.
             run_options: Backend runtime options used for circuit execution. The order of priority is:
@@ -105,7 +105,7 @@ def _validate_arguments(
         circuits: Sequence[QuantumCircuit],
         parameter_values: Sequence[Sequence[float]],
         parameters: Sequence[Sequence[Parameter] | None] | None = None,
-    ):
+    ) -> None:
         """Validate the arguments of the ``run`` method.
 
         Args:

qiskit/algorithms/gradients/estimator_gradient_result.py

@@ -23,15 +23,12 @@
 
 @dataclass(frozen=True)
 class EstimatorGradientResult:
-    """Result of EstimatorGradient.
-
-    Args:
-        gradients: The gradients of the expectation values.
-        metadata: Additional information about the job.
-        run_options: run_options for the estimator. Currently, estimator's default run_options is not
-        included.
-    """
+    """Result of EstimatorGradient."""
 
     gradients: list[np.ndarray]
+    """The gradients of the expectation values."""
     metadata: list[dict[str, Any]]
+    """Additional information about the job."""
     run_options: dict[str, Any]
+    """run_options for the estimator. Currently, estimator's default run_options is not
+        included."""

qiskit/algorithms/gradients/finite_diff_estimator_gradient.py

@@ -19,8 +19,10 @@
 import numpy as np
 
 from qiskit.circuit import Parameter, QuantumCircuit
+from qiskit.exceptions import QiskitError
 from qiskit.opflow import PauliSumOp
 from qiskit.primitives import BaseEstimator
+from qiskit.providers import JobStatus
 from qiskit.quantum_info.operators.base_operator import BaseOperator
 
 from .base_estimator_gradient import BaseEstimatorGradient
@@ -42,10 +44,10 @@ def __init__(self, estimator: BaseEstimator, epsilon: float, **run_options):
                 setting. Higher priority setting overrides lower priority setting.
 
         Raises:
-            ValueError: If ``epsilon`` is not float.
+            ValueError: If ``epsilon`` is not positive.
         """
-        if not isinstance(epsilon, float):
-            raise ValueError(f"epsilon must be a float, but got {type(epsilon)} instead.")
+        if epsilon <= 0:
+            raise ValueError(f"epsilon ({epsilon}) should be positive.")
         self._epsilon = epsilon
         self._base_parameter_values_dict = {}
         super().__init__(estimator, **run_options)
@@ -81,6 +83,9 @@ def _run(
             jobs.append(job)
 
         # combine the results
+        if any(job.status() is not JobStatus.DONE for job in jobs):
+            raise QiskitError("The gradient job was not completed successfully. ")
+
         results = [job.result() for job in jobs]
         gradients = []
         for result in results:

qiskit/algorithms/gradients/finite_diff_sampler_gradient.py

@@ -19,7 +19,9 @@
 import numpy as np
 
 from qiskit.circuit import Parameter, QuantumCircuit
+from qiskit.exceptions import QiskitError
 from qiskit.primitives import BaseSampler
+from qiskit.providers import JobStatus
 
 from .base_sampler_gradient import BaseSamplerGradient
 from .sampler_gradient_result import SamplerGradientResult
@@ -43,10 +45,10 @@ def __init__(
                 setting. Higher priority setting overrides lower priority setting.
 
         Raises:
-            ValueError: If ``epsilon`` is not float.
+            ValueError: If ``epsilon`` is not positive.
         """
-        if not isinstance(epsilon, float):
-            raise ValueError(f"epsilon must be a float, but got {type(epsilon)} instead.")
+        if epsilon <= 0:
+            raise ValueError(f"epsilon ({epsilon}) should be positive.")
         self._epsilon = epsilon
         super().__init__(sampler, **run_options)
 
@@ -74,6 +76,8 @@ def _run(
             jobs.append(job)
 
         # combine the results
+        if any(job.status() is not JobStatus.DONE for job in jobs):
+            raise QiskitError("The gradient job was not completed successfully. ")
         results = [job.result() for job in jobs]
         gradients = []
         for i, result in enumerate(results):

qiskit/algorithms/gradients/lin_comb_estimator_gradient.py

@@ -20,14 +20,18 @@
 import numpy as np
 
 from qiskit.circuit import Parameter, ParameterExpression, QuantumCircuit
+from qiskit.exceptions import QiskitError
 from qiskit.opflow import PauliSumOp
 from qiskit.primitives import BaseEstimator
+from qiskit.primitives.utils import init_observable
+from qiskit.providers import JobStatus
 from qiskit.quantum_info import Pauli
 from qiskit.quantum_info.operators.base_operator import BaseOperator
 
 from .base_estimator_gradient import BaseEstimatorGradient
 from .estimator_gradient_result import EstimatorGradientResult
-from .utils import make_lin_comb_gradient_circuit
+from .utils import _make_lin_comb_gradient_circuit
+
 
 Pauli_Z = Pauli("Z")
 
@@ -65,6 +69,8 @@ def _run(
         for circuit, observable, parameter_values_, parameters_ in zip(
             circuits, observables, parameter_values, parameters
         ):
+            # Make the observable as observable as :class:`~qiskit.quantum_info.SparsePauliOp`.
+            observables = init_observable(observable)
             # a set of parameters to be differentiated
             if parameters_ is None:
                 param_set = set(circuit.parameters)
@@ -76,7 +82,7 @@ def _run(
             observable_ = observable.expand(Pauli_Z)
             gradient_circuits_ = self._gradient_circuits.get(id(circuit))
             if gradient_circuits_ is None:
-                gradient_circuits_ = make_lin_comb_gradient_circuit(circuit)
+                gradient_circuits_ = _make_lin_comb_gradient_circuit(circuit)
                 self._gradient_circuits[id(circuit)] = gradient_circuits_
 
             # only compute the gradients for parameters in the parameter set
@@ -112,6 +118,8 @@ def _run(
             coeffs_all.append(coeffs)
 
         # combine the results
+        if any(job.status() is not JobStatus.DONE for job in jobs):
+            raise QiskitError("The gradient job was not completed successfully. ")
         results = [job.result() for job in jobs]
         gradients = []
         for i, result in enumerate(results):

qiskit/algorithms/gradients/lin_comb_sampler_gradient.py

@@ -20,11 +20,13 @@
 import numpy as np
 
 from qiskit.circuit import Parameter, ParameterExpression, QuantumCircuit
+from qiskit.exceptions import QiskitError
 from qiskit.primitives import BaseSampler
+from qiskit.providers import JobStatus
 
 from .base_sampler_gradient import BaseSamplerGradient
 from .sampler_gradient_result import SamplerGradientResult
-from .utils import make_lin_comb_gradient_circuit
+from .utils import _make_lin_comb_gradient_circuit
 
 
 class LinCombSamplerGradient(BaseSamplerGradient):
@@ -68,7 +70,7 @@ def _run(
             # TODO: support measurement in different basis (Y and Z+iY)
             gradient_circuits_ = self._gradient_circuits.get(id(circuit))
             if gradient_circuits_ is None:
-                gradient_circuits_ = make_lin_comb_gradient_circuit(circuit, add_measurement=True)
+                gradient_circuits_ = _make_lin_comb_gradient_circuit(circuit, add_measurement=True)
                 self._gradient_circuits[id(circuit)] = gradient_circuits_
 
             # only compute the gradients for parameters in the parameter set
@@ -101,6 +103,8 @@ def _run(
             coeffs_all.append(coeffs)
 
         # combine the results
+        if any(job.status() is not JobStatus.DONE for job in jobs):
+            raise QiskitError("The gradient job was not completed successfully. ")
         results = [job.result() for job in jobs]
         gradients = []
         for i, result in enumerate(results):

qiskit/algorithms/gradients/param_shift_estimator_gradient.py

@@ -20,14 +20,16 @@
 import numpy as np
 
 from qiskit.circuit import Parameter, QuantumCircuit
+from qiskit.exceptions import QiskitError
 from qiskit.opflow import PauliSumOp
 from qiskit.primitives import BaseEstimator
+from qiskit.providers import JobStatus
 from qiskit.quantum_info.operators.base_operator import BaseOperator
 
 from .base_estimator_gradient import BaseEstimatorGradient
 from .estimator_gradient_result import EstimatorGradientResult
 
-from .utils import param_shift_preprocessing, make_param_shift_parameter_values
+from .utils import _param_shift_preprocessing, _make_param_shift_parameter_values
 
 
 class ParamShiftEstimatorGradient(BaseEstimatorGradient):
@@ -67,7 +69,7 @@ def _run(
             if self._gradient_circuits.get(id(circuit)):
                 gradient_circuit, base_parameter_values_all = self._gradient_circuits[id(circuit)]
             else:
-                gradient_circuit, base_parameter_values_all = param_shift_preprocessing(circuit)
+                gradient_circuit, base_parameter_values_all = _param_shift_preprocessing(circuit)
                 self._gradient_circuits[id(circuit)] = (
                     gradient_circuit,
                     base_parameter_values_all,
@@ -78,7 +80,7 @@ def _run(
                 gradient_parameter_values_minus,
                 result_indices,
                 coeffs,
-            ) = make_param_shift_parameter_values(
+            ) = _make_param_shift_parameter_values(
                 gradient_circuit_data=gradient_circuit,
                 base_parameter_values=base_parameter_values_all,
                 parameter_values=parameter_values_,
@@ -96,6 +98,8 @@ def _run(
             coeffs_all.append(coeffs)
 
         # combine the results
+        if any(job.status() is not JobStatus.DONE for job in jobs):
+            raise QiskitError("The gradient job was not completed successfully. ")
         results = [job.result() for job in jobs]
         gradients = []
         for i, result in enumerate(results):

qiskit/algorithms/gradients/param_shift_sampler_gradient.py

@@ -20,11 +20,13 @@
 import numpy as np
 
 from qiskit.circuit import Parameter, QuantumCircuit
+from qiskit.exceptions import QiskitError
 from qiskit.primitives import BaseSampler
+from qiskit.providers import JobStatus
 
 from .base_sampler_gradient import BaseSamplerGradient
 from .sampler_gradient_result import SamplerGradientResult
-from .utils import param_shift_preprocessing, make_param_shift_parameter_values
+from .utils import _param_shift_preprocessing, _make_param_shift_parameter_values
 
 
 class ParamShiftSamplerGradient(BaseSamplerGradient):
@@ -61,7 +63,7 @@ def _run(
             if self._gradient_circuits.get(id(circuit)):
                 gradient_circuit, base_parameter_values_all = self._gradient_circuits[id(circuit)]
             else:
-                gradient_circuit, base_parameter_values_all = param_shift_preprocessing(circuit)
+                gradient_circuit, base_parameter_values_all = _param_shift_preprocessing(circuit)
                 self._gradient_circuits[id(circuit)] = (
                     gradient_circuit,
                     base_parameter_values_all,
@@ -72,7 +74,7 @@ def _run(
                 gradient_parameter_values_minus,
                 result_indices,
                 coeffs,
-            ) = make_param_shift_parameter_values(
+            ) = _make_param_shift_parameter_values(
                 gradient_circuit_data=gradient_circuit,
                 base_parameter_values=base_parameter_values_all,
                 parameter_values=parameter_values_,
@@ -90,6 +92,8 @@ def _run(
             coeffs_all.append(coeffs)
 
         # combine the results
+        if any(job.status() is not JobStatus.DONE for job in jobs):
+            raise QiskitError("The gradient job was not completed successfully. ")
         results = [job.result() for job in jobs]
         gradients = []
         for i, result in enumerate(results):

qiskit/algorithms/gradients/sampler_gradient_result.py

@@ -18,20 +18,14 @@
 from typing import Any
 from dataclasses import dataclass
 
-from qiskit.result import QuasiDistribution
-
 
 @dataclass(frozen=True)
 class SamplerGradientResult:
-    """Result of SamplerGradient.
-
-    Args:
-        gradients: The gradients of the quasi distributions.
-        metadata: Additional information about the job.
-        run_options: run_options for the sampler. Currently, sampler's default run_options is not
-        included.
-    """
+    """Result of SamplerGradient."""
 
-    gradients: list[list[QuasiDistribution]]
+    gradients: list[list[dict[int, float]]]
+    """The gradients of the sample probabilities."""
     metadata: list[dict[str, Any]]
+    """Additional information about the job."""
     run_options: dict[str, Any]
+    """run_options for the sampler. Currently, sampler's default run_options is not included"""