Gradients with the primitives

qiskit/algorithms/gradients/base_estimator_gradient.py

@@ -0,0 +1,83 @@
+# 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.opflow import PauliSumOp
+from qiskit.primitives import BaseEstimator
+from qiskit.quantum_info.operators.base_operator import BaseOperator
+
+from .estimator_gradient_job import EstimatorGradientJob
+
+
+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 run(
+        self,
+        circuits: Sequence[QuantumCircuit],
+        observables: Sequence[BaseOperator | PauliSumOp],
+        parameter_values: Sequence[Sequence[float]],
+        partial: Sequence[Sequence[Parameter]] | None = None,
+        **run_options,
+    ) -> EstimatorGradientJob:
+        """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]``.
+        """
+        # 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._run(circuits, observables, parameter_values, partial, **run_options)
+
+    @abstractmethod
+    def _run(
+        self,
+        circuits: Sequence[QuantumCircuit],
+        observables: Sequence[BaseOperator | PauliSumOp],
+        parameter_values: Sequence[Sequence[float]],
+        partial: Sequence[Sequence[Parameter]] | None = None,
+        **run_options,
+    ) -> EstimatorGradientJob:
+        raise NotImplementedError()

qiskit/algorithms/gradients/base_sampler_gradient.py

@@ -0,0 +1,75 @@
+# 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.primitives import BaseSampler
+from .sampler_gradient_job import SamplerGradientJob
+
+
+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 run(
+        self,
+        circuits: Sequence[QuantumCircuit],
+        parameter_values: Sequence[Sequence[float]],
+        partial: Sequence[Sequence[Parameter]] | None = None,
+        **run_options,
+    ) -> SamplerGradientJob:
+        """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]``.
+        """
+        # 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._run(circuits, parameter_values, partial, **run_options)
+
+    @abstractmethod
+    def _run(
+        self,
+        circuits: Sequence[QuantumCircuit],
+        parameter_values: Sequence[Sequence[float]],
+        partial: Sequence[Sequence[Parameter]] | None = None,
+        **run_options,
+    ) -> SamplerGradientJob:
+        raise NotImplementedError()

qiskit/algorithms/gradients/estimator_gradient_job.py

@@ -0,0 +1,36 @@
+# 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 qiskit.primitives import EstimatorResult
+from qiskit.providers import JobStatus
+
+
+@dataclass(frozen=True)
+class EstimatorGradientJob:
+    """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.
+    """
+
+    results: list[EstimatorResult]
+    status: list[JobStatus]

qiskit/algorithms/gradients/finite_diff_estimator_gradient.py

@@ -0,0 +1,127 @@
+# 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.
+
+"""Gradient of Sampler with Finite difference method."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+import numpy as np
+
+from qiskit.circuit import Parameter, QuantumCircuit
+from qiskit.opflow import PauliSumOp
+from qiskit.primitives import BaseEstimator, EstimatorResult
+from qiskit.quantum_info.operators.base_operator import BaseOperator
+
+from .base_estimator_gradient import BaseEstimatorGradient
+from .estimator_gradient_job import EstimatorGradientJob
+from .utils import make_fin_diff_base_parameter_values
+
+
+class FiniteDiffEstimatorGradient(BaseEstimatorGradient):
+    """
+    Gradient of Estimator with Finite difference method.
+    """
+
+    def __init__(
+        self,
+        estimator: BaseEstimator,
+        epsilon: float = 1e-6,
+        **run_options
+    ):
+        """
+        Args:
+            estimator: The estimator used to compute the gradients.
+            epsilon: The offset size for the finite difference gradients.
+        """
+        self._epsilon = epsilon
+        self._base_parameter_values_dict = {}
+        super().__init__(estimator, **run_options)
+
+    def _run(
+        self,
+        circuits: Sequence[QuantumCircuit],
+        observables: Sequence[BaseOperator | PauliSumOp],
+        parameter_values: Sequence[Sequence[float]],
+        partial: Sequence[Sequence[Parameter]] | None = None,
+        **run_options,
+    ) -> EstimatorGradientJob:
+        partial = partial or [[] for _ in range(len(circuits))]
+        gradients = []
+        status = []
+        for circuit, observable, parameter_values_, partial_ in zip(
+            circuits, observables, parameter_values, partial
+        ):
+            index = self._circuit_ids.get(id(circuit))
+            if index is not None:
+                circuit_index = index
+            else:
+                # if the given circuit is  a new one, make base parameter values for + and - epsilon
+                circuit_index = len(self._circuits)
+                self._circuit_ids[id(circuit)] = circuit_index
+                self._base_parameter_values_dict[
+                    circuit_index
+                ] = make_fin_diff_base_parameter_values(circuit, self._epsilon)
+                self._circuits.append(circuit)
+
+            circuit_parameters = self._circuits[circuit_index].parameters
+            base_parameter_values_list = []
+            gradient_parameter_values = np.zeros(len(circuit_parameters))
+
+            # a parameter set for the partial option
+            parameters = partial_ or circuit_parameters
+            param_set = set(parameters)
+
+            result_index = 0
+            result_index_map = {}
+            # bring the base parameter values for parameters only in the partial parameter set.
+            for i, param in enumerate(circuit_parameters):
+                gradient_parameter_values[i] = parameter_values_[i]
+                if param in param_set:
+                    base_parameter_values_list.append(
+                        self._base_parameter_values_dict[circuit_index][i * 2]
+                    )
+                    base_parameter_values_list.append(
+                        self._base_parameter_values_dict[circuit_index][i * 2 + 1]
+                    )
+                    result_index_map[param] = result_index
+                    result_index += 1
+            # add the given parameter values and the base parameter values
+            gradient_parameter_values_list = [
+                gradient_parameter_values + base_parameter_values
+                for base_parameter_values in base_parameter_values_list
+            ]
+            gradient_circuits = [self._circuits[circuit_index]] * len(
+                gradient_parameter_values_list
+            )
+            observable_list = [observable] * len(gradient_parameter_values_list)
+
+            job = self._estimator.run(
+                gradient_circuits, observable_list, gradient_parameter_values_list, **run_options
+            )
+            results = job.result()
+
+            # Combines the results and coefficients to reconstruct the gradient
+            # for the original circuit parameters
+            values = np.zeros(len(parameter_values_))
+            for i, param in enumerate(circuit_parameters):
+                if param not in param_set:
+                    continue
+                # plus
+                values[i] += results.values[result_index_map[param] * 2] / (2 * self._epsilon)
+                # minus
+                values[i] -= results.values[result_index_map[param] * 2 + 1] / (2 * self._epsilon)
+
+            gradients.append(EstimatorResult(values, metadata=run_options))
+            status.append(job.status())
+        return EstimatorGradientJob(results=gradients, status=status)