qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

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

qiskit/primitives/containers/shape.py

@@ -0,0 +1,129 @@
+# 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.
+
+"""
+Array shape related classes and functions
+"""
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Protocol, Union, runtime_checkable
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+ShapeInput = Union[int, "Iterable[ShapeInput]"]
+"""An input that is coercible into a shape tuple."""
+
+
+@runtime_checkable
+class Shaped(Protocol):
+    """Protocol that defines what it means to be a shaped object.
+
+    Note that static type checkers will classify ``numpy.ndarray`` as being :class:`Shaped`.
+    Moreover, since this protocol is runtime-checkable, we will even have
+    ``isinstance(<numpy.ndarray instance>, Shaped) == True``.
+    """
+
+    @property
+    def shape(self) -> tuple[int, ...]:
+        """The array shape of this object."""
+        raise NotImplementedError("A `Shaped` protocol must implement the `shape` property")
+
+    @property
+    def ndim(self) -> int:
+        """The number of array dimensions of this object."""
+        raise NotImplementedError("A `Shaped` protocol must implement the `ndim` property")
+
+    @property
+    def size(self) -> int:
+        """The total dimension of this object, i.e. the product of the entries of :attr:`~shape`."""
+        raise NotImplementedError("A `Shaped` protocol must implement the `size` property")
+
+
+class ShapedMixin(Shaped):
+    """Mixin class to create :class:`~Shaped` types by only providing :attr:`_shape` attribute."""
+
+    _shape: tuple[int, ...]
+
+    def __repr__(self):
+        return f"{type(self).__name__}(<{self.shape}>)"
+
+    @property
+    def shape(self):
+        return self._shape
+
+    @property
+    def ndim(self):
+        return len(self._shape)
+
+    @property
+    def size(self):
+        return int(np.prod(self._shape, dtype=int))
+
+
+def array_coerce(arr: ArrayLike | Shaped) -> NDArray | Shaped:
+    """Coerce the input into an object with a shape attribute.
+
+    Copies are avoided.
+
+    Args:
+        arr: The object to coerce.
+
+    Returns:
+        Something that is :class:`~Shaped`, and always ``numpy.ndarray`` if the input is not
+        already :class:`~Shaped`.
+    """
+    if isinstance(arr, Shaped):
+        return arr
+    return np.asarray(arr)
+
+
+def _flatten_to_ints(arg: ShapeInput) -> Iterable[int]:
+    """
+    Yield one integer at a time.
+
+    Args:
+        arg: Integers or iterables of integers, possibly nested, to be yielded.
+
+    Yields:
+        The provided integers in depth-first recursive order.
+
+    Raises:
+        ValueError: If an input is not an iterable or an integer.
+    """
+    for item in arg:
+        try:
+            if isinstance(item, Iterable):
+                yield from _flatten_to_ints(item)
+            elif int(item) == item:
+                yield int(item)
+            else:
+                raise ValueError(f"Expected {item} to be iterable or an integer.")
+        except (TypeError, RecursionError) as ex:
+            raise ValueError(f"Expected {item} to be iterable or an integer.") from ex
+
+
+def shape_tuple(*shapes: ShapeInput) -> tuple[int, ...]:
+    """
+    Flatten the input into a single tuple of integers, preserving order.
+
+    Args:
+        shapes: Integers or iterables of integers, possibly nested.
+
+    Returns:
+        A tuple of integers.
+
+    Raises:
+        ValueError: If some member of ``shapes`` is not an integer or iterable.
+    """
+    return tuple(_flatten_to_ints(shapes))

qiskit/primitives/primitive_job.py

