qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/primitives/base/base_primitive_v1.py

@@ -0,0 +1,45 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# 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.
+
+"""Primitive V1 abstract base class."""
+
+from __future__ import annotations
+
+from abc import ABC
+
+from qiskit.providers import Options
+
+
+class BasePrimitiveV1(ABC):
+    """Primitive V1 abstract base class."""
+
+    def __init__(self, options: dict | None = None):
+        self._run_options = Options()
+        if options is not None:
+            self._run_options.update_options(**options)
+
+    @property
+    def options(self) -> Options:
+        """Return options values for the estimator.
+
+        Returns:
+            options
+        """
+        return self._run_options
+
+    def set_options(self, **fields):
+        """Set options values for the estimator.
+
+        Args:
+            **fields: The fields to update the options
+        """
+        self._run_options.update_options(**fields)

qiskit/primitives/base/base_result_v1.py

@@ -0,0 +1,65 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# 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.
+"""
+Primitive V1 result abstract base class
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from collections.abc import Sequence
+from dataclasses import fields
+from typing import Any, Dict
+
+from numpy import ndarray
+
+ExperimentData = Dict[str, Any]
+
+
+class _BasePrimitiveResultV1(ABC):
+    """
+    Base class for deprecated Primitive V1 result methods.
+    """
+
+    def __post_init__(self) -> None:
+        """
+        Verify that all fields in any inheriting result dataclass are consistent, after
+        instantiation, with the number of experiments being represented.
+
+        This magic method is specific of `dataclasses.dataclass`, therefore all inheriting
+        classes must have this decorator.
+
+        Raises:
+            TypeError: If one of the data fields is not a Sequence or ``numpy.ndarray``.
+            ValueError: Inconsistent number of experiments across data fields.
+        """
+        num_experiments = None
+        for value in self._field_values:  # type: Sequence
+            if num_experiments is None:
+                num_experiments = len(value)
+            # TODO: enforce all data fields to be tuples instead of sequences
+            if not isinstance(value, (Sequence, ndarray)) or isinstance(value, (str, bytes)):
+                raise TypeError(
+                    f"Expected sequence or `numpy.ndarray`, provided {type(value)} instead."
+                )
+            if len(value) != num_experiments:
+                raise ValueError("Inconsistent number of experiments across data fields.")
+
+    @property  # TODO: functools.cached_property when py37 is dropped
+    def _field_names(self) -> tuple[str, ...]:
+        """Tuple of field names in any inheriting result dataclass."""
+        return tuple(field.name for field in fields(self))
+
+    @property  # TODO: functools.cached_property when py37 is dropped
+    def _field_values(self) -> tuple:
+        """Tuple of field values in any inheriting result dataclass."""
+        return tuple(getattr(self, name) for name in self._field_names)

qiskit/primitives/base/base_sampler.py

@@ -0,0 +1,196 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# 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 Sampler V1 and V2 classes"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable, Sequence
+from copy import copy
+from typing import Generic, TypeVar
+
+from qiskit.circuit import QuantumCircuit
+from qiskit.providers import JobV1 as Job
+
+from ..containers.primitive_result import PrimitiveResult
+from ..containers.sampler_pub import SamplerPubLike
+from ..containers.sampler_pub_result import SamplerPubResult
+from .validation_v1 import _validate_sampler_args
+from .base_primitive_v1 import BasePrimitiveV1
+from .base_primitive_job import BasePrimitiveJob
+
+T = TypeVar("T", bound=Job)
+
+
+class BaseSamplerV2(ABC):
+    r"""Base class for ``SamplerV2`` implementations.
+
+    A Sampler returns samples of quantum circuit outputs. Implementations of this
+    :class:`.BaseSamplerV2` interface must define their own :meth:`.run` method,
+    which is designed to take the following inputs:
+
+     * pubs: list of pubs (Primitive Unified Blocs). A sampler pub is a list or tuple
+        of two to three elements that define the unit of work for the sampler. These are:
+
+            * A single :class:`~qiskit.circuit.QuantumCircuit`, possibly parameterized.
+
+            * A collection parameter value sets to bind the circuit against if it is parametric.
+
+            * Optionally, the number of shots to sample.
+
+     * shots: the number of shots to sample. This specification is optional and will be overriden by
+        the pub-wise shots if provided.
+
+    All sampler implementations must implement default value for the ``shots`` in the
+    :meth:`.run` method. This default value will be used any time ``shots=None`` is specified, which
+    can take place in the :meth:`.run` kwargs or at the pub level.
+    """
+
+    @abstractmethod
+    def run(
+        self, pubs: Iterable[SamplerPubLike], *, shots: int | None = None
+    ) -> BasePrimitiveJob[PrimitiveResult[SamplerPubResult]]:
+        """Run and collect samples from each pub.
+
+        Args:
+            pubs: An iterable of pub-like objects. For example, a list of circuits
+                  or tuples ``(circuit, parameter_values)``.
+            shots: The total number of shots to sample for each sampler pub that does
+                   not specify its own shots. If ``None``, the primitive's default
+                   shots value will be used, which can vary by implementation.
+
+        Returns:
+            The job object of Sampler's result.
+        """
+
+
+class BaseSamplerV1(BasePrimitiveV1, Generic[T]):
+    r"""Sampler V1 base class
+
+    Base class of Sampler that calculates quasi-probabilities of bitstrings from quantum circuits.
+
+    A sampler is initialized with an empty parameter set. The sampler is used to
+    create a :class:`~qiskit.providers.JobV1`, via the :meth:`qiskit.primitives.Sampler.run()`
+    method. This method is called with the following parameters
+
+    * quantum circuits (:math:`\psi_i(\theta)`): list of (parameterized) quantum circuits.
+      (a list of :class:`~qiskit.circuit.QuantumCircuit` objects)
+
+    * parameter values (:math:`\theta_k`): list of sets of parameter values
+      to be bound to the parameters of the quantum circuits.
+      (list of list of float)
+
+    The method returns a :class:`~qiskit.providers.JobV1` object, calling
+    :meth:`qiskit.providers.JobV1.result()` yields a :class:`~qiskit.primitives.SamplerResult`
+    object, which contains probabilities or quasi-probabilities of bitstrings,
+    plus optional metadata like error bars in the samples.
+
+    Here is an example of how sampler is used.
+
+    .. code-block:: python
+
+        # This is a fictional import path.
+        # There are currently no Sampler implementations in Qiskit.
+        from sampler_v1_location import SamplerV1
+        from qiskit import QuantumCircuit
+        from qiskit.circuit.library import RealAmplitudes
+
+        # a Bell circuit
+        bell = QuantumCircuit(2)
+        bell.h(0)
+        bell.cx(0, 1)
+        bell.measure_all()
+
+        # two parameterized circuits
+        pqc = RealAmplitudes(num_qubits=2, reps=2)
+        pqc.measure_all()
+        pqc2 = RealAmplitudes(num_qubits=2, reps=3)
+        pqc2.measure_all()
+
+        theta1 = [0, 1, 1, 2, 3, 5]
+        theta2 = [0, 1, 2, 3, 4, 5, 6, 7]
+
+        # initialization of the sampler
+        sampler = Sampler()
+
+        # Sampler runs a job on the Bell circuit
+        job = sampler.run(circuits=[bell], parameter_values=[[]], parameters=[[]])
+        job_result = job.result()
+        print([q.binary_probabilities() for q in job_result.quasi_dists])
+
+        # Sampler runs a job on the parameterized circuits
+        job2 = sampler.run(
+            circuits=[pqc, pqc2],
+            parameter_values=[theta1, theta2],
+            parameters=[pqc.parameters, pqc2.parameters])
+        job_result = job2.result()
+        print([q.binary_probabilities() for q in job_result.quasi_dists])
+
+    """
+
+    __hash__ = None
+
+    def __init__(
+        self,
+        *,
+        options: dict | None = None,
+    ):
+        """
+        Initialize ``SamplerV1``.
+
+        Args:
+            options: Default options.
+        """
+        super().__init__(options)
+
+    def run(
+        self,
+        circuits: QuantumCircuit | Sequence[QuantumCircuit],
+        parameter_values: Sequence[float] | Sequence[Sequence[float]] | None = None,
+        **run_options,
+    ) -> T:
+        """Run the job of the sampling of bitstrings.
+
+        Args:
+            circuits: One of more circuit objects.
+            parameter_values: Parameters to be bound to the circuit.
+            run_options: Backend runtime options used for circuit execution.
+
+        Returns:
+            The job object of the result of the sampler. The i-th result corresponds to
+            ``circuits[i]`` evaluated with parameters bound as ``parameter_values[i]``.
+
+        Raises:
+            ValueError: Invalid arguments are given.
+        """
+        # Validation
+        circuits, parameter_values = _validate_sampler_args(circuits, parameter_values)
+
+        # Options
+        run_opts = copy(self.options)
+        run_opts.update_options(**run_options)
+
+        return self._run(
+            circuits,
+            parameter_values,
+            **run_opts.__dict__,
+        )
+
+    @abstractmethod
+    def _run(
+        self,
+        circuits: tuple[QuantumCircuit, ...],
+        parameter_values: tuple[tuple[float, ...], ...],
+        **run_options,
+    ) -> T:
+        raise NotImplementedError("The subclass of BaseSamplerV1 must implement `_run` method.")

qiskit/primitives/base/estimator_result_v1.py

@@ -0,0 +1,46 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# 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 V1 result class
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .base_result_v1 import _BasePrimitiveResultV1
+
+if TYPE_CHECKING:
+    import numpy as np
+
+
+@dataclass(frozen=True)
+class EstimatorResult(_BasePrimitiveResultV1):
+    """Result of Estimator V1.
+
+    .. code-block:: python
+
+        result = estimator.run(circuits, observables, params).result()
+
+    where the i-th elements of ``result`` correspond to the circuit and observable given by
+    ``circuits[i]``, ``observables[i]``, and the parameter values bounds by ``params[i]``.
+    For example, ``results.values[i]`` gives the expectation value, and ``result.metadata[i]``
+    is a metadata dictionary for this circuit and parameters.
+
+    Args:
+        values (np.ndarray): The array of the expectation values.
+        metadata (list[dict]): List of the metadata.
+    """
+
+    values: "np.ndarray[Any, np.dtype[np.float64]]"
+    metadata: list[dict[str, Any]]

qiskit/primitives/base/sampler_result_v1.py

@@ -0,0 +1,45 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# 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 V1 result class
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from qiskit.result import QuasiDistribution
+
+from .base_result_v1 import _BasePrimitiveResultV1
+
+
+@dataclass(frozen=True)
+class SamplerResult(_BasePrimitiveResultV1):
+    """Result of Sampler V1.
+
+    .. code-block:: python
+
+        result = sampler.run(circuits, params).result()
+
+    where the i-th elements of ``result`` correspond to the circuit given by ``circuits[i]``,
+    and the parameter values bounds by ``params[i]``.
+    For example, ``results.quasi_dists[i]`` gives the quasi-probabilities of bitstrings, and
+    ``result.metadata[i]`` is a metadata dictionary for this circuit and parameters.
+
+    Args:
+        quasi_dists (list[QuasiDistribution]): List of the quasi-probabilities.
+        metadata (list[dict]): List of the metadata.
+    """
+
+    quasi_dists: list[QuasiDistribution]
+    metadata: list[dict[str, Any]]

qiskit/primitives/base/validation_v1.py

@@ -0,0 +1,250 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# 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.
+
+"""Primitive V1 validation methods.
+
+Note that these are not intended to be part of the public API of base primitives
+but are here for backward compatibility with BaseSamplerV1 and BaseEstimatorV1 classes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+import numpy as np
+
+from qiskit.circuit import QuantumCircuit, ControlFlowOp, Measure
+from qiskit.exceptions import QiskitError
+from qiskit.quantum_info import PauliList, SparsePauliOp
+from qiskit.quantum_info.operators.base_operator import BaseOperator
+from qiskit.quantum_info.operators.symplectic.base_pauli import BasePauli
+
+
+def _validate_estimator_args(
+    circuits: Sequence[QuantumCircuit] | QuantumCircuit,
+    observables: Sequence[BaseOperator | str] | BaseOperator | str,
+    parameter_values: Sequence[Sequence[float]] | Sequence[float] | float | None = None,
+) -> tuple[tuple[QuantumCircuit], tuple[BaseOperator], tuple[tuple[float]]]:
+    """Validate run arguments for BaseEstimatorV1.
+
+    Args:
+        circuits: one or more circuit objects.
+        observables: one or more observable objects.
+        parameter_values: concrete parameters to be bound.
+
+    Returns:
+        The formatted arguments ``(circuits, observables, parameter_values)``.
+
+    Raises:
+        TypeError: If input arguments are invalid types.
+        ValueError: if input arguments are invalid values.
+    """
+    # Singular validation
+    circuits = _validate_circuits(circuits)
+    observables = _validate_observables(observables)
+    parameter_values = _validate_parameter_values(
+        parameter_values,
+        default=[()] * len(circuits),
+    )
+
+    # Cross-validation
+    _cross_validate_circuits_parameter_values(circuits, parameter_values)
+    _cross_validate_circuits_observables(circuits, observables)
+
+    return circuits, observables, parameter_values
+
+
+def _validate_sampler_args(
+    circuits: Sequence[QuantumCircuit] | QuantumCircuit,
+    parameter_values: Sequence[Sequence[float]] | Sequence[float] | float | None = None,
+) -> tuple[tuple[QuantumCircuit], tuple[BaseOperator], tuple[tuple[float]]]:
+    """Validate run arguments for BaseSamplerV1.
+
+    Args:
+        circuits: one or more circuit objects.
+        parameter_values: concrete parameters to be bound.
+
+    Returns:
+        The formatted arguments ``(circuits, parameter_values)``.
+
+    Raises:
+        TypeError: If input arguments are invalid types.
+        ValueError: if input arguments are invalid values.
+    """
+    # Singular validation
+    circuits = _validate_circuits(circuits, requires_measure=True)
+    parameter_values = _validate_parameter_values(
+        parameter_values,
+        default=[()] * len(circuits),
+    )
+
+    # Cross-validation
+    _cross_validate_circuits_parameter_values(circuits, parameter_values)
+
+    return circuits, parameter_values
+
+
+def _init_observable(observable: BaseOperator | str) -> SparsePauliOp:
+    """Initialize observable by converting the input to a :class:`~qiskit.quantum_info.SparsePauliOp`.
+
+    Args:
+        observable: The observable.
+
+    Returns:
+        The observable as :class:`~qiskit.quantum_info.SparsePauliOp`.
+
+    Raises:
+        QiskitError: when observable type cannot be converted to SparsePauliOp.
+    """
+
+    if isinstance(observable, SparsePauliOp):
+        return observable
+    elif isinstance(observable, BaseOperator) and not isinstance(observable, BasePauli):
+        raise QiskitError(f"observable type not supported: {type(observable)}")
+    else:
+        if isinstance(observable, PauliList):
+            raise QiskitError(f"observable type not supported: {type(observable)}")
+        return SparsePauliOp(observable)
+
+
+def _validate_circuits(
+    circuits: Sequence[QuantumCircuit] | QuantumCircuit,
+    requires_measure: bool = False,
+) -> tuple[QuantumCircuit, ...]:
+    if isinstance(circuits, QuantumCircuit):
+        circuits = (circuits,)
+    elif not isinstance(circuits, Sequence) or not all(
+        isinstance(cir, QuantumCircuit) for cir in circuits
+    ):
+        raise TypeError("Invalid circuits, expected Sequence[QuantumCircuit].")
+    elif not isinstance(circuits, tuple):
+        circuits = tuple(circuits)
+    if len(circuits) == 0:
+        raise ValueError("No circuits were provided.")
+
+    if requires_measure:
+        for i, circuit in enumerate(circuits):
+            if circuit.num_clbits == 0:
+                raise ValueError(
+                    f"The {i}-th circuit does not have any classical bit. "
+                    "Sampler requires classical bits, plus measurements "
+                    "on the desired qubits."
+                )
+            if not _has_measure(circuit):
+                raise ValueError(
+                    f"The {i}-th circuit does not have Measure instruction. "
+                    "Without measurements, the circuit cannot be sampled from."
+                )
+    return circuits
+
+
+def _validate_parameter_values(
+    parameter_values: Sequence[Sequence[float]] | Sequence[float] | float | None,
+    default: Sequence[Sequence[float]] | Sequence[float] | None = None,
+) -> tuple[tuple[float, ...], ...]:
+    # Allow optional (if default)
+    if parameter_values is None:
+        if default is None:
+            raise ValueError("No default `parameter_values`, optional input disallowed.")
+        parameter_values = default
+
+    # Support numpy ndarray
+    if isinstance(parameter_values, np.ndarray):
+        parameter_values = parameter_values.tolist()
+    elif isinstance(parameter_values, Sequence):
+        parameter_values = tuple(
+            vector.tolist() if isinstance(vector, np.ndarray) else vector
+            for vector in parameter_values
+        )
+
+    # Allow single value
+    if _isreal(parameter_values):
+        parameter_values = ((parameter_values,),)
+    elif isinstance(parameter_values, Sequence) and not any(
+        isinstance(vector, Sequence) for vector in parameter_values
+    ):
+        parameter_values = (parameter_values,)
+
+    # Validation
+    if (
+        not isinstance(parameter_values, Sequence)
+        or not all(isinstance(vector, Sequence) for vector in parameter_values)
+        or not all(all(_isreal(value) for value in vector) for vector in parameter_values)
+    ):
+        raise TypeError("Invalid parameter values, expected Sequence[Sequence[float]].")
+
+    return tuple(tuple(float(value) for value in vector) for vector in parameter_values)
+
+
+def _validate_observables(
+    observables: Sequence[BaseOperator | str] | BaseOperator | str,
+) -> tuple[SparsePauliOp, ...]:
+    if isinstance(observables, str) or not isinstance(observables, Sequence):
+        observables = (observables,)
+    if len(observables) == 0:
+        raise ValueError("No observables were provided.")
+    return tuple(_init_observable(obs) for obs in observables)
+
+
+def _cross_validate_circuits_parameter_values(
+    circuits: tuple[QuantumCircuit, ...], parameter_values: tuple[tuple[float, ...], ...]
+) -> None:
+    if len(circuits) != len(parameter_values):
+        raise ValueError(
+            f"The number of circuits ({len(circuits)}) does not match "
+            f"the number of parameter value sets ({len(parameter_values)})."
+        )
+    for i, (circuit, vector) in enumerate(zip(circuits, parameter_values)):
+        if len(vector) != circuit.num_parameters:
+            raise ValueError(
+                f"The number of values ({len(vector)}) does not match "
+                f"the number of parameters ({circuit.num_parameters}) for the {i}-th circuit."
+            )
+
+
+def _cross_validate_circuits_observables(
+    circuits: tuple[QuantumCircuit, ...], observables: tuple[BaseOperator, ...]
+) -> None:
+    if len(circuits) != len(observables):
+        raise ValueError(
+            f"The number of circuits ({len(circuits)}) does not match "
+            f"the number of observables ({len(observables)})."
+        )
+    for i, (circuit, observable) in enumerate(zip(circuits, observables)):
+        if circuit.num_qubits != observable.num_qubits:
+            raise ValueError(
+                f"The number of qubits of the {i}-th circuit ({circuit.num_qubits}) does "
+                f"not match the number of qubits of the {i}-th observable "
+                f"({observable.num_qubits})."
+            )
+
+
+def _isint(obj: Sequence[Sequence[float]] | Sequence[float] | float) -> bool:
+    """Check if object is int."""
+    int_types = (int, np.integer)
+    return isinstance(obj, int_types) and not isinstance(obj, bool)
+
+
+def _isreal(obj: Sequence[Sequence[float]] | Sequence[float] | float) -> bool:
+    """Check if object is a real number: int or float except ``±Inf`` and ``NaN``."""
+    float_types = (float, np.floating)
+    return _isint(obj) or isinstance(obj, float_types) and float("-Inf") < obj < float("Inf")
+
+
+def _has_measure(circuit: QuantumCircuit) -> bool:
+    for instruction in reversed(circuit):
+        if isinstance(instruction.operation, Measure):
+            return True
+        elif isinstance(instruction.operation, ControlFlowOp):
+            for block in instruction.operation.blocks:
+                if _has_measure(block):
+                    return True
+    return False

qiskit/primitives/containers/__init__.py

@@ -0,0 +1,26 @@
+# 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 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 .primitive_result import PrimitiveResult
+from .pub_result import PubResult
+from .sampler_pub import SamplerPubLike
+from .sampler_pub_result import SamplerPubResult