qiskit 2.0.3__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/primitives/containers/observables_array.py

@@ -0,0 +1,296 @@
+# 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.
+
+
+"""
+ND-Array container class for Estimator observables.
+"""
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from collections.abc import Iterable, Mapping as _Mapping
+from functools import lru_cache
+from typing import Union, Mapping, overload
+from numbers import Complex
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from qiskit.quantum_info import Pauli, PauliList, SparsePauliOp
+
+from .object_array import object_array
+from .shape import ShapedMixin, shape_tuple
+
+# Public API classes
+__all__ = ["ObservableLike", "ObservablesArrayLike"]
+
+ObservableLike = Union[
+    str,
+    Pauli,
+    SparsePauliOp,
+    Mapping[Union[str, Pauli], float],
+]
+"""Types that can be natively used to construct a Hermitian Estimator observable."""
+
+
+ObservablesArrayLike = Union[ObservableLike, ArrayLike]
+"""Types that can be natively converted to an array of Hermitian Estimator observables."""
+
+
+class ObservablesArray(ShapedMixin):
+    """An ND-array of Hermitian observables for an :class:`.Estimator` primitive."""
+
+    __slots__ = ("_array", "_shape")
+    ALLOWED_BASIS: str = "IXYZ01+-lr"
+    """The allowed characters in basis strings."""
+
+    def __init__(
+        self,
+        observables: ObservablesArrayLike,
+        copy: bool = True,
+        validate: bool = True,
+    ):
+        """Initialize an observables array.
+
+        Args:
+            observables: An array-like of basis observable compatible objects.
+            copy: Specify the ``copy`` kwarg of the :func:`.object_array` function
+                when initializing observables.
+            validate: If true, coerce entries into the internal format and validate them. If false,
+                the input should already be an array-like.
+
+        Raises:
+            ValueError: If ``validate=True`` and the input observables is not valid.
+        """
+        super().__init__()
+        if isinstance(observables, ObservablesArray):
+            observables = observables._array
+        self._array = object_array(observables, copy=copy, list_types=(PauliList,))
+        self._shape = self._array.shape
+        if validate:
+            num_qubits = None
+            for ndi, obs in np.ndenumerate(self._array):
+                basis_obs = self.coerce_observable(obs)
+                basis_num_qubits = len(next(iter(basis_obs)))
+                if num_qubits is None:
+                    num_qubits = basis_num_qubits
+                elif basis_num_qubits != num_qubits:
+                    raise ValueError(
+                        "The number of qubits must be the same for all observables in the "
+                        "observables array."
+                    )
+                self._array[ndi] = basis_obs
+
+    def __repr__(self):
+        prefix = f"{type(self).__name__}("
+        suffix = f", shape={self.shape})"
+        array = np.array2string(self._array, prefix=prefix, suffix=suffix, threshold=50)
+        return prefix + array + suffix
+
+    def tolist(self) -> list | ObservableLike:
+        """Convert to a nested list.
+
+        Similar to Numpy's ``tolist`` method, the level of nesting
+        depends on the dimension of the observables array. In the
+        case of dimension 0 the method returns a single observable
+        (``dict`` in the case of a weighted sum of Paulis) instead of a list.
+
+        Examples::
+            Return values for a one-element list vs one element:
+
+                >>> from qiskit.primitives.containers.observables_array import ObservablesArray
+                >>> oa = ObservablesArray.coerce(["Z"])
+                >>> print(type(oa.tolist()))
+                <class 'list'>
+                >>> oa = ObservablesArray.coerce("Z")
+                >>> print(type(oa.tolist()))
+                <class 'dict'>
+        """
+        return self._array.tolist()
+
+    def __array__(self, dtype=None, copy=None):
+        """Convert to an Numpy.ndarray"""
+        if dtype is None or dtype == object:
+            return self._array.copy() if copy else self._array
+        raise ValueError("Type must be 'None' or 'object'")
+
+    @overload
+    def __getitem__(self, args: int | tuple[int, ...]) -> Mapping[str, float]: ...
+
+    @overload
+    def __getitem__(self, args: slice) -> ObservablesArray: ...
+
+    def __getitem__(self, args):
+        item = self._array[args]
+        if not isinstance(item, np.ndarray):
+            return item
+        return ObservablesArray(item, copy=False, validate=False)
+
+    def reshape(self, *shape: int | Iterable[int]) -> ObservablesArray:
+        """Return a new array with a different shape.
+
+        This results in a new view of the same arrays.
+
+        Args:
+            shape: The shape of the returned array.
+
+        Returns:
+            A new array.
+        """
+        shape = shape_tuple(*shape)
+        return ObservablesArray(self._array.reshape(shape), copy=False, validate=False)
+
+    def ravel(self) -> ObservablesArray:
+        """Return a new array with one dimension.
+
+        The returned array has a :attr:`shape` given by ``(size, )``, where
+        the size is the :attr:`~size` of this array.
+
+        Returns:
+            A new flattened array.
+        """
+        return self.reshape(self.size)
+
+    @classmethod
+    def coerce_observable(cls, observable: ObservableLike) -> Mapping[str, float]:
+        """Format an observable-like object into the internal format.
+
+        Args:
+            observable: The observable-like to format.
+
+        Returns:
+            The coerced observable.
+
+        Raises:
+            TypeError: If the input cannot be formatted because its type is not valid.
+            ValueError: If the input observable is invalid.
+        """
+        # Pauli-type conversions
+        if isinstance(observable, SparsePauliOp):
+            observable = observable.simplify(atol=0)
+            # Check that the operator is Hermitian and has real coeffs
+            coeffs = np.real_if_close(observable.coeffs)
+            if np.iscomplexobj(coeffs):
+                raise ValueError(
+                    "Non-Hermitian input observable: the input SparsePauliOp has non-zero"
+                    " imaginary part in its coefficients."
+                )
+            paulis = observable.paulis.to_labels()
+            # Call simplify to combine duplicate keys before converting to a mapping
+            return dict(zip(paulis, coeffs))
+
+        if isinstance(observable, Pauli):
+            label, phase = observable[:].to_label(), observable.phase
+            if phase % 2:
+                raise ValueError(
+                    "Non-Hermitian input observable: the input Pauli has an imaginary phase."
+                )
+            return {label: 1} if phase == 0 else {label: -1}
+
+        # String conversion
+        if isinstance(observable, str):
+            cls._validate_basis(observable)
+            return {observable: 1}
+
+        # Mapping conversion (with possible Pauli keys)
+        if isinstance(observable, _Mapping):
+            num_qubits = len(next(iter(observable)))
+            unique = defaultdict(float)
+            for basis, coeff in observable.items():
+                if isinstance(basis, Pauli):
+                    basis, phase = basis[:].to_label(), basis.phase
+                    if phase % 2:
+                        raise ValueError(
+                            "Non-Hermitian input observable: the input Pauli has an imaginary phase."
+                        )
+                    if phase == 2:
+                        coeff = -coeff
+                # Truncate complex numbers to real
+                if isinstance(coeff, Complex):
+                    if abs(coeff.imag) > 1e-7:
+                        raise TypeError(
+                            f"Non-Hermitian input observable: {basis} term has a complex value"
+                            " coefficient."
+                        )
+                    coeff = coeff.real
+
+                # Validate basis
+                cls._validate_basis(basis)
+                if len(basis) != num_qubits:
+                    raise ValueError(
+                        "Number of qubits must be the same for all observable basis elements."
+                    )
+                unique[basis] += coeff
+            return dict(unique)
+
+        raise TypeError(f"Invalid observable type: {type(observable)}")
+
+    @classmethod
+    def coerce(cls, observables: ObservablesArrayLike) -> ObservablesArray:
+        """Coerce ObservablesArrayLike into ObservableArray.
+
+        Args:
+            observables: an object to be observables array.
+
+        Returns:
+            A coerced observables array.
+        """
+        if isinstance(observables, ObservablesArray):
+            return observables
+        return cls(observables)
+
+    def validate(self):
+        """Validate the consistency in observables array."""
+        num_qubits = None
+        for obs in self._array.reshape(-1):
+            basis_num_qubits = len(next(iter(obs)))
+            if num_qubits is None:
+                num_qubits = basis_num_qubits
+            elif basis_num_qubits != num_qubits:
+                raise ValueError(
+                    "The number of qubits must be the same for all observables in the "
+                    "observables array."
+                )
+
+    @classmethod
+    def _validate_basis(cls, basis: str) -> None:
+        """Validate a basis string.
+
+        Args:
+            basis: a basis string to validate.
+
+        Raises:
+            ValueError: If basis string contains invalid characters
+        """
+        # NOTE: the allowed basis characters can be overridden by modifying the class
+        # attribute ALLOWED_BASIS
+        allowed_pattern = _regex_match(cls.ALLOWED_BASIS)
+        if not allowed_pattern.match(basis):
+            invalid_pattern = _regex_invalid(cls.ALLOWED_BASIS)
+            invalid_chars = list(set(invalid_pattern.findall(basis)))
+            raise ValueError(
+                f"Observable basis string '{basis}' contains invalid characters {invalid_chars},"
+                f" allowed characters are {list(cls.ALLOWED_BASIS)}.",
+            )
+
+
+@lru_cache(1)
+def _regex_match(allowed_chars: str) -> re.Pattern:
+    """Return pattern for matching if a string contains only the allowed characters."""
+    return re.compile(f"^[{re.escape(allowed_chars)}]*$")
+
+
+@lru_cache(1)
+def _regex_invalid(allowed_chars: str) -> re.Pattern:
+    """Return pattern for selecting invalid strings"""
+    return re.compile(f"[^{re.escape(allowed_chars)}]")

