Document Primitives types

qiskit/primitives/__init__.py

@@ -31,11 +31,11 @@
 :class:`~.StatevectorSampler` and :class:`~.StatevectorEstimator` classes.
 
 The earlier versions of the sampler and estimator abstractions are defined by :class:`~.BaseSamplerV1`
-and :class:`~.BaseEstimatorV1`. These interfaces follow a different and less flexible input-output 
-format for the ``run`` method and have been largely replaced in practice by :class:`~.BaseSamplerV2` and 
-:class:`~.BaseEstimatorV2`. However, the original abstract interface definitions have been 
-retained for backward compatibility. Check the migration section of this page to see further details 
-on the difference between V1 and V2. 
+and :class:`~.BaseEstimatorV1`. These interfaces follow a different and less flexible input-output
+format for the ``run`` method and have been largely replaced in practice by :class:`~.BaseSamplerV2` and
+:class:`~.BaseEstimatorV2`. However, the original abstract interface definitions have been
+retained for backward compatibility. Check the migration section of this page to see further details
+on the difference between V1 and V2.
 
 Overview of EstimatorV2
 =======================
@@ -174,11 +174,11 @@
 Overview of EstimatorV1
 =======================
 
-There are currently no implementations of the legacy ``EstimatorV1`` interface in Qiskit. 
-However, the abstract interface definition from :class:`~BaseEstimatorV1` is still part 
-of the package to provide backwards compatibility for external implementations. 
+There are currently no implementations of the legacy ``EstimatorV1`` interface in Qiskit.
+However, the abstract interface definition from :class:`~BaseEstimatorV1` is still part
+of the package to provide backwards compatibility for external implementations.
 
-An ``EstimatorV1`` implementation is initialized with an empty parameter set. 
+An ``EstimatorV1`` implementation is initialized with an empty parameter set.
 :class:`~BaseEstimatorV1` can be called via the ``.run()`` method with the following parameters:
 
 * quantum circuits (:math:`\psi_i(\theta)`): list of (parameterized) quantum circuits
@@ -201,14 +201,14 @@
     \langle\psi_i(\theta_k)|H_j|\psi_i(\theta_k)\rangle
 
 Here is an example of how an ``EstimatorV1`` implementation would be used.
-Note that there are currently no implementations of the legacy ``EstimatorV1`` 
-interface in Qiskit. 
+Note that there are currently no implementations of the legacy ``EstimatorV1``
+interface in Qiskit.
 
 .. code-block:: python
 
     # This is a fictional import path.
     # There are currently no EstimatorV1 implementations in Qiskit.
-    from estimator_v1_location import EstimatorV1 
+    from estimator_v1_location import EstimatorV1
     from qiskit.circuit.library import RealAmplitudes
     from qiskit.quantum_info import SparsePauliOp
 
@@ -245,13 +245,13 @@
 Overview of SamplerV1
 =====================
 
-There are currently no implementations of the legacy ``SamplerV1`` interface in Qiskit. 
-However, the abstract interface definition from :class:`~BaseSamplerV1` is still part 
-of the package to provide backward compatibility for external implementations. 
+There are currently no implementations of the legacy ``SamplerV1`` interface in Qiskit.
+However, the abstract interface definition from :class:`~BaseSamplerV1` is still part
+of the package to provide backward compatibility for external implementations.
 
 Sampler classes calculate probabilities or quasi-probabilities of bitstrings from quantum circuits.
 
-A ``SamplerV1`` is initialized with an empty parameter set. :class:`~BaseSamplerV1` implementations can 
+A ``SamplerV1`` is initialized with an empty parameter set. :class:`~BaseSamplerV1` implementations can
 be called via the ``.run()`` method with the following parameters:
 
 * quantum circuits (:math:`\psi_i(\theta)`): list of (parameterized) quantum circuits.
@@ -267,14 +267,14 @@
 plus optional metadata like error bars in the samples.
 
 Here is an example of how a ``SamplerV1`` implementation would be used.
-Note that there are currently no implementations of the legacy ``SamplerV1`` 
-interface in Qiskit. 
+Note that there are currently no implementations of the legacy ``SamplerV1``
+interface in Qiskit.
 
 .. code-block:: python
 
     # This is a fictional import path.
     # There are currently no SamplerV1 implementations in Qiskit.
-    from sampler_v1_location import Sampler 
+    from sampler_v1_location import Sampler
     from qiskit import QuantumCircuit
     from qiskit.circuit.library import RealAmplitudes
 
@@ -408,6 +408,16 @@
 Primitives API
 ==============
 
+Parameters V2
+-------------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   ParameterLike
+   BindingsArray
+   BindingsArrayLike
+
 Estimator V2
 ------------
 
@@ -417,6 +427,11 @@
    BaseEstimatorV2
    StatevectorEstimator
    BackendEstimatorV2
