qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/primitives/containers/data_bin.py

@@ -0,0 +1,172 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2024.
+#
+# 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.
+
+"""
+Dataclass tools for data namespaces (bins)
+"""
+from __future__ import annotations
+
+from typing import Any, ItemsView, Iterable, KeysView, ValuesView
+
+import numpy as np
+
+from .shape import ShapedMixin, ShapeInput, shape_tuple
+
+
+def _value_repr(value: Any) -> str:
+    """Helper function for :meth:`DataBin.__repr__`."""
+    if isinstance(value, np.ndarray):
+        return f"np.ndarray(<shape={value.shape}, dtype={value.dtype}>)"
+    return repr(value)
+
+
+class DataBin(ShapedMixin):
+    """Namespace for storing data.
+
+    .. plot::
+       :include-source:
+       :nofigs:
+
+        import numpy as np
+        from qiskit.primitives import DataBin, BitArray
+
+        data = DataBin(
+            alpha=BitArray.from_samples(["0010"]),
+            beta=np.array([1.2])
+        )
+
+        print("alpha data:", data.alpha)
+        print("beta data:", data.beta)
+
+    .. code-block::
+
+        alpha data: BitArray(<shape=(), num_shots=1, num_bits=2>)
+        beta data: [1.2]
+
+    """
+
+    __slots__ = ("_data", "_shape")
+
+    _RESTRICTED_NAMES = frozenset(
+        {
+            "_RESTRICTED_NAMES",
+            "_SHAPE",
+            "_FIELDS",
+            "_FIELD_TYPES",
+            "_data",
+            "_shape",
+            "keys",
+            "values",
+            "items",
+            "shape",
+            "ndim",
+            "size",
+        }
+    )
+
+    def __init__(self, *, shape: ShapeInput = (), **data):
+        """
+        Args:
+            data: Name/value data to place in the data bin.
+            shape: The leading shape common to all entries in the data bin. This defaults to
+                the trivial leading shape of ``()`` that is compatible with all objects.
+
+        Raises:
+            ValueError: If a name overlaps with a method name on this class.
+            ValueError: If some value is inconsistent with the provided shape.
+        """
+        if not self._RESTRICTED_NAMES.isdisjoint(data):
+            bad_names = sorted(self._RESTRICTED_NAMES.intersection(data))
+            raise ValueError(f"Cannot assign with these field names: {bad_names}")
+
+        _setattr = super().__setattr__
+        _setattr("_shape", shape_tuple(shape))
+        _setattr("_data", data)
+
+        ndim = len(self._shape)
+        for name, value in data.items():
+            if getattr(value, "shape", shape)[:ndim] != shape:
+                raise ValueError(f"The value of '{name}' does not lead with the shape {shape}.")
+            _setattr(name, value)
+
+        super().__init__()
+
+    def __len__(self):
+        return len(self._data)
+
+    def __repr__(self):
+        vals = [f"{name}={_value_repr(val)}" for name, val in self.items()]
+        if self.ndim:
+            vals.append(f"shape={self.shape}")
+        return f"{type(self).__name__}({', '.join(vals)})"
+
+    def __getitem__(self, key: str) -> Any:
+        try:
+            return self._data[key]
+        except KeyError as ex:
+            raise KeyError(f"Key ({key}) does not exist in this data bin.") from ex
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._data
+
+    def __iter__(self) -> Iterable[str]:
+        return iter(self._data)
+
+    def keys(self) -> KeysView[str]:
+        """Return a view of field names."""
+        return self._data.keys()
+
+    def values(self) -> ValuesView[Any]:
+        """Return a view of values."""
+        return self._data.values()
+
+    def items(self) -> ItemsView[str, Any]:
+        """Return a view of field names and values"""
+        return self._data.items()
+
+    # The following properties exist to provide support to legacy private class attributes which
+    # gained widespread prior to qiskit 1.1. These properties will be removed once the internal
+    # projects have made the appropriate changes.
+
+    @property
+    def _FIELDS(self) -> tuple[str, ...]:  # pylint: disable=invalid-name
+        return tuple(self._data)
+
+    @property
+    def _FIELD_TYPES(self) -> tuple[Any, ...]:  # pylint: disable=invalid-name
+        return tuple(map(type, self.values()))
+
+    @property
+    def _SHAPE(self) -> tuple[int, ...]:  # pylint: disable=invalid-name
+        return self.shape
+
+
+# pylint: disable=unused-argument
+def make_data_bin(
+    fields: Iterable[tuple[str, type]], shape: tuple[int, ...] | None = None
+) -> type[DataBin]:
+    """Return the :class:`~DataBin` type.
+
+    .. note::
+        This class used to return a subclass of :class:`~DataBin`. However, that caused confusion
+        and didn't have a useful purpose. Several internal projects made use of this internal
+        function prior to qiskit 1.1. This function will be removed once these internal projects
+        have made the appropriate changes.
+
+    Args:
+        fields: Tuples ``(name, type)`` specifying the attributes of the returned class.
+        shape: The intended shape of every attribute of this class.
+
+    Returns:
+        The :class:`DataBin` type.
+    """
+    return DataBin