qiskit/primitives/containers/primitive_result.py

@@ -0,0 +1,53 @@
+# 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.
+
+"""PrimitiveResult"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Generic, TypeVar
+
+from .pub_result import PubResult
+
+T = TypeVar("T", bound=PubResult)
+
+
+class PrimitiveResult(Generic[T]):
+    """A container for multiple pub results and global metadata."""
+
+    def __init__(self, pub_results: Iterable[T], metadata: dict[str, Any] | None = None):
+        """
+        Args:
+            pub_results: Pub results.
+            metadata: Metadata that is common to all pub results; metadata specific to particular
+                pubs should be placed in their metadata fields. Keys are expected to be strings.
+        """
+        self._pub_results = list(pub_results)
+        self._metadata = metadata or {}
+
+    @property
+    def metadata(self) -> dict[str, Any]:
+        """The metadata of this primitive result."""
+        return self._metadata
+
+    def __getitem__(self, index) -> T:
+        return self._pub_results[index]
+
+    def __len__(self) -> int:
+        return len(self._pub_results)
+
+    def __repr__(self) -> str:
+        return f"PrimitiveResult({self._pub_results}, metadata={self.metadata})"
+
+    def __iter__(self) -> Iterable[T]:
+        return iter(self._pub_results)

qiskit/primitives/containers/pub_result.py

@@ -0,0 +1,51 @@
+# 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 Pub result class
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .data_bin import DataBin
+
+
+class PubResult:
+    """Result of Primitive Unified Bloc."""
+
+    __slots__ = ("_data", "_metadata")
+
+    def __init__(self, data: DataBin, metadata: dict[str, Any] | None = None):
+        """Initialize a pub result.
+
+        Args:
+            data: Result data.
+            metadata: Metadata specific to this pub. Keys are expected to be strings.
+        """
+        self._data = data
+        self._metadata = metadata or {}
+
+    def __repr__(self):
+        metadata = f", metadata={self.metadata}" if self.metadata else ""
+        return f"{type(self).__name__}(data={self._data}{metadata})"
+
+    @property
+    def data(self) -> DataBin:
+        """Result data for the pub."""
+        return self._data
+
+    @property
+    def metadata(self) -> dict:
+        """Metadata for the pub."""
+        return self._metadata

qiskit/primitives/containers/sampler_pub.py

@@ -0,0 +1,193 @@
+# 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.
+
+
+"""
+Sampler Pub class
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from numbers import Integral
+from typing import Tuple, Union
+
+from qiskit import QuantumCircuit
+from qiskit.circuit import CircuitInstruction
+
+from .bindings_array import BindingsArray, BindingsArrayLike
+from .shape import ShapedMixin
+
+# Public API classes
+__all__ = ["SamplerPubLike"]
+
+
+class SamplerPub(ShapedMixin):
+    """Pub (Primitive Unified Bloc) for a Sampler.
+
+    Pub is composed of 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.
+    """
+
+    def __init__(
+        self,
+        circuit: QuantumCircuit,
+        parameter_values: BindingsArray | None = None,
+        shots: int | None = None,
+        validate: bool = True,
+    ):
+        """Initialize a sampler pub.
+
+        Args:
+            circuit: A quantum circuit.
+            parameter_values: A bindings array.
+            shots: A specific number of shots to run with. This value takes
+                precedence over any value owed by or supplied to a sampler.
+            validate: If ``True``, the input data is validated during initialization.
+        """
+        super().__init__()
+        self._circuit = circuit
+        self._parameter_values = parameter_values or BindingsArray()
+        self._shots = shots
+        self._shape = self._parameter_values.shape
+        if validate:
+            self.validate()
+
+    @property
+    def circuit(self) -> QuantumCircuit:
+        """A quantum circuit."""
+        return self._circuit
+
+    @property
+    def parameter_values(self) -> BindingsArray:
+        """A bindings array."""
+        return self._parameter_values
+
+    @property
+    def shots(self) -> int | None:
+        """An specific number of shots to run with (optional).
+
+        This value takes precedence over any value owed by or supplied to a sampler.
+        """
+        return self._shots
+
+    @classmethod
+    def coerce(cls, pub: SamplerPubLike, shots: int | None = None) -> SamplerPub:
+        """Coerce a :class:`~.SamplerPubLike` object into a :class:`~.SamplerPub` instance.
+
+        Args:
+            pub: An object to coerce.
+            shots: An optional default number of shots to use if not
+                   already specified by the pub-like object.
+
+        Returns:
+            A coerced sampler pub.
+        """
+        # Validate shots kwarg if provided
+        if shots is not None:
+            if not isinstance(shots, Integral) or isinstance(shots, bool):
+                raise TypeError("shots must be an integer")
+            if shots <= 0:
+                raise ValueError("shots must be positive")
+
+        if isinstance(pub, SamplerPub):
+            if pub.shots is None and shots is not None:
+                return cls(
+                    circuit=pub.circuit,
+                    parameter_values=pub.parameter_values,
+                    shots=shots,
+                    validate=False,  # Assume Pub is already validated
+                )
+            return pub
+
+        if isinstance(pub, QuantumCircuit):
+            return cls(circuit=pub, shots=shots, validate=True)
+
+        if isinstance(pub, CircuitInstruction):
+            raise ValueError(
+                f"An invalid Sampler pub-like was given ({type(pub)}). "
+                "If you want to run a single circuit, "
+                "you need to wrap it with `[]` like `sampler.run([circuit])` "
+                "instead of `sampler.run(circuit)`."
+            )
+
+        if len(pub) not in [1, 2, 3]:
+            raise ValueError(
+                f"The length of pub must be 1, 2 or 3, but length {len(pub)} is given."
+            )
+        circuit = pub[0]
+
+        if len(pub) > 1 and pub[1] is not None:
+            values = pub[1]
+            if not isinstance(values, (BindingsArray, Mapping)):
+                values = {tuple(circuit.parameters): values}
+            parameter_values = BindingsArray.coerce(values)
+        else:
+            parameter_values = None
+
+        if len(pub) > 2 and pub[2] is not None:
+            shots = pub[2]
+        return cls(circuit=circuit, parameter_values=parameter_values, shots=shots, validate=True)
+
+    def validate(self):
+        """Validate the pub."""
+        if not isinstance(self.circuit, QuantumCircuit):
+            raise TypeError("circuit must be QuantumCircuit.")
+
+        self.parameter_values.validate()
+
+        if self.shots is not None:
+            if not isinstance(self.shots, Integral) or isinstance(self.shots, bool):
+                raise TypeError("shots must be an integer")
+            if self.shots <= 0:
+                raise ValueError("shots must be positive")
+
+        # Cross validate circuits and parameter values
+        num_parameters = self.parameter_values.num_parameters
+        if num_parameters != self.circuit.num_parameters:
+            message = (
+                f"The number of values ({num_parameters}) does not match "
+                f"the number of parameters ({self.circuit.num_parameters}) for the circuit."
+            )
+            if num_parameters == 0:
+                message += (
+                    " Note that if you want to run a single pub, you need to wrap it with `[]` like "
+                    "`sampler.run([(circuit, param_values)])` instead of "
+                    "`sampler.run((circuit, param_values))`."
+                )
+            raise ValueError(message)
+
+
+SamplerPubLike = Union[
+    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)``
+"""

qiskit/primitives/containers/sampler_pub_result.py

@@ -0,0 +1,74 @@
+# 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.
+
+"""
+Sampler Pub result class
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+import numpy as np
+
+from .bit_array import BitArray
+from .pub_result import PubResult
+
+
+class SamplerPubResult(PubResult):
+    """Result of Sampler Pub."""
+
+    def join_data(self, names: Iterable[str] | None = None) -> BitArray | np.ndarray:
+        """Join data from many registers into one data container.
+
+        Data is joined along the bits axis. For example, for :class:`~.BitArray` data, this corresponds
+        to bitstring concatenation.
+
+        Args:
+            names: Which registers to join. Their order is maintained, for example, given
+                ``["alpha", "beta"]``, the data from register ``alpha`` is placed to the left of the
+                data from register ``beta``. When ``None`` is given, this value is set to the
+                ordered list of register names, which will have been preserved from the input circuit
+                order.
+
+        Returns:
+            Joint data.
+
+        Raises:
+            ValueError: If specified names are empty.
+            ValueError: If specified name does not exist.
+            TypeError: If specified data comes from incompatible types.
+        """
+        if names is None:
+            names = list(self.data)
+            if not names:
+                raise ValueError("No entry exists in the data bin.")
+        else:
+            names = list(names)
+            if not names:
+                raise ValueError("An empty name list is given.")
+            for name in names:
+                if name not in self.data:
+                    raise ValueError(f"Name '{name}' does not exist.")
+
+        data = [self.data[name] for name in names]
+        if isinstance(data[0], BitArray):
+            if not all(isinstance(datum, BitArray) for datum in data):
+                raise TypeError("Data comes from incompatible types.")
+            joint_data = BitArray.concatenate_bits(data)
+        elif isinstance(data[0], np.ndarray):
+            if not all(isinstance(datum, np.ndarray) for datum in data):
+                raise TypeError("Data comes from incompatible types.")
+            joint_data = np.concatenate(data, axis=-1)
+        else:
+            raise TypeError("Data comes from incompatible types.")
+        return joint_data