qiskit 1.3.0__cp39-abi3-macosx_11_0_arm64.whl

qiskit/pulse/library/waveform.py

@@ -0,0 +1,136 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2020.
+#
+# 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.
+
+"""A pulse that is described by complex-valued sample points."""
+from __future__ import annotations
+from typing import Any
+
+import numpy as np
+
+from qiskit.pulse.exceptions import PulseError
+from qiskit.pulse.library.pulse import Pulse
+from qiskit.utils.deprecate_pulse import deprecate_pulse_func
+
+
+class Waveform(Pulse):
+    """A pulse specified completely by complex-valued samples; each sample is played for the
+    duration of the backend cycle-time, dt.
+    """
+
+    @deprecate_pulse_func
+    def __init__(
+        self,
+        samples: np.ndarray | list[complex],
+        name: str | None = None,
+        epsilon: float = 1e-7,
+        limit_amplitude: bool | None = None,
+    ):
+        """Create new sample pulse command.
+
+        Args:
+            samples: Complex array of the samples in the pulse envelope.
+            name: Unique name to identify the pulse.
+            epsilon: Pulse sample norm tolerance for clipping.
+                If any sample's norm exceeds unity by less than or equal to epsilon
+                it will be clipped to unit norm. If the sample
+                norm is greater than 1+epsilon an error will be raised.
+            limit_amplitude: Passed to parent Pulse
+        """
+
+        super().__init__(duration=len(samples), name=name, limit_amplitude=limit_amplitude)
+        samples = np.asarray(samples, dtype=np.complex128)
+        self.epsilon = epsilon
+        self._samples = self._clip(samples, epsilon=epsilon)
+
+    @property
+    def samples(self) -> np.ndarray:
+        """Return sample values."""
+        return self._samples
+
+    def _clip(self, samples: np.ndarray, epsilon: float = 1e-7) -> np.ndarray:
+        """If samples are within epsilon of unit norm, clip sample by reducing norm by (1-epsilon).
+
+        If difference is greater than epsilon error is raised.
+
+        Args:
+            samples: Complex array of the samples in the pulse envelope.
+            epsilon: Pulse sample norm tolerance for clipping.
+                If any sample's norm exceeds unity by less than or equal to epsilon
+                it will be clipped to unit norm. If the sample
+                norm is greater than 1+epsilon an error will be raised.
+
+        Returns:
+            Clipped pulse samples.
+
+        Raises:
+            PulseError: If there exists a pulse sample with a norm greater than 1+epsilon.
+        """
+        samples_norm = np.abs(samples)
+        to_clip = (samples_norm > 1.0) & (samples_norm <= 1.0 + epsilon)
+
+        if np.any(to_clip):
+            # first try normalizing by the abs value
+            clip_where = np.argwhere(to_clip)
+            clip_angle = np.angle(samples[clip_where])
+            clipped_samples = np.exp(1j * clip_angle, dtype=np.complex128)
+
+            # if norm still exceed one subtract epsilon
+            # required for some platforms
+            clipped_sample_norms = np.abs(clipped_samples)
+            to_clip_epsilon = clipped_sample_norms > 1.0
+            if np.any(to_clip_epsilon):
+                clip_where_epsilon = np.argwhere(to_clip_epsilon)
+                clipped_samples_epsilon = (1 - epsilon) * np.exp(
+                    1j * clip_angle[clip_where_epsilon], dtype=np.complex128
+                )
+                clipped_samples[clip_where_epsilon] = clipped_samples_epsilon
+
+            # update samples with clipped values
+            samples[clip_where] = clipped_samples
+            samples_norm[clip_where] = np.abs(clipped_samples)
+
+        if np.any(samples_norm > 1.0) and self._limit_amplitude:
+            amp = np.max(samples_norm)
+            raise PulseError(
+                f"Pulse contains sample with norm {amp} greater than 1+epsilon."
+                " This can be overruled by setting Pulse.limit_amplitude."
+            )
+
+        return samples
+
+    def is_parameterized(self) -> bool:
+        """Return True iff the instruction is parameterized."""
+        return False
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        """Return a dictionary containing the pulse's parameters."""
+        return {}
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Waveform):
+            return NotImplemented
+        return (
+            super().__eq__(other)
+            and self.samples.shape == other.samples.shape
+            and np.allclose(self.samples, other.samples, rtol=0, atol=self.epsilon)
+        )
+
+    def __hash__(self) -> int:
+        return hash(self.samples.tobytes())
+
+    def __repr__(self) -> str:
+        opt = np.get_printoptions()
+        np.set_printoptions(threshold=50)
+        np.set_printoptions(**opt)
+        name_repr = f", name='{self.name}'" if self.name is not None else ""
+        return f"{self.__class__.__name__}({repr(self.samples)}{name_repr})"

qiskit/pulse/macros.py

