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
+   PubResult
 """
 
-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, EstimatorPub, ObservablesArray, PrimitiveResult, PubResult
+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,98 @@
 
 .. estimator-desc:
 
-=====================
-Overview of Estimator
-=====================
+========================
+Overview of EstimatorV2
+========================
+
+:class:`~BaseEstimatorV2` is a primitive that estimates expectation values for provided quantum
+circuit and observable combinations.
+
+Following construction, and estimator is used by calling its :meth:`~.BaseEstimatorV2.run` method
+with a list of pubs (Primitive Unified Blocs). Each pub contains three values that, together,
+define a computation unit of work for the estimator to complete:
+
+* a single :class:`~qiskit.circuit.QuantumCircuit`, possibly parametrized, whose final state we
+  define as :math:`\psi(\theta)`,
+
+* one or more observables (specified as any :class:`~.ObservablesArrayLike`, including
+  :class:`~.Pauli`, :class:`~.SparsePauliOp`, ``str``) that specify which expectation values to
+  estimate, denoted :math:`H_j`, and
+
+* a collection parameter value sets to bind the circuit against, :math:`\theta_k`.
+
+Running an estimator returns a :class:`~qiskit.providers.JobV1` object, where calling
+the method :meth:`qiskit.providers.JobV1.result` results in expectation value estimates and metadata
+for each pub:
+
+.. math::
+
+    \langle\psi(\theta_k)|H_j|\psi(\theta_k)\rangle
+
+The observables and parameter values portion of a pub can be array-valued with arbitrary dimensions,
+where standard broadcasting rules are applied, so that, in turn, the estimated result for each pub
+is in general array-valued as well. 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 pubs.
+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.
 
@@ -82,24 +171,27 @@
 
 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 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 qiskit.utils.optionals import HAS_PYDANTIC
 
-from .base_primitive import BasePrimitive
+from ..containers.estimator_pub import EstimatorPubLike
+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 +346,30 @@ 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
+
+
+@HAS_PYDANTIC.require_in_instance
+class BaseEstimatorV2(BasePrimitiveV2):
+    """Estimator base class version 2.
+
+    An estimator estimates expectation values for provided quantum circuit and observable combinations.
+    """
+
+    def __init__(self, options: BasePrimitiveOptionsLike | None):
+        super().__init__(options=options)
+
+    @abstractmethod
+    def run(self, pubs: Iterable[EstimatorPubLike]) -> Job:
+        """Estimate expectation values for each provided pub (Primitive Unified Bloc).
+
+        Args:
+            pubs: a iterable of pubslike object. Typically, list of tuple
+                ``(QuantumCircuit, observables, parameter_values)``
+
+        Returns:
+            A job object that contains results.
+        """
+        pass

qiskit/primitives/base/base_primitive.py

@@ -18,13 +18,14 @@
 from collections.abc import Sequence
 
 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 +73,23 @@ 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: BasePrimitiveOptionsLike | None = None):
+        self._options = self._options_class()
+        if options:
+            self._options.update(options)
+
+    @property
+    def options(self) -> BasePrimitiveOptions:
+        """Options for the primitive"""
+        return self._options

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_data_bin
+from .estimator_pub import EstimatorPub, EstimatorPubLike
+from .observables_array import ObservablesArray
+from .options import BasePrimitiveOptions, BasePrimitiveOptionsLike
+from .primitive_result import PrimitiveResult
+from .pub_result import PubResult

qiskit/primitives/containers/base_pub.py

@@ -0,0 +1,36 @@
+# 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 Pubs class
+"""
+
+from __future__ import annotations
+
+from qiskit import QuantumCircuit
+from qiskit.utils.optionals import HAS_PYDANTIC
+
+from .dataclasses import frozen_dataclass
+
+
+@HAS_PYDANTIC.require_in_instance
+@frozen_dataclass
+class BasePub:
+    """Base class for PUB (Primitive Unified Bloc)"""
+
+    circuit: QuantumCircuit
+    """Quantum circuit object for the pubs."""
+
+    def validate(self):
+        """Validate the data"""
+        if not isinstance(self.circuit, QuantumCircuit):
+            raise TypeError("circuit must be QuantumCircuit.")