qiskit/primitives/containers/estimator_pub.py

@@ -0,0 +1,222 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2024.
+#
+# 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 Pub class
+"""
+
+from __future__ import annotations
+
+from numbers import Real
+from collections.abc import Mapping
+from typing import Tuple, Union
+
+import numpy as np
+
+from qiskit import QuantumCircuit
+
+from .bindings_array import BindingsArray, BindingsArrayLike
+from .observables_array import ObservablesArray, ObservablesArrayLike
+from .shape import ShapedMixin
+
+# Public API classes
+__all__ = ["EstimatorPubLike"]
+
+
+class EstimatorPub(ShapedMixin):
+    """Primitive Unified Bloc for any Estimator primitive.
+
+    An estimator pub is essentially a tuple ``(circuit, observables, parameter_values, precision)``.
+
+    If precision is provided this should be used for the target precision of an
+    estimator, if ``precision=None`` the estimator will determine the target precision.
+    """
+
+    __slots__ = ("_circuit", "_observables", "_parameter_values", "_precision", "_shape")
+
+    def __init__(
+        self,
+        circuit: QuantumCircuit,
+        observables: ObservablesArray,
+        parameter_values: BindingsArray | None = None,
+        precision: float | None = None,
+        validate: bool = True,
+    ):
+        """Initialize an estimator pub.
+
+        Args:
+            circuit: A quantum circuit.
+            observables: An observables array.
+            parameter_values: A bindings array, if the circuit is parametric.
+            precision: An optional target precision for expectation value estimates.
+            validate: Whether to validate arguments during initialization.
+
+        Raises:
+            ValueError: If the ``observables`` and ``parameter_values`` are not broadcastable, that
+                is, if their shapes, when right-aligned, do not agree or equal 1.
+        """
+        super().__init__()
+        self._circuit = circuit
+        self._observables = observables
+        self._parameter_values = parameter_values or BindingsArray()
+        self._precision = precision
+
+        # for ShapedMixin
+        try:
+            # _shape has to be defined to properly be Shaped, so we can't put it in validation
+            self._shape = np.broadcast_shapes(self.observables.shape, self.parameter_values.shape)
+        except ValueError as ex:
+            raise ValueError(
+                f"The observables shape {self.observables.shape} and the "
+                f"parameter values shape {self.parameter_values.shape} are not broadcastable."
+            ) from ex
+
+        if validate:
+            self.validate()
+
+    @property
+    def circuit(self) -> QuantumCircuit:
+        """A quantum circuit."""
+        return self._circuit
+
+    @property
+    def observables(self) -> ObservablesArray:
+        """An observables array."""
+        return self._observables
+
+    @property
+    def parameter_values(self) -> BindingsArray:
+        """A bindings array."""
+        return self._parameter_values
+
+    @property
+    def precision(self) -> float | None:
+        """The target precision for expectation value estimates (optional)."""
+        return self._precision
+
+    @classmethod
+    def coerce(cls, pub: EstimatorPubLike, precision: float | None = None) -> EstimatorPub:
+        """Coerce :class:`~.EstimatorPubLike` into :class:`~.EstimatorPub`.
+
+        Args:
+            pub: A compatible object for coercion.
+            precision: an optional default precision to use if not
+                       already specified by the pub-like object.
+
+        Returns:
+            An estimator pub.
+        """
+        # Validate precision kwarg if provided
+        if precision is not None:
+            if not isinstance(precision, Real):
+                raise TypeError(f"precision must be a real number, not {type(precision)}.")
+            if precision < 0:
+                raise ValueError("precision must be non-negative")
+        if isinstance(pub, EstimatorPub):
+            if pub.precision is None and precision is not None:
+                return cls(
+                    circuit=pub.circuit,
+                    observables=pub.observables,
+                    parameter_values=pub.parameter_values,
+                    precision=precision,
+                    validate=False,  # Assume Pub is already validated
+                )
+            return pub
+
+        if isinstance(pub, QuantumCircuit):
+            raise ValueError(
+                f"An invalid Estimator pub-like was given ({type(pub)}). "
+                "If you want to run a single pub, you need to wrap it with `[]` like "
+                "`estimator.run([(circuit, observables, param_values)])` "
+                "instead of `estimator.run((circuit, observables, param_values))`."
+            )
+
+        if len(pub) not in [2, 3, 4]:
+            raise ValueError(
+                f"The length of pub must be 2, 3 or 4, but length {len(pub)} is given."
+            )
+        circuit = pub[0]
+        observables = ObservablesArray.coerce(pub[1])
+
+        if len(pub) > 2 and pub[2] is not None:
+            values = pub[2]
+            if not isinstance(values, (BindingsArray, Mapping)):
+                values = {tuple(circuit.parameters): values}
+            parameter_values = BindingsArray.coerce(values)
+        else:
+            parameter_values = None
+
+        if len(pub) > 3 and pub[3] is not None:
+            precision = pub[3]
+
+        return cls(
+            circuit=circuit,
+            observables=observables,
+            parameter_values=parameter_values,
+            precision=precision,
+            validate=True,
+        )
+
+    def validate(self):
+        """Validate the pub."""
+        if not isinstance(self.circuit, QuantumCircuit):
+            raise TypeError("circuit must be QuantumCircuit.")
+
+        self.observables.validate()
+        self.parameter_values.validate()
+
+        if self.precision is not None:
+            if not isinstance(self.precision, Real):
+                raise TypeError(f"precision must be a real number, not {type(self.precision)}.")
+            if self.precision < 0:
+                raise ValueError("precision must be non-negative.")
+
+        # Cross validate circuits and observables
+        for i, observable in np.ndenumerate(self.observables):
+            num_qubits = len(next(iter(observable)))
+            if self.circuit.num_qubits != num_qubits:
+                raise ValueError(
+                    f"The number of qubits of the circuit ({self.circuit.num_qubits}) does "
+                    f"not match the number of qubits of the {i}-th observable ({num_qubits})."
+                )
+
+        # Cross validate circuits and parameter_values
+        num_parameters = self.parameter_values.num_parameters
+        if num_parameters != self.circuit.num_parameters:
+            raise ValueError(
+                f"The number of values ({num_parameters}) does not match "
+                f"the number of parameters ({self.circuit.num_parameters}) for the circuit."
+            )
+
+
+EstimatorPubLike = Union[
+    EstimatorPub,
+    Tuple[QuantumCircuit, ObservablesArrayLike],
+    Tuple[QuantumCircuit, ObservablesArrayLike, BindingsArrayLike],
+    Tuple[QuantumCircuit, ObservablesArrayLike, BindingsArrayLike, Real],
+]
+"""A Pub (Primitive Unified Bloc) for an Estimator primitive.
+
+A fully specified estimator pub is a tuple ``(circuit, observables, parameter_values, precision)``.
+
+If precision is provided this should be used for the target precision of an
+estimator, if ``precision=None`` the estimator will determine the target precision.
+
+.. note::
+
+    An Estimator Pub can also be initialized in the following formats which
+    will be converted to the full Pub tuple:
+
+    * ``(circuit, observables)``
+    * ``(circuit, observables, parameter_values)``
+"""

qiskit/primitives/containers/object_array.py

@@ -0,0 +1,94 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2024.
+#
+# 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.
+
+"""
+Object ND-array initialization function.
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+
+def object_array(
+    arr: ArrayLike,
+    order: str | None = None,
+    copy: bool = True,
+    list_types: Sequence[type] | None = (),
+) -> np.ndarray:
+    """Convert an array-like of objects into an object array.
+
+    .. note::
+
+        If the objects in the array like input define ``__array__`` methods
+        this avoids calling them and will instead set the returned array values
+        to the Python objects themselves.
+
+    Args:
+        arr: An array-like input.
+        order: Optional, the order of the returned array (C, F, A, K). If None
+               the default NumPy ordering of C is used.
+        copy: If True make a copy of the input if it is already an array.
+        list_types: Optional, a sequence of types to treat as lists of array
+            element objects when inferring the array shape from the input.
+
+    Returns:
+        A NumPy ND-array with ``dtype=object``.
+
+    Raises:
+        ValueError: If the input cannot be coerced into an object array.
+    """
+    if isinstance(arr, np.ndarray):
+        if arr.dtype != object or order is not None or copy is True:
+            arr = arr.astype(object, order=order, copy=copy)
+        return arr
+
+    shape = _infer_shape(arr, list_types=tuple(list_types))
+    obj_arr = np.empty(shape, dtype=object, order=order)
+    if not shape:
+        # We call fill here instead of [()] to avoid invoking the
+        # objects `__array__` method if it has one (eg for Pauli's).
+        obj_arr.fill(arr)
+    else:
+        # For other arrays we need to do some tricks to avoid invoking the
+        # objects __array__ method by flattening the input and initializing
+        # using `np.fromiter` which does not invoke `__array__` for object
+        # dtypes.
+        def _flatten(nested, k):
+            if k == 1:
+                return nested
+            else:
+                return [item for sublist in nested for item in _flatten(sublist, k - 1)]
+
+        flattened = _flatten(arr, len(shape))
+        if len(flattened) != obj_arr.size:
+            raise ValueError(
+                "Input object size does not match the inferred array shape."
+                " This most likely occurs when the input is a ragged array."
+            )
+        obj_arr.flat = np.fromiter(flattened, dtype=object, count=len(flattened))
+
+    return obj_arr
+
+
+def _infer_shape(obj: ArrayLike, list_types: tuple[type, ...] = ()) -> tuple[int, ...]:
+    """Infer the shape of an array-like object without casting"""
+    if isinstance(obj, np.ndarray):
+        return obj.shape
+    if not isinstance(obj, (list, *list_types)):
+        return ()
+    size = len(obj)
+    if size == 0:
+        return (size,)
+    return (size, *_infer_shape(obj[0], list_types=list_types))