10142527079

Committed 29 Jul 2024 10:24AM UTC coverage: 89.919% (-0.04%) from 89.955%

Build # 10142527079

Build Type

Pull #12835

github

Committed by

mergify[bot]

Commit Message

Primitive V1 deprecation follow-up (#12824)

* Apply tweaks to deprecation messages, docstrings and release notes.

* Fix missing backtick

* Apply suggestions from Luciano's code review

Co-authored-by: Luciano Bello <bel@zurich.ibm.com>

* Update qiskit/primitives/statevector_sampler.py

Co-authored-by: Luciano Bello <bel@zurich.ibm.com>

* Update qiskit/primitives/backend_sampler.py

Co-authored-by: Luciano Bello <bel@zurich.ibm.com>

* Update qiskit/primitives/primitive_job.py

Co-authored-by: Takashi Imamichi <31178928+t-imamichi@users.noreply.github.com>

* Update qiskit/primitives/base/base_estimator.py

Co-authored-by: Takashi Imamichi <31178928+t-imamichi@users.noreply.github.com>

---------

Co-authored-by: Luciano Bello <bel@zurich.ibm.com>
Co-authored-by: Takashi Imamichi <31178928+t-imamichi@users.noreply.github.com>
(cherry picked from commit b7d0a974b)

Pull Request Pull Request #12835: Primitive V1 deprecation follow-up (backport #12824)

Run Details

21 of 21 new or added lines in 6 files covered. (100.0%)

35 existing lines in 4 files now uncovered.

66151 of 73567 relevant lines covered (89.92%)

302189.55 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

96.97

/qiskit/primitives/base/base_sampler.py

# 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 qiskit.utils.deprecation import deprecate_func

from ..containers.primitive_result import PrimitiveResult
from ..containers.sampler_pub import SamplerPubLike
from ..containers.sampler_pub_result import SamplerPubResult
from . import validation
from .base_primitive import BasePrimitive
from .base_primitive_job import BasePrimitiveJob

T = TypeVar("T", bound=Job)


class BaseSamplerV1(BasePrimitive, 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

        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])

    """

    __hash__ = None

    def __init__(
        self,
        *,
        options: dict | None = None,
    ):
        """
        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 = 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.")


class BaseSampler(BaseSamplerV1[T]):
    """DEPRECATED. Type alias for Sampler V1 base class

    See :class:`.BaseSamplerV1` for details.
    """

    @deprecate_func(
        since="1.2",
        additional_msg="The `BaseSampler` class is a type alias for the `BaseSamplerV1` "
        "interface that has been deprecated in favor of explicitly versioned interface classes. "
        "It is recommended to migrate all implementations to use `BaseSamplerV2`. "
        "However, for implementations incompatible with `BaseSamplerV2`, `BaseSampler` can "
        "be replaced with the explicitly versioned `BaseSamplerV1` class.",
    )
    def __init__(
        self,
        *,
        options: dict | None = None,
    ):
        """
        Args:
            options: Default options.
        """
        super().__init__(options=options)


class BaseSamplerV2(ABC):
    r"""Sampler V2 base class.

    A Sampler returns samples of quantum circuit outputs.

    All sampler implementations must implement default value for the ``shots`` in the
    :meth:`.run` method if ``None`` is given both as a ``kwarg`` and in all of the pubs.
    """

    @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.
        """

1	# This code is part of Qiskit.
2	#
3	# (C) Copyright IBM 2022.
4	#
5	# This code is licensed under the Apache License, Version 2.0. You may
6	# obtain a copy of this license in the LICENSE.txt file in the root directory
7	# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
8	#
9	# Any modifications or derivative works of this code must retain this
10	# copyright notice, and modified files need to carry a notice indicating
11	# that they have been altered from the originals.
12
13	"""Base Sampler V1 and V2 classes"""	1✔
14
15	from __future__ import annotations	1✔
16
17	from abc import ABC, abstractmethod	1✔
18	from collections.abc import Iterable, Sequence	1✔
19	from copy import copy	1✔
20	from typing import Generic, TypeVar	1✔
21
22	from qiskit.circuit import QuantumCircuit	1✔
23	from qiskit.providers import JobV1 as Job	1✔
24	from qiskit.utils.deprecation import deprecate_func	1✔
25
26	from ..containers.primitive_result import PrimitiveResult	1✔
27	from ..containers.sampler_pub import SamplerPubLike	1✔
28	from ..containers.sampler_pub_result import SamplerPubResult	1✔
29	from . import validation	1✔
30	from .base_primitive import BasePrimitive	1✔
31	from .base_primitive_job import BasePrimitiveJob	1✔
32
33	T = TypeVar("T", bound=Job)	1✔
34
35
36	class BaseSamplerV1(BasePrimitive, Generic[T]):	1✔
37	r"""Sampler V1 base class	1✔
38
39	Base class of Sampler that calculates quasi-probabilities of bitstrings from quantum circuits.
40
41	A sampler is initialized with an empty parameter set. The sampler is used to
42	create a :class:`~qiskit.providers.JobV1`, via the :meth:`qiskit.primitives.Sampler.run()`
43	method. This method is called with the following parameters
44
45	* quantum circuits (:math:`\psi_i(\theta)`): list of (parameterized) quantum circuits.
46	(a list of :class:`~qiskit.circuit.QuantumCircuit` objects)
47
48	* parameter values (:math:`\theta_k`): list of sets of parameter values
49	to be bound to the parameters of the quantum circuits.
50	(list of list of float)
51
52	The method returns a :class:`~qiskit.providers.JobV1` object, calling
53	:meth:`qiskit.providers.JobV1.result()` yields a :class:`~qiskit.primitives.SamplerResult`
54	object, which contains probabilities or quasi-probabilities of bitstrings,
55	plus optional metadata like error bars in the samples.
56
57	Here is an example of how sampler is used.
58
59	.. code-block:: python
60
61	from qiskit.primitives import Sampler
62	from qiskit import QuantumCircuit
63	from qiskit.circuit.library import RealAmplitudes
64
65	# a Bell circuit
66	bell = QuantumCircuit(2)
67	bell.h(0)
68	bell.cx(0, 1)
69	bell.measure_all()
70
71	# two parameterized circuits
72	pqc = RealAmplitudes(num_qubits=2, reps=2)
73	pqc.measure_all()
74	pqc2 = RealAmplitudes(num_qubits=2, reps=3)
75	pqc2.measure_all()
76
77	theta1 = [0, 1, 1, 2, 3, 5]
78	theta2 = [0, 1, 2, 3, 4, 5, 6, 7]
79
80	# initialization of the sampler
81	sampler = Sampler()
82
83	# Sampler runs a job on the Bell circuit
84	job = sampler.run(circuits=[bell], parameter_values=[[]], parameters=[[]])
85	job_result = job.result()
86	print([q.binary_probabilities() for q in job_result.quasi_dists])
87
88	# Sampler runs a job on the parameterized circuits
89	job2 = sampler.run(
90	circuits=[pqc, pqc2],
91	parameter_values=[theta1, theta2],
92	parameters=[pqc.parameters, pqc2.parameters])
93	job_result = job2.result()
94	print([q.binary_probabilities() for q in job_result.quasi_dists])
95
96	"""
97
98	__hash__ = None	1✔
99
100	def __init__(	1✔
101	self,
102	*,
103	options: dict \| None = None,
104	):
105	"""
106	Args:
107	options: Default options.
108	"""
109	super().__init__(options)	1✔
110
111	def run(	1✔
112	self,
113	circuits: QuantumCircuit \| Sequence[QuantumCircuit],
114	parameter_values: Sequence[float] \| Sequence[Sequence[float]] \| None = None,
115	**run_options,
116	) -> T:
117	"""Run the job of the sampling of bitstrings.
118
119	Args:
120	circuits: One of more circuit objects.
121	parameter_values: Parameters to be bound to the circuit.
122	run_options: Backend runtime options used for circuit execution.
123
124	Returns:
125	The job object of the result of the sampler. The i-th result corresponds to
126	``circuits[i]`` evaluated with parameters bound as ``parameter_values[i]``.
127
128	Raises:
129	ValueError: Invalid arguments are given.
130	"""
131	# Validation
132	circuits, parameter_values = validation._validate_sampler_args(circuits, parameter_values)	1✔
133
134	# Options
135	run_opts = copy(self.options)	1✔
136	run_opts.update_options(**run_options)	1✔
137
138	return self._run(	1✔
139	circuits,
140	parameter_values,
141	**run_opts.__dict__,
142	)
143
144	@abstractmethod
145	def _run(
146	self,
147	circuits: tuple[QuantumCircuit, ...],
148	parameter_values: tuple[tuple[float, ...], ...],
149	**run_options,
150	) -> T:
151	raise NotImplementedError("The subclass of BaseSampler must implement `_run` method.")
152
153
154	class BaseSampler(BaseSamplerV1[T]):	1✔
155	"""DEPRECATED. Type alias for Sampler V1 base class	1✔
156
157	See :class:`.BaseSamplerV1` for details.
158	"""
159
160	@deprecate_func(	1✔
161	since="1.2",
162	additional_msg="The `BaseSampler` class is a type alias for the `BaseSamplerV1` "
163	"interface that has been deprecated in favor of explicitly versioned interface classes. "
164	"It is recommended to migrate all implementations to use `BaseSamplerV2`. "
165	"However, for implementations incompatible with `BaseSamplerV2`, `BaseSampler` can "
166	"be replaced with the explicitly versioned `BaseSamplerV1` class.",
167	)
168	def __init__(	1✔
169	self,
170	*,
171	options: dict \| None = None,
172	):
173	"""
174	Args:
175	options: Default options.
176	"""
UNCOV 177	super().__init__(options=options)	×
178
179
180	class BaseSamplerV2(ABC):	1✔
181	r"""Sampler V2 base class.	1✔
182
183	A Sampler returns samples of quantum circuit outputs.
184
185	All sampler implementations must implement default value for the ``shots`` in the
186	:meth:`.run` method if ``None`` is given both as a ``kwarg`` and in all of the pubs.
187	"""
188
189	@abstractmethod
190	def run(
191	self, pubs: Iterable[SamplerPubLike], *, shots: int \| None = None
192	) -> BasePrimitiveJob[PrimitiveResult[SamplerPubResult]]:
193	"""Run and collect samples from each pub.
194
195	Args:
196	pubs: An iterable of pub-like objects. For example, a list of circuits
197	or tuples ``(circuit, parameter_values)``.
198	shots: The total number of shots to sample for each sampler pub that does
199	not specify its own shots. If ``None``, the primitive's default
200	shots value will be used, which can vary by implementation.
201
202	Returns:
203	The job object of Sampler's result.
204	"""

Qiskit / qiskit / 10142527079

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous