Gradients with the primitives

qiskit/algorithms/gradients/__init__.py

@@ -0,0 +1,74 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+=====================================
+Gradients (:mod:`qiskit.algorithms.gradients`)
+=====================================
+
+.. currentmodule:: qiskit.algorithms.gradients
+
+Base Classes
+============
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   BaseSamplerGradient
+   BaseEstimatorGradient
+
+Gradients
+=========
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   FiniteDiffEstimatorGradient
+   FiniteDiffSamplerGradient
+   LinCombEstimatorGradient
+   LinCombSamplerGradient
+   ParamShiftEstimatorGradient
+   ParamShiftSamplerGradient
+
+Results
+=======
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   EstimatorResult
+   SamplerResult
+"""
+
+from .base_estimator_gradient import BaseEstimatorGradient
+from .base_sampler_gradient import BaseSamplerGradient
+from .estimator_gradient_result import EstimatorGradientResult
+from .finite_diff_estimator_gradient import FiniteDiffEstimatorGradient
+from .finite_diff_sampler_gradient import FiniteDiffSamplerGradient
+from .lin_comb_estimator_gradient import LinCombEstimatorGradient
+from .lin_comb_sampler_gradient import LinCombSamplerGradient
+from .param_shift_estimator_gradient import ParamShiftEstimatorGradient
+from .param_shift_sampler_gradient import ParamShiftSamplerGradient
+from .sampler_gradient_result import SamplerGradientResult
+
+__all__ = [
+    "BaseEstimatorGradient",
+    "BaseSamplerGradient",
+    "EstimatorGradientResult",
+    "FiniteDiffEstimatorGradient",
+    "FiniteDiffSamplerGradient",
+    "LinCombEstimatorGradient",
+    "LinCombSamplerGradient",
+    "ParamShiftEstimatorGradient",
+    "ParamShiftSamplerGradient",
+    "SamplerGradientResult",
+]

qiskit/algorithms/gradients/base_estimator_gradient.py

@@ -0,0 +1,122 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+Abstract Base class of Gradient for Estimator.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+
+from qiskit.circuit import Parameter, QuantumCircuit
+from qiskit.exceptions import QiskitError
+from qiskit.opflow import PauliSumOp
+from qiskit.primitives import BaseEstimator
+from qiskit.quantum_info.operators.base_operator import BaseOperator
+
+from .estimator_gradient_result import EstimatorGradientResult
+
+
+class BaseEstimatorGradient(ABC):
+    """Base class for an EstimatorGradient to compute the gradients of the expectation value."""
+
+    def __init__(
+        self,
+        estimator: BaseEstimator,
+        **run_options,
+    ):
+        """
+        Args:
+            estimator: The estimator used to compute the gradients.
+        """
+        self._estimator: BaseEstimator = estimator
+        self._circuits: Sequence[QuantumCircuit] = []
+        self._circuit_ids: dict[int, int] = {}
+        self._default_run_options = run_options
+
+    def evaluate(
+        self,
+        circuits: Sequence[QuantumCircuit],
+        observables: Sequence[BaseOperator | PauliSumOp],
+        parameter_values: Sequence[Sequence[float]],
+        partial: Sequence[Sequence[Parameter]] | None = None,
+        **run_options,
+    ) -> EstimatorGradientResult:
+        """Run the job of the gradients of expectation values.
+
+        Args:
+            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.
+            partial: The list of Parameters to calculate only the gradients of the specified parameters.
+                Defaults to None, which means that the gradients of all parameters will be calculated.
+            run_options: Backend runtime options used for circuit execution.
+
+        Returns:
+            The job object of the gradients of the expectation values. The i-th result corresponds to
+            ``circuits[i]`` evaluated with parameters bound as ``parameter_values[i]``.
+
+        Raises:
+            QiskitError: Invalid arguments are given.
+        """
+        # Validation
+        if len(circuits) != len(parameter_values):
+            raise QiskitError(
+                f"The number of circuits ({len(circuits)}) does not match "
+                f"the number of parameter value sets ({len(parameter_values)})."
+            )
+
+        if len(circuits) != len(observables):
+            raise QiskitError(
+                f"The number of circuits ({len(circuits)}) does not match "
+                f"the number of observables ({len(partial)})."
+            )
+
+        if partial is not None:
+            if len(circuits) != len(partial):
+                raise QiskitError(
+                    f"The number of circuits ({len(circuits)}) does not match "
+                    f"the number of partial parameter sets ({len(partial)})."
+                )
+
+        for i, (circuit, parameter_value) in enumerate(zip(circuits, parameter_values)):
+            if len(parameter_value) != circuit.num_parameters:
+                raise QiskitError(
+                    f"The number of values ({len(parameter_value)}) does not match "
+                    f"the number of parameters ({circuit.num_parameters}) for the {i}-th circuit."
+                )
+
+        for i, (circuit, observable) in enumerate(zip(circuits, observables)):
+            if circuit.num_qubits != observable.num_qubits:
+                raise QiskitError(
+                    f"The number of qubits of the {i}-th circuit ({circuit.num_qubits}) does "
+                    f"not match the number of qubits of the {i}-th observable "
+                    f"({observable.num_qubits})."
+                )
+
+        # The priority of run option is as follows:
+        # run_options in `run` method > gradient's default run_options > primitive's default setting.
+        run_options = run_options or self._default_run_options
+        return self._evaluate(circuits, observables, parameter_values, partial, **run_options)
+
+    @abstractmethod
+    def _evaluate(
+        self,
+        circuits: Sequence[QuantumCircuit],
+        observables: Sequence[BaseOperator | PauliSumOp],
+        parameter_values: Sequence[Sequence[float]],
+        partial: Sequence[Sequence[Parameter]] | None = None,
+        **run_options,
+    ) -> EstimatorGradientResult:
+        raise NotImplementedError()

qiskit/algorithms/gradients/base_sampler_gradient.py

@@ -0,0 +1,99 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+Abstract Base class of Gradient for Sampler.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+
+from qiskit.circuit import QuantumCircuit, Parameter
+from qiskit.exceptions import QiskitError
+from qiskit.primitives import BaseSampler
+from .sampler_gradient_result import SamplerGradientResult
+
+
+class BaseSamplerGradient(ABC):
+    """Base class for a SamplerGradient to compute the gradients of the sampling probability."""
+
+    def __init__(self, sampler: BaseSampler, **run_options):
+        """
+        Args:
+            sampler: The sampler used to compute the gradients.
+        """
+        self._sampler: BaseSampler = sampler
+        self._circuits: list[QuantumCircuit] = []
+        self._circuit_ids: dict[int, int] = {}
+        self._default_run_options = run_options
+
+    def evaluate(
+        self,
+        circuits: Sequence[QuantumCircuit],
+        parameter_values: Sequence[Sequence[float]],
+        partial: Sequence[Sequence[Parameter]] | None = None,
+        **run_options,
+    ) -> SamplerGradientResult:
+        """Run the job of the gradients of the sampling probability.
+
+        Args:
+            circuits: The list of quantum circuits to compute the gradients.
+            parameter_values: The list of parameter values to be bound to the circuit.
+            partial: The list of Parameters to calculate only the gradients of the specified parameters.
+                Defaults to None, which means that the gradients of all parameters will be calculated.
+            run_options: Backend runtime options used for circuit execution.
+
+        Returns:
+            The job object of the gradients of the sampling probability. The i-th result corresponds to
+            ``circuits[i]`` evaluated with parameters bound as ``parameter_values[i]``. The j-th
+            quasi-probability distribution in the i-th result corresponds to the gradients of the
+            sampling probability for the j-th parameter in ``circuits[i]``.
+
+        Raises:
+            QiskitError: Invalid arguments are given.
+        """
+        # Validation
+        if len(circuits) != len(parameter_values):
+            raise QiskitError(
+                f"The number of circuits ({len(circuits)}) does not match "
+                f"the number of parameter value sets ({len(parameter_values)})."
+            )
+        if partial is not None:
+            if len(circuits) != len(partial):
+                raise QiskitError(
+                    f"The number of circuits ({len(circuits)}) does not match "
+                    f"the number of partial parameter sets ({len(partial)})."
+                )
+
+        for i, (circuit, parameter_value) in enumerate(zip(circuits, parameter_values)):
+            if len(parameter_value) != circuit.num_parameters:
+                raise QiskitError(
+                    f"The number of values ({len(parameter_value)}) does not match "
+                    f"the number of parameters ({circuit.num_parameters}) for the {i}-th circuit."
+                )
+
+        # The priority of run option is as follows:
+        # run_options in `run` method > gradient's default run_options > primitive's default run_options.
+        run_options = run_options or self._default_run_options
+        return self._evaluate(circuits, parameter_values, partial, **run_options)
+
+    @abstractmethod
+    def _evaluate(
+        self,
+        circuits: Sequence[QuantumCircuit],
+        parameter_values: Sequence[Sequence[float]],
+        partial: Sequence[Sequence[Parameter]] | None = None,
+        **run_options,
+    ) -> SamplerGradientResult:
+        raise NotImplementedError()

qiskit/algorithms/gradients/estimator_gradient_result.py

@@ -0,0 +1,39 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+"""
+Estimator result class
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+from qiskit.providers import JobStatus
+
+
+@dataclass(frozen=True)
+class EstimatorGradientResult:
+    """Result of EstimatorGradient.
+
+    Args:
+        results (list[EstimatorResult]): List of EstimatorResults. The i-th result corresponds to
+            ``circuits[i]`` evaluated with parameters bound as ``parameter_values[i]``. The j-th value
+            in the i-th result corresponds to the gradients of the j-th parameter in ``circuits[i]``.
+        status: List of JobStatus for each EstimatorResult.
+    """
+
+    values: list[np.ndarray]
+    status: list[JobStatus]
+    metadata: list[dict[str, Any]]