@@ -0,0 +1,100 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022, 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.
+"""
+Job for the reference implementations of Primitives V1 and V2.
+"""
+
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+
+from qiskit.providers import JobError, JobStatus
+from qiskit.providers.jobstatus import JOB_FINAL_STATES
+
+from .base.base_primitive_job import BasePrimitiveJob, ResultT
+
+
+class PrimitiveJob(BasePrimitiveJob[ResultT, JobStatus]):
+    """
+    Primitive job class for the reference implementations of Primitives.
+    """
+
+    def __init__(self, function, *args, **kwargs):
+        """
+        Args:
+            function: A callable function to execute the job.
+        """
+        super().__init__(str(uuid.uuid4()))
+        self._future = None
+        self._function = function
+        self._result = None
+        self._status = None
+        self._args = args
+        self._kwargs = kwargs
+
+    def _submit(self):
+        if self._future is not None:
+            raise JobError("Primitive job has been submitted already.")
+
+        executor = ThreadPoolExecutor(max_workers=1)  # pylint: disable=consider-using-with
+        self._future = executor.submit(self._function, *self._args, **self._kwargs)
+        executor.shutdown(wait=False)
+
+    def __getstate__(self):
+        _ = self.result()
+        _ = self.status()
+        state = self.__dict__.copy()
+        state["_future"] = None
+        return state
+
+    def __setstate__(self, state):
+        self.__dict__.update(state)
+        self._future = None
+
+    def result(self) -> ResultT:
+        if self._result is None:
+            self._check_submitted()
+            self._result = self._future.result()
+        return self._result
+
+    def status(self) -> JobStatus:
+        if self._status is None:
+            self._check_submitted()
+            if self._future.running():
+                # we should not store status running because it is not completed
+                return JobStatus.RUNNING
+            elif self._future.cancelled():
+                self._status = JobStatus.CANCELLED
+            elif self._future.done() and self._future.exception() is None:
+                self._status = JobStatus.DONE
+            else:
+                self._status = JobStatus.ERROR
+        return self._status
+
+    def _check_submitted(self):
+        if self._future is None:
+            raise JobError("Primitive Job has not been submitted yet.")
+
+    def cancel(self):
+        self._check_submitted()
+        return self._future.cancel()
+
+    def done(self) -> bool:
+        return self.status() == JobStatus.DONE
+
+    def running(self) -> bool:
+        return self.status() == JobStatus.RUNNING
+
+    def cancelled(self) -> bool:
+        return self.status() == JobStatus.CANCELLED
+
+    def in_final_state(self) -> bool:
+        return self.status() in JOB_FINAL_STATES

qiskit/primitives/statevector_estimator.py

@@ -0,0 +1,175 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023, 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.
+"""
+Statevector Estimator V2 class
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import numpy as np
+
+from qiskit.quantum_info import SparsePauliOp
+
+from .base import BaseEstimatorV2
+from .containers import DataBin, EstimatorPubLike, PrimitiveResult, PubResult
+from .containers.estimator_pub import EstimatorPub
+from .primitive_job import PrimitiveJob
+from .utils import _statevector_from_circuit
+
+
+class StatevectorEstimator(BaseEstimatorV2):
+    """
+    Simple implementation of :class:`BaseEstimatorV2` with full state vector simulation.
+
+    This class is implemented via :class:`~.Statevector` which turns provided circuits into
+    pure state vectors. These states are subsequently acted on by :class:`~.SparsePauliOp`,
+    which implies that, at present, this implementation is only compatible with Pauli-based
+    observables.
+
+    Each tuple of ``(circuit, observables, <optional> parameter values, <optional> precision)``,
+    called an estimator primitive unified bloc (PUB), produces its own array-based result. The
+    :meth:`~.EstimatorV2.run` method can be given a sequence of pubs to run in one call.
+
+    .. note::
+        The result of this class is exact if the circuit contains only unitary operations.
+        On the other hand, the result could be stochastic if the circuit contains a non-unitary
+        operation such as a reset for a some subsystems.
+        The stochastic result can be made reproducible by setting ``seed``, e.g.,
+        ``StatevectorEstimator(seed=123)``.
+
+    .. plot::
+        :alt: Output from the previous code.
+        :include-source:
+
+        from qiskit.circuit import Parameter, QuantumCircuit
+        from qiskit.primitives import StatevectorEstimator
+        from qiskit.quantum_info import Pauli, SparsePauliOp
+
+        import matplotlib.pyplot as plt
+        import numpy as np
+
+        # Define a circuit with two parameters.
+        circuit = QuantumCircuit(2)
+        circuit.h(0)
+        circuit.cx(0, 1)
+        circuit.ry(Parameter("a"), 0)
+        circuit.rz(Parameter("b"), 0)
+        circuit.cx(0, 1)
+        circuit.h(0)
+
+        # Define a sweep over parameter values, where the second axis is over
+        # the two parameters in the circuit.
+        params = np.vstack([
+            np.linspace(-np.pi, np.pi, 100),
+            np.linspace(-4 * np.pi, 4 * np.pi, 100)
+        ]).T
+
+        # Define three observables. Many formats are supported here including
+        # classes such as qiskit.quantum_info.SparsePauliOp. The inner length-1
+        # lists cause this array of observables to have shape (3, 1), rather
+        # than shape (3,) if they were omitted.
+        observables = [
+            [SparsePauliOp(["XX", "IY"], [0.5, 0.5])],
+            [Pauli("XX")],
+            [Pauli("IY")]
+        ]
+
+        # Instantiate a new statevector simulation based estimator object.
+        estimator = StatevectorEstimator()
+
+        # Estimate the expectation value for all 300 combinations of
+        # observables and parameter values, where the pub result will have
+        # shape (3, 100). This shape is due to our array of parameter
+        # bindings having shape (100,), combined with our array of observables
+        # having shape (3, 1)
+        pub = (circuit, observables, params)
+        job = estimator.run([pub])
+
+        # Extract the result for the 0th pub (this example only has one pub).
+        result = job.result()[0]
+
+        # Error-bar information is also available, but the error is 0
+        # for this StatevectorEstimator.
+        result.data.stds
+
+        # Pull out the array-based expectation value estimate data from the
+        # result and plot a trace for each observable.
+        for idx, pauli in enumerate(observables):
+            plt.plot(result.data.evs[idx], label=pauli)
+        plt.legend()
+    """
+
+    def __init__(
+        self, *, default_precision: float = 0.0, seed: np.random.Generator | int | None = None
+    ):
+        """
+        Args:
+            default_precision: The default precision for the estimator if not specified during run.
+            seed: The seed or Generator object for random number generation.
+                If None, a random seeded default RNG will be used.
+        """
+        self._default_precision = default_precision
+        self._seed = seed
+
+    @property
+    def default_precision(self) -> float:
+        """Return the default precision"""
+        return self._default_precision
+
+    @property
+    def seed(self) -> np.random.Generator | int | None:
+        """Return the seed or Generator object for random number generation."""
+        return self._seed
+
+    def run(
+        self, pubs: Iterable[EstimatorPubLike], *, precision: float | None = None
+    ) -> PrimitiveJob[PrimitiveResult[PubResult]]:
+        if precision is None:
+            precision = self._default_precision
+        coerced_pubs = [EstimatorPub.coerce(pub, precision) for pub in pubs]
+
+        job = PrimitiveJob(self._run, coerced_pubs)
+        job._submit()
+        return job
+
+    def _run(self, pubs: list[EstimatorPub]) -> PrimitiveResult[PubResult]:
+        return PrimitiveResult([self._run_pub(pub) for pub in pubs], metadata={"version": 2})
+
+    def _run_pub(self, pub: EstimatorPub) -> PubResult:
+        rng = np.random.default_rng(self._seed)
+        circuit = pub.circuit
+        observables = pub.observables
+        parameter_values = pub.parameter_values
+        precision = pub.precision
+        bound_circuits = parameter_values.bind_all(circuit)
+        bc_circuits, bc_obs = np.broadcast_arrays(bound_circuits, observables)
+        evs = np.zeros_like(bc_circuits, dtype=np.float64)
+        stds = np.zeros_like(bc_circuits, dtype=np.float64)
+        for index in np.ndindex(*bc_circuits.shape):
+            bound_circuit = bc_circuits[index]
+            observable = bc_obs[index]
+            final_state = _statevector_from_circuit(bound_circuit, rng)
+            paulis, coeffs = zip(*observable.items())
+            obs = SparsePauliOp(paulis, coeffs)  # TODO: support non Pauli operators
+            expectation_value = np.real_if_close(final_state.expectation_value(obs))
+            if precision != 0:
+                if not np.isreal(expectation_value):
+                    raise ValueError("Given operator is not Hermitian and noise cannot be added.")
+                expectation_value = rng.normal(expectation_value, precision)
+            evs[index] = expectation_value
+
+        data = DataBin(evs=evs, stds=stds, shape=evs.shape)
+        return PubResult(
+            data, metadata={"target_precision": precision, "circuit_metadata": pub.circuit.metadata}
+        )