qiskit 1.0.0b1__cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

qiskit/primitives/base/base_sampler.py

@@ -0,0 +1,202 @@
+# 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.
+
+r"""
+===================
+Overview of Sampler
+===================
+
+Sampler class calculates probabilities or 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
+
+    from qiskit.primitives import Sampler
+    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])
+"""
+
+from __future__ import annotations
+
+import warnings
+from abc import abstractmethod
+from collections.abc import Sequence
+from copy import copy
+from typing import Generic, TypeVar
+
+from qiskit.utils.deprecation import deprecate_func
+from qiskit.circuit import QuantumCircuit
+from qiskit.circuit.parametertable import ParameterView
+from qiskit.providers import JobV1 as Job
+
+from .base_primitive import BasePrimitive
+from . import validation
+
+T = TypeVar("T", bound=Job)
+
+
+class BaseSampler(BasePrimitive, Generic[T]):
+    """Sampler base class
+
+    Base class of Sampler that calculates quasi-probabilities of bitstrings from quantum circuits.
+    """
+
+    __hash__ = None
+
+    def __init__(
+        self,
+        *,
+        options: dict | None = None,
+    ):
+        """
+        Args:
+            options: Default options.
+        """
+        super().__init__(options)
+
+    def __getattr__(self, name: str) -> any:
+        # Work around to enable deprecation of the init attributes in BaseSampler incase
+        # existing subclasses depend on them (which some do)
+        dep_defaults = {
+            "_circuits": [],
+            "_parameters": [],
+        }
+        if name not in dep_defaults:
+            raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'")
+
+        warnings.warn(
+            f"The init attribute `{name}` in BaseSampler is deprecated as of Qiskit 0.46."
+            " To continue to use this attribute in a subclass and avoid this warning the"
+            " subclass should initialize it itself.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        setattr(self, name, dep_defaults[name])
+        return getattr(self, name)
+
+    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 = validation._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 BaseSampler must implement `_run` method.")
+
+    @classmethod
+    @deprecate_func(since="0.46.0")
+    def _validate_circuits(
+        cls,
+        circuits: Sequence[QuantumCircuit] | QuantumCircuit,
+    ) -> tuple[QuantumCircuit, ...]:
+        return validation._validate_circuits(circuits, requires_measure=True)
+
+    @property
+    @deprecate_func(since="0.46.0", is_property=True)
+    def circuits(self) -> tuple[QuantumCircuit, ...]:
+        """Quantum circuits to be sampled.
+
+        Returns:
+            The quantum circuits to be sampled.
+        """
+        return tuple(self._circuits)
+
+    @property
+    @deprecate_func(since="0.46.0", is_property=True)
+    def parameters(self) -> tuple[ParameterView, ...]:
+        """Parameters of quantum circuits.
+
+        Returns:
+            List of the parameters in each quantum circuit.
+        """
+        return tuple(self._parameters)

qiskit/primitives/base/estimator_result.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 result class
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .base_result import BasePrimitiveResult
+
+if TYPE_CHECKING:
+    import numpy as np
+
+
+@dataclass(frozen=True)
+class EstimatorResult(BasePrimitiveResult):
+    """Result of Estimator.
+
+    .. 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.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 result class
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from qiskit.result import QuasiDistribution
+
+from .base_result import BasePrimitiveResult
+
+
+@dataclass(frozen=True)
+class SamplerResult(BasePrimitiveResult):
+    """Result of Sampler.
+
+    .. 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.py

@@ -0,0 +1,231 @@
+# 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 validation methods.
+
+Note that these are not intended to be part of the public API of base primitives
+but are here for backwards compatibility with deprecated functions.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+import typing
+import numpy as np
+
+from qiskit.circuit import QuantumCircuit, ControlFlowOp, Measure
+from qiskit.quantum_info.operators import SparsePauliOp
+from qiskit.quantum_info.operators.base_operator import BaseOperator
+
+from ..utils import init_observable
+
+if typing.TYPE_CHECKING:
+    from qiskit.opflow import PauliSumOp
+
+
+def _validate_estimator_args(
+    circuits: Sequence[QuantumCircuit] | QuantumCircuit,
+    observables: Sequence[BaseOperator | PauliSumOp | str] | BaseOperator | PauliSumOp | str,
+    parameter_values: Sequence[Sequence[float]] | Sequence[float] | float | None = None,
+) -> tuple[tuple[QuantumCircuit], tuple[BaseOperator], tuple[tuple[float]]]:
+    """Validate run arguments for a reference Estimator.
+
+    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 a reference Sampler.
+
+    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 _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 | PauliSumOp | str] | BaseOperator | PauliSumOp | 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 | PauliSumOp, ...]
+) -> 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/estimator.py

@@ -0,0 +1,158 @@
+# 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 class
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+import numpy as np
+
+from qiskit.circuit import QuantumCircuit
+from qiskit.exceptions import QiskitError
+from qiskit.quantum_info import Statevector
+from qiskit.quantum_info.operators.base_operator import BaseOperator
+
+from .base import BaseEstimator, EstimatorResult
+from .primitive_job import PrimitiveJob
+from .utils import (
+    _circuit_key,
+    _observable_key,
+    bound_circuit_to_instruction,
+    init_observable,
+)
+
+
+class Estimator(BaseEstimator[PrimitiveJob[EstimatorResult]]):
+    """
+    Reference implementation of :class:`BaseEstimator`.
+
+    :Run Options:
+
+        - **shots** (None or int) --
+          The number of shots. If None, it calculates the exact expectation
+          values. Otherwise, it samples from normal distributions with standard errors as standard
+          deviations using normal distribution approximation.
+
+        - **seed** (np.random.Generator or int) --
+          Set a fixed seed or generator for the normal distribution. If shots is None,
+          this option is ignored.
+    """
+
+    def __init__(self, *, options: dict | None = None):
+        """
+        Args:
+            options: Default options.
+
+        Raises:
+            QiskitError: if some classical bits are not used for measurements.
+        """
+        super().__init__(options=options)
+        self._circuits = []
+        self._parameters = []
+        self._observables = []
+        self._circuit_ids = {}
+        self._observable_ids = {}
+
+    def _call(
+        self,
+        circuits: Sequence[int],
+        observables: Sequence[int],
+        parameter_values: Sequence[Sequence[float]],
+        **run_options,
+    ) -> EstimatorResult:
+        shots = run_options.pop("shots", None)
+        seed = run_options.pop("seed", None)
+        if seed is None:
+            rng = np.random.default_rng()
+        elif isinstance(seed, np.random.Generator):
+            rng = seed
+        else:
+            rng = np.random.default_rng(seed)
+
+        # Initialize metadata
+        metadata: list[dict[str, Any]] = [{} for _ in range(len(circuits))]
+
+        bound_circuits = []
+        for i, value in zip(circuits, parameter_values):
+            if len(value) != len(self._parameters[i]):
+                raise QiskitError(
+                    f"The number of values ({len(value)}) does not match "
+                    f"the number of parameters ({len(self._parameters[i])})."
+                )
+            bound_circuits.append(
+                self._circuits[i]
+                if len(value) == 0
+                else self._circuits[i].assign_parameters(dict(zip(self._parameters[i], value)))
+            )
+        sorted_observables = [self._observables[i] for i in observables]
+        expectation_values = []
+        for circ, obs, metadatum in zip(bound_circuits, sorted_observables, metadata):
+            if circ.num_qubits != obs.num_qubits:
+                raise QiskitError(
+                    f"The number of qubits of a circuit ({circ.num_qubits}) does not match "
+                    f"the number of qubits of a observable ({obs.num_qubits})."
+                )
+            final_state = Statevector(bound_circuit_to_instruction(circ))
+            expectation_value = final_state.expectation_value(obs)
+            if shots is None:
+                expectation_values.append(expectation_value)
+            else:
+                expectation_value = np.real_if_close(expectation_value)
+                sq_obs = (obs @ obs).simplify(atol=0)
+                sq_exp_val = np.real_if_close(final_state.expectation_value(sq_obs))
+                variance = sq_exp_val - expectation_value**2
+                variance = max(variance, 0)
+                standard_error = np.sqrt(variance / shots)
+                expectation_value_with_error = rng.normal(expectation_value, standard_error)
+                expectation_values.append(expectation_value_with_error)
+                metadatum["variance"] = variance
+                metadatum["shots"] = shots
+
+        return EstimatorResult(np.real_if_close(expectation_values), metadata)
+
+    def _run(
+        self,
+        circuits: tuple[QuantumCircuit, ...],
+        observables: tuple[BaseOperator, ...],
+        parameter_values: tuple[tuple[float, ...], ...],
+        **run_options,
+    ):
+        circuit_indices = []
+        for circuit in circuits:
+            key = _circuit_key(circuit)
+            index = self._circuit_ids.get(key)
+            if index is not None:
+                circuit_indices.append(index)
+            else:
+                circuit_indices.append(len(self._circuits))
+                self._circuit_ids[key] = len(self._circuits)
+                self._circuits.append(circuit)
+                self._parameters.append(circuit.parameters)
+        observable_indices = []
+        for observable in observables:
+            observable = init_observable(observable)
+            index = self._observable_ids.get(_observable_key(observable))
+            if index is not None:
+                observable_indices.append(index)
+            else:
+                observable_indices.append(len(self._observables))
+                self._observable_ids[_observable_key(observable)] = len(self._observables)
+                self._observables.append(observable)
+        job = PrimitiveJob(
+            self._call, circuit_indices, observable_indices, parameter_values, **run_options
+        )
+        job.submit()
+        return job