+   EstimatorPub
+   EstimatorPubLike
+   ObservablesArray
+   ObservablesArrayLike
+   ObservableLike
 
 Sampler V2
 ----------
@@ -427,6 +442,40 @@
    BaseSamplerV2
    StatevectorSampler
    BackendSamplerV2
+   SamplerPub
+
+.. list-table:: bla
+   :widths: auto
+   :header-rows: 0
+
+   * - SamplerPubLike
+     - Alias of
+
+       .. code-block:: python
+
+           Union[
+               SamplerPub,
+               QuantumCircuit,
+               Tuple[QuantumCircuit],
+               Tuple[QuantumCircuit, BindingsArrayLike],
+               Tuple[QuantumCircuit, BindingsArrayLike,Union[Integral, None]]
+           ]
+
+       A Pub (Primitive Unified Bloc) for a Sampler.
+
+       A fully specified sample Pub is a tuple ``(circuit, parameter_values, shots)``.
+
+       If shots are provided this number of shots will be run with the sampler,
+       if ``shots=None`` the number of run shots is determined by the sampler.
+
+       .. note::
+
+           A Sampler Pub can also be initialized in the following formats which
+           will be converted to the full Pub tuple:
+
+           * ``circuit``
+           * ``(circuit,)``
+           * ``(circuit, parameter_values)``
 
 Results V2
 ----------
@@ -476,11 +525,16 @@
     DataBin,
     PrimitiveResult,
     PubResult,
+    EstimatorPub,
     EstimatorPubLike,
+    SamplerPub,
     SamplerPubLike,
     SamplerPubResult,
+    ParameterLike,
+    BindingsArray,
     BindingsArrayLike,
     ObservableLike,
+    ObservablesArray,
     ObservablesArrayLike,
 )
 from .primitive_job import BasePrimitiveJob, PrimitiveJob

qiskit/primitives/containers/__init__.py

@@ -15,12 +15,12 @@
 """
 
 
-from .bindings_array import BindingsArrayLike
+from .bindings_array import ParameterLike, BindingsArray, BindingsArrayLike
 from .bit_array import BitArray
 from .data_bin import DataBin, make_data_bin
-from .estimator_pub import EstimatorPubLike
-from .observables_array import ObservableLike, ObservablesArrayLike
+from .estimator_pub import EstimatorPub, EstimatorPubLike
+from .observables_array import ObservableLike, ObservablesArray, ObservablesArrayLike
 from .primitive_result import PrimitiveResult
 from .pub_result import PubResult
-from .sampler_pub import SamplerPubLike
+from .sampler_pub import SamplerPub, SamplerPubLike
 from .sampler_pub_result import SamplerPubResult

qiskit/primitives/containers/bindings_array.py

@@ -71,18 +71,21 @@ class BindingsArray(ShapedMixin):
        :include-source:
        :nofigs:
 
-        # 0-d array (i.e. only one binding)
-        BindingsArray({"a": 4, ("b", "c"): [5, 6]})
-
-        # single array, last index is parameters
-        parameters = tuple(f"a{idx}" for idx in range(100))
-        BindingsArray({parameters: np.ones((10, 10, 100))})
-
-        # multiple arrays, where each last index is parameters. notice that it's smart enough to
-        # figure out that a missing last dimension corresponds to a single parameter.
-        BindingsArray(
-            {("c", "a"): np.zeros((10, 10, 2)), "b": np.ones((10, 10))}
-        )
+       import numpy as np
+       from qiskit.primitives import BindingsArray
+
+       # 0-d array (i.e. only one binding)
+       BindingsArray({"a": 4, ("b", "c"): [5, 6]})
+
+       # single array, last index is parameters
+       parameters = tuple(f"a{idx}" for idx in range(100))
+       BindingsArray({parameters: np.ones((10, 10, 100))})
+
+       # multiple arrays, where each last index is parameters. notice that it's smart enough to
+       # figure out that a missing last dimension corresponds to a single parameter.
+       BindingsArray(
+           {("c", "a"): np.zeros((10, 10, 2)), "b": np.ones((10, 10))}
+       )
     """
 
     def __init__(
@@ -112,7 +115,7 @@ class casts all given values to float. If an incompatible dtype is given, such a
             ValueError: If all inputs are ``None``.
             ValueError: If the shape cannot be automatically inferred from the arrays, or if there
                 is some inconsistency in the shape of the given arrays.
-            TypeError: If some of the vaules can't be cast to a float type.
+            TypeError: If some of the values can't be cast to a float type.
         """
         super().__init__()
 

qiskit/primitives/containers/sampler_pub.py

@@ -170,6 +170,7 @@ def validate(self):
 
 
 SamplerPubLike = Union[
+    SamplerPub,
     QuantumCircuit,
     Tuple[QuantumCircuit],
     Tuple[QuantumCircuit, BindingsArrayLike],