Add reference implementation of EstimatorV2

qiskit/primitives/__init__.py

@@ -32,6 +32,14 @@
    Estimator
    BackendEstimator
 
+EstimatorV2
+===========
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   StatevectorEstimator
+
 Sampler
 =======
 
@@ -50,13 +58,16 @@
 
    EstimatorResult
    SamplerResult
+   PrimitiveResult
+   TaskResult
 """
 
-from .base import BaseEstimator
-from .base import BaseSampler
 from .backend_estimator import BackendEstimator
-from .estimator import Estimator
-from .base.estimator_result import EstimatorResult
 from .backend_sampler import BackendSampler
-from .sampler import Sampler
+from .base import BaseEstimator, BaseSampler
+from .base.estimator_result import EstimatorResult
 from .base.sampler_result import SamplerResult
+from .containers import BindingsArray, EstimatorTask, ObservablesArray, PrimitiveResult, TaskResult
+from .estimator import Estimator
+from .sampler import Sampler
+from .statevector_estimator import Estimator as StatevectorEstimator

qiskit/primitives/base/__init__.py

@@ -14,7 +14,7 @@
 Abstract base classes for primitives module.
 """
 
-from .base_estimator import BaseEstimator
+from .base_estimator import BaseEstimator, BaseEstimatorV2
 from .base_sampler import BaseSampler
 from .estimator_result import EstimatorResult
 from .sampler_result import SamplerResult

qiskit/primitives/base/base_estimator.py

@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2022.
+# (C) Copyright IBM 2022, 2023.
 #
 # 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
@@ -14,9 +14,99 @@
 
 .. estimator-desc:
 
-=====================
-Overview of Estimator
-=====================
+========================
+Overview of EstimatorV2
+========================
+
+EstimatorV2 class estimates expectation values of quantum circuits and observables.
+
+An estimator is initialized with an empty parameter set. The estimator is used to
+create a :class:`~qiskit.providers.JobV1`, via the
+:meth:`~.BaseEstimatorV2.run()` method. This method is called
+with the list of task.
+Task is composed of tuple of following parameters ``[(circuit, observables, parameter_values)]``.
+
+* quantum circuit (:math:`\psi(\theta)`): (parameterized) quantum circuits
+  :class:`~qiskit.circuit.QuantumCircuit`.
+
+* observables (:math:`H_j`): a list of :class:`~.ObservablesArrayLike` classes
+  (including :class:`~.Pauli`, :class:`~.SparsePauliOp`, str).
+
+* parameter values (:math:`\theta_k`): list of sets of values
+  to be bound to the parameters of the quantum circuits
+  (list of list of float or list of dict).
+
+The method returns a :class:`~qiskit.providers.JobV1` object, calling
+:meth:`qiskit.providers.JobV1.result()` yields the
+a list of expectation values plus optional metadata like confidence intervals for
+the estimation.
+
+.. math::
+
+    \langle\psi(\theta_k)|H_j|\psi(\theta_k)\rangle
+
+The broadcast rule applies for observables and parameters. For more information, please check
+`here <https://github.com/Qiskit/RFCs/blob/master/0015-estimator-interface.md#arrays-and
+-broadcasting->`_.
+
+Here is an example of how the estimator is used.
+
+.. code-block:: python
+
+    from qiskit.primitives.statevector_estimator import Estimator
+    from qiskit.circuit.library import RealAmplitudes
+    from qiskit.quantum_info import SparsePauliOp
+
+    psi1 = RealAmplitudes(num_qubits=2, reps=2)
+    psi2 = RealAmplitudes(num_qubits=2, reps=3)
+
+    H1 = SparsePauliOp.from_list([("II", 1), ("IZ", 2), ("XI", 3)])
+    H2 = SparsePauliOp.from_list([("IZ", 1)])
+    H3 = SparsePauliOp.from_list([("ZI", 1), ("ZZ", 1)])
+
+    theta1 = [0, 1, 1, 2, 3, 5]
+    theta2 = [0, 1, 1, 2, 3, 5, 8, 13]
+    theta3 = [1, 2, 3, 4, 5, 6]
+
+    estimator = Estimator()
+
+    # calculate [ <psi1(theta1)|H1|psi1(theta1)> ]
+    job = estimator.run([(psi1, hamiltonian1, [theta1])])
+    job_result = job.result() # It will block until the job finishes.
+    print(f"The primitive-job finished with result {job_result}"))
+
+    # calculate [ [<psi1(theta1)|H1|psi1(theta1)>,
+    #              <psi1(theta3)|H3|psi1(theta3)>],
+    #             [<psi2(theta2)|H2|psi2(theta2)>] ]
+    job2 = estimator.run(
+        [(psi1, [hamiltonian1, hamiltonian3], [theta1, theta3]), (psi2, hamiltonian2, theta2)]
+    )
+    job_result = job2.result()
+    print(f"The primitive-job finished with result {job_result}")
+
+==============================
+Migration guide from V1 to V2
+==============================
+
+
+The original three arguments are now a single argument task.
+To accommodate this change, the zip function can be used for easy migration.
+For example, suppose the code originally is:
+
+.. code-block:: python
+
+    estimator.run([psi1], [hamiltonian1], [theta1])  # for EstimatorV1
+
+Just add zip function:
+
+.. code-block:: python
+
+    estimator.run(zip([psi1], [hamiltonian1], [theta1]))  # for EstimatorV2
+
+
+========================
+Overview of EstimatorV1
+========================
 
 Estimator class estimates expectation values of quantum circuits and observables.
 
@@ -80,26 +170,29 @@
 
 from __future__ import annotations
 
+import typing
 import warnings
 from abc import abstractmethod
-from collections.abc import Sequence
+from collections.abc import Iterable, Sequence
 from copy import copy
-from typing import Generic, TypeVar
+from typing import Generic, Optional, TypeVar
 
-from qiskit.utils.deprecation import deprecate_func
 from qiskit.circuit import QuantumCircuit
 from qiskit.circuit.parametertable import ParameterView
 from qiskit.providers import JobV1 as Job
 from qiskit.quantum_info.operators import SparsePauliOp
 from qiskit.quantum_info.operators.base_operator import BaseOperator
+from qiskit.utils.deprecation import deprecate_func
 
-from .base_primitive import BasePrimitive
+from ..containers.estimator_task import EstimatorTask, EstimatorTaskLike
+from ..containers.options import BasePrimitiveOptionsLike
 from . import validation
+from .base_primitive import BasePrimitive, BasePrimitiveV2
 
 T = TypeVar("T", bound=Job)
 
 
-class BaseEstimator(BasePrimitive, Generic[T]):
+class BaseEstimatorV1(BasePrimitive, Generic[T]):
     """Estimator base class.
 
     Base class for Estimator that estimates expectation values of quantum circuits and observables.
@@ -254,3 +347,44 @@ def parameters(self) -> tuple[ParameterView, ...]:
             Parameters, where ``parameters[i][j]`` is the j-th parameter of the i-th circuit.
         """
         return tuple(self._parameters)
+
+
+BaseEstimator = BaseEstimatorV1
+
+
+class BaseEstimatorV2(BasePrimitiveV2, Generic[T]):
+    """Estimator base class version 2.
+
+    Estimator estimates expectation values of quantum circuits and observables.
+    """
+
+    def __init__(self, options: Optional[BasePrimitiveOptionsLike]):
+        super().__init__(options=options)
+
+    def run(self, tasks: EstimatorTaskLike | Iterable[EstimatorTaskLike]) -> T:
+        """Run the tasks of the estimation of expectation value(s).
+
+        Args:
+            tasks: a tasklike object. Typically, list of tuple
+                ``(QuantumCircuit, observables, parameter_values)``
+
+        Returns:
+            The job object of Estimator's Result.
+        """
+        if isinstance(tasks, EstimatorTask):
+            tasks = [tasks]
+        elif isinstance(tasks, tuple) and isinstance(tasks[0], QuantumCircuit):
+            tasks = [EstimatorTask.coerce(tasks)]
+        elif isinstance(tasks, Iterable):
+            tasks = [EstimatorTask.coerce(task) for task in tasks]
+        else:
+            raise TypeError(f"Unsupported type {type(tasks)} is given.")
+
+        for task in tasks:
+            task.validate()
+
+        return self._run(tasks)
+
+    @abstractmethod
+    def _run(self, tasks: list[EstimatorTask]) -> T:
+        pass

qiskit/primitives/base/base_primitive.py

@@ -16,15 +16,17 @@
 
 from abc import ABC
 from collections.abc import Sequence
+from typing import Optional
 
 from qiskit.circuit import QuantumCircuit
+from qiskit.primitives.containers import BasePrimitiveOptions, BasePrimitiveOptionsLike
 from qiskit.providers import Options
 from qiskit.utils.deprecation import deprecate_func
 
 from . import validation
 
 
-class BasePrimitive(ABC):
+class BasePrimitiveV1(ABC):
     """Primitive abstract base class."""
 
     def __init__(self, options: dict | None = None):
@@ -72,3 +74,38 @@ def _cross_validate_circuits_parameter_values(
         return validation._cross_validate_circuits_parameter_values(
             circuits, parameter_values=parameter_values
         )
+
+
+BasePrimitive = BasePrimitiveV1
+
+
+class BasePrimitiveV2(ABC):
+    """Primitive abstract base class version 2."""
+
+    version = 2
+    _options_class: type[BasePrimitiveOptions] = BasePrimitiveOptions
+
+    def __init__(self, options: Optional[BasePrimitiveOptionsLike] = None):
+        self._options: type(self)._options_class
+        self._set_options(options)
+
+    @property
+    def options(self) -> BasePrimitiveOptions:
+        """Options for BaseEstimator"""
+        return self._options
+
+    @options.setter
+    def options(self, options: BasePrimitiveOptionsLike):
+        self._set_options(options)
+
+    def _set_options(self, options):
+        if options is None:
+            self._options = self._options_class()
+        elif isinstance(options, dict):
+            self._options = self._options_class(**options)
+        elif isinstance(options, self._options_class):
+            self._options = options
+        else:
+            raise TypeError(
+                f"Invalid 'options' type. It can only be a dictionary of {self._options_class}"
+            )

qiskit/primitives/containers/__init__.py

@@ -0,0 +1,23 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# 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.
+
+"""
+Data containers for primitives.
+"""
+
+from .bindings_array import BindingsArray
+from .data_bin import make_databin
+from .estimator_task import EstimatorTask
+from .observables_array import ObservablesArray
+from .options import BasePrimitiveOptions, BasePrimitiveOptionsLike
+from .primitive_result import PrimitiveResult
+from .task_result import TaskResult

qiskit/primitives/containers/base_task.py

@@ -0,0 +1,34 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# 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.
+
+"""
+Base Task class
+"""
+
+from __future__ import annotations
+
+from qiskit import QuantumCircuit
+
+from .dataclasses import frozen_dataclass
+
+
+@frozen_dataclass
+class BaseTask:
+    """Base class for Task"""
+
+    circuit: QuantumCircuit
+    """Quantum circuit object for the task."""
+
+    def validate(self):
+        """Validate the data"""
+        if not isinstance(self.circuit, QuantumCircuit):
+            raise TypeError("circuit must be QuantumCircuit.")