@@ -0,0 +1,262 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2020.
+#
+# 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.
+
+"""Module for common pulse programming macros."""
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from qiskit.pulse import channels, exceptions, instructions, utils
+from qiskit.pulse.instruction_schedule_map import InstructionScheduleMap
+from qiskit.pulse.schedule import Schedule
+from qiskit.providers.backend import BackendV2
+
+
+if TYPE_CHECKING:
+    from qiskit.transpiler import Target
+
+
+def measure(
+    qubits: Sequence[int],
+    backend=None,
+    inst_map: InstructionScheduleMap | None = None,
+    meas_map: list[list[int]] | dict[int, list[int]] | None = None,
+    qubit_mem_slots: dict[int, int] | None = None,
+    measure_name: str = "measure",
+) -> Schedule:
+    """Return a schedule which measures the requested qubits according to the given
+    instruction mapping and measure map, or by using the defaults provided by the backend.
+
+    .. note::
+        This function internally dispatches schedule generation logic depending on input backend model.
+        For the :class:`.BackendV1`, it considers conventional :class:`.InstructionScheduleMap`
+        and utilizes the backend calibration defined for a group of qubits in the `meas_map`.
+        For the :class:`.BackendV2`, it assembles calibrations of single qubit measurement
+        defined in the backend target to build a composite measurement schedule for `qubits`.
+
+    By default, the measurement results for each qubit are trivially mapped to the qubit
+    index. This behavior is overridden by qubit_mem_slots. For instance, to measure
+    qubit 0 into MemorySlot(1), qubit_mem_slots can be provided as {0: 1}.
+
+    Args:
+        qubits: List of qubits to be measured.
+        backend (Union[Backend, BaseBackend]): A backend instance, which contains
+            hardware-specific data required for scheduling.
+        inst_map: Mapping of circuit operations to pulse schedules. If None, defaults to the
+                  ``instruction_schedule_map`` of ``backend``.
+        meas_map: List of sets of qubits that must be measured together. If None, defaults to
+                  the ``meas_map`` of ``backend``.
+        qubit_mem_slots: Mapping of measured qubit index to classical bit index.
+        measure_name: Name of the measurement schedule.
+
+    Returns:
+        A measurement schedule corresponding to the inputs provided.
+    """
+
+    # backend is V2.
+    if isinstance(backend, BackendV2):
+
+        return _measure_v2(
+            qubits=qubits,
+            target=backend.target,
+            meas_map=meas_map or backend.meas_map,
+            qubit_mem_slots=qubit_mem_slots or dict(zip(qubits, range(len(qubits)))),
+            measure_name=measure_name,
+        )
+    # backend is V1 or backend is None.
+    else:
+        try:
+            return _measure_v1(
+                qubits=qubits,
+                inst_map=inst_map or backend.defaults().instruction_schedule_map,
+                meas_map=meas_map or backend.configuration().meas_map,
+                qubit_mem_slots=qubit_mem_slots,
+                measure_name=measure_name,
+            )
+        except AttributeError as ex:
+            raise exceptions.PulseError(
+                "inst_map or meas_map, and backend cannot be None simultaneously"
+            ) from ex
+
+
+def _measure_v1(
+    qubits: Sequence[int],
+    inst_map: InstructionScheduleMap,
+    meas_map: list[list[int]] | dict[int, list[int]],
+    qubit_mem_slots: dict[int, int] | None = None,
+    measure_name: str = "measure",
+) -> Schedule:
+    """Return a schedule which measures the requested qubits according to the given
+    instruction mapping and measure map, or by using the defaults provided by the backendV1.
+
+    Args:
+        qubits: List of qubits to be measured.
+        backend (Union[Backend, BaseBackend]): A backend instance, which contains
+            hardware-specific data required for scheduling.
+        inst_map: Mapping of circuit operations to pulse schedules. If None, defaults to the
+                  ``instruction_schedule_map`` of ``backend``.
+        meas_map: List of sets of qubits that must be measured together. If None, defaults to
+                  the ``meas_map`` of ``backend``.
+        qubit_mem_slots: Mapping of measured qubit index to classical bit index.
+        measure_name: Name of the measurement schedule.
+    Returns:
+        A measurement schedule corresponding to the inputs provided.
+    Raises:
+        PulseError: If both ``inst_map`` or ``meas_map``, and ``backend`` is None.
+    """
+
+    schedule = Schedule(name=f"Default measurement schedule for qubits {qubits}")
+
+    if isinstance(meas_map, list):
+        meas_map = utils.format_meas_map(meas_map)
+
+    measure_groups = set()
+    for qubit in qubits:
+        measure_groups.add(tuple(meas_map[qubit]))
+    for measure_group_qubits in measure_groups:
+
+        unused_mem_slots = (
+            set()
+            if qubit_mem_slots is None
+            else set(measure_group_qubits) - set(qubit_mem_slots.values())
+        )
+
+        try:
+            default_sched = inst_map.get(measure_name, measure_group_qubits)
+        except exceptions.PulseError as ex:
+            raise exceptions.PulseError(
+                f"We could not find a default measurement schedule called '{measure_name}'. "
+                "Please provide another name using the 'measure_name' keyword "
+                "argument. For assistance, the instructions which are defined are: "
+                f"{inst_map.instructions}"
+            ) from ex
+        for time, inst in default_sched.instructions:
+            if inst.channel.index not in qubits:
+                continue
+            if qubit_mem_slots and isinstance(inst, instructions.Acquire):
+                if inst.channel.index in qubit_mem_slots:
+                    mem_slot = channels.MemorySlot(qubit_mem_slots[inst.channel.index])
+                else:
+                    mem_slot = channels.MemorySlot(unused_mem_slots.pop())
+                inst = instructions.Acquire(inst.duration, inst.channel, mem_slot=mem_slot)
+            # Measurement pulses should only be added if its qubit was measured by the user
+            schedule = schedule.insert(time, inst)
+
+    return schedule
+
+
+def _measure_v2(
+    qubits: Sequence[int],
+    target: Target,
+    meas_map: list[list[int]] | dict[int, list[int]],
+    qubit_mem_slots: dict[int, int],
+    measure_name: str = "measure",
+) -> Schedule:
+    """Return a schedule which measures the requested qubits according to the given
+    target and measure map, or by using the defaults provided by the backendV2.
+
+    Args:
+        qubits: List of qubits to be measured.
+        target: The :class:`~.Target` representing the target backend.
+        meas_map: List of sets of qubits that must be measured together.
+        qubit_mem_slots: Mapping of measured qubit index to classical bit index.
+        measure_name: Name of the measurement schedule.
+
+    Returns:
+        A measurement schedule corresponding to the inputs provided.
+    """
+    schedule = Schedule(name=f"Default measurement schedule for qubits {qubits}")
+
+    if isinstance(meas_map, list):
+        meas_map = utils.format_meas_map(meas_map)
+    meas_group = set()
+    for qubit in qubits:
+        meas_group |= set(meas_map[qubit])
+    meas_group = sorted(meas_group)
+
+    meas_group_set = set(range(max(meas_group) + 1))
+    unassigned_qubit_indices = sorted(set(meas_group) - qubit_mem_slots.keys())
+    unassigned_reg_indices = sorted(meas_group_set - set(qubit_mem_slots.values()), reverse=True)
+    if set(qubit_mem_slots.values()).issubset(meas_group_set):
+        for qubit in unassigned_qubit_indices:
+            qubit_mem_slots[qubit] = unassigned_reg_indices.pop()
+
+    for measure_qubit in meas_group:
+        try:
+            if measure_qubit in qubits:
+                default_sched = target._get_calibration(measure_name, (measure_qubit,)).filter(
+                    channels=[
+                        channels.MeasureChannel(measure_qubit),
+                        channels.AcquireChannel(measure_qubit),
+                    ]
+                )
+                schedule += _schedule_remapping_memory_slot(default_sched, qubit_mem_slots)
+        except KeyError as ex:
+            raise exceptions.PulseError(
+                f"We could not find a default measurement schedule called '{measure_name}'. "
+                "Please provide another name using the 'measure_name' keyword "
+                "argument. For assistance, the instructions which are defined are: "
+                f"{target.instructions}"
+            ) from ex
+    return schedule
+
+
+def measure_all(backend) -> Schedule:
+    """
+    Return a Schedule which measures all qubits of the given backend.
+
+    Args:
+        backend (Union[Backend, BaseBackend]): A backend instance, which contains
+            hardware-specific data required for scheduling.
+
+    Returns:
+        A schedule corresponding to the inputs provided.
+    """
+    # backend is V2.
+    if isinstance(backend, BackendV2):
+        qubits = list(range(backend.num_qubits))
+    else:
+        qubits = list(range(backend.configuration().n_qubits))
+    return measure(qubits=qubits, backend=backend)
+
+
+def _schedule_remapping_memory_slot(
+    schedule: Schedule, qubit_mem_slots: dict[int, int]
+) -> Schedule:
+    """
+    A helper function to overwrite MemorySlot index of :class:`.Acquire` instruction.
+
+    Args:
+        schedule: A measurement schedule.
+        qubit_mem_slots: Mapping of measured qubit index to classical bit index.
+
+    Returns:
+        A measurement schedule with new memory slot index.
+    """
+    new_schedule = Schedule()
+    for t0, inst in schedule.instructions:
+        if isinstance(inst, instructions.Acquire):
+            qubit_index = inst.channel.index
+            reg_index = qubit_mem_slots.get(qubit_index, qubit_index)
+            new_schedule.insert(
+                t0,
+                instructions.Acquire(
+                    inst.duration,
+                    channels.AcquireChannel(qubit_index),
+                    mem_slot=channels.MemorySlot(reg_index),
+                ),
+                inplace=True,
+            )
+        else:
+            new_schedule.insert(t0, inst, inplace=True)
+    return new_schedule