qiskit 1.0.0b1__cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

qiskit/pulse/instructions/instruction.py

@@ -0,0 +1,266 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2019.
+#
+# 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.
+
+"""
+``Instruction`` s are single operations within a :py:class:`~qiskit.pulse.Schedule`, and can be
+used the same way as :py:class:`~qiskit.pulse.Schedule` s.
+
+For example::
+
+    duration = 10
+    channel = DriveChannel(0)
+    sched = Schedule()
+    sched += Delay(duration, channel)  # Delay is a specific subclass of Instruction
+"""
+from abc import ABC, abstractmethod
+from typing import Iterable, List, Optional, Set, Tuple
+
+from qiskit.circuit import Parameter
+from qiskit.pulse.channels import Channel
+from qiskit.pulse.exceptions import PulseError
+
+
+# pylint: disable=bad-docstring-quotes
+
+
+class Instruction(ABC):
+    """The smallest schedulable unit: a single instruction. It has a fixed duration and specified
+    channels.
+    """
+
+    def __init__(
+        self,
+        operands: Tuple,
+        name: Optional[str] = None,
+    ):
+        """Instruction initializer.
+
+        Args:
+            operands: The argument list.
+            name: Optional display name for this instruction.
+        """
+        self._operands = operands
+        self._name = name
+        self._validate()
+
+    def _validate(self):
+        """Called after initialization to validate instruction data.
+
+        Raises:
+            PulseError: If the input ``channels`` are not all of type :class:`Channel`.
+        """
+        for channel in self.channels:
+            if not isinstance(channel, Channel):
+                raise PulseError(f"Expected a channel, got {channel} instead.")
+
+    @property
+    def name(self) -> str:
+        """Name of this instruction."""
+        return self._name
+
+    @property
+    def id(self) -> int:  # pylint: disable=invalid-name
+        """Unique identifier for this instruction."""
+        return id(self)
+
+    @property
+    def operands(self) -> Tuple:
+        """Return instruction operands."""
+        return self._operands
+
+    @property
+    @abstractmethod
+    def channels(self) -> Tuple[Channel]:
+        """Returns the channels that this schedule uses."""
+        raise NotImplementedError
+
+    @property
+    def start_time(self) -> int:
+        """Relative begin time of this instruction."""
+        return 0
+
+    @property
+    def stop_time(self) -> int:
+        """Relative end time of this instruction."""
+        return self.duration
+
+    @property
+    def duration(self) -> int:
+        """Duration of this instruction."""
+        raise NotImplementedError
+
+    @property
+    def _children(self) -> Tuple["Instruction"]:
+        """Instruction has no child nodes."""
+        return ()
+
+    @property
+    def instructions(self) -> Tuple[Tuple[int, "Instruction"]]:
+        """Iterable for getting instructions from Schedule tree."""
+        return tuple(self._instructions())
+
+    def ch_duration(self, *channels: List[Channel]) -> int:
+        """Return duration of the supplied channels in this Instruction.
+
+        Args:
+            *channels: Supplied channels
+        """
+        return self.ch_stop_time(*channels)
+
+    def ch_start_time(self, *channels: List[Channel]) -> int:
+        # pylint: disable=unused-argument
+        """Return minimum start time for supplied channels.
+
+        Args:
+            *channels: Supplied channels
+        """
+        return 0
+
+    def ch_stop_time(self, *channels: List[Channel]) -> int:
+        """Return maximum start time for supplied channels.
+
+        Args:
+            *channels: Supplied channels
+        """
+        if any(chan in self.channels for chan in channels):
+            return self.duration
+        return 0
+
+    def _instructions(self, time: int = 0) -> Iterable[Tuple[int, "Instruction"]]:
+        """Iterable for flattening Schedule tree.
+
+        Args:
+            time: Shifted time of this node due to parent
+
+        Yields:
+            Tuple[int, Union['Schedule, 'Instruction']]: Tuple of the form
+                (start_time, instruction).
+        """
+        yield (time, self)
+
+    def shift(self, time: int, name: Optional[str] = None):
+        """Return a new schedule shifted forward by `time`.
+
+        Args:
+            time: Time to shift by
+            name: Name of the new schedule. Defaults to name of self
+
+        Returns:
+            Schedule: The shifted schedule.
+        """
+        from qiskit.pulse.schedule import Schedule
+
+        if name is None:
+            name = self.name
+        return Schedule((time, self), name=name)
+
+    def insert(self, start_time: int, schedule, name: Optional[str] = None):
+        """Return a new :class:`~qiskit.pulse.Schedule` with ``schedule`` inserted within
+        ``self`` at ``start_time``.
+
+        Args:
+            start_time: Time to insert the schedule schedule
+            schedule (Union['Schedule', 'Instruction']): Schedule or instruction to insert
+            name: Name of the new schedule. Defaults to name of self
+
+        Returns:
+            Schedule: A new schedule with ``schedule`` inserted with this instruction at t=0.
+        """
+        from qiskit.pulse.schedule import Schedule
+
+        if name is None:
+            name = self.name
+        return Schedule(self, (start_time, schedule), name=name)
+
+    def append(self, schedule, name: Optional[str] = None):
+        """Return a new :class:`~qiskit.pulse.Schedule` with ``schedule`` inserted at the
+        maximum time over all channels shared between ``self`` and ``schedule``.
+
+        Args:
+            schedule (Union['Schedule', 'Instruction']): Schedule or instruction to be appended
+            name: Name of the new schedule. Defaults to name of self
+
+        Returns:
+            Schedule: A new schedule with ``schedule`` a this instruction at t=0.
+        """
+        common_channels = set(self.channels) & set(schedule.channels)
+        time = self.ch_stop_time(*common_channels)
+        return self.insert(time, schedule, name=name)
+
+    @property
+    def parameters(self) -> Set:
+        """Parameters which determine the instruction behavior."""
+
+        def _get_parameters_recursive(obj):
+            params = set()
+            if hasattr(obj, "parameters"):
+                for param in obj.parameters:
+                    if isinstance(param, Parameter):
+                        params.add(param)
+                    else:
+                        params |= _get_parameters_recursive(param)
+            return params
+
+        parameters = set()
+        for op in self.operands:
+            parameters |= _get_parameters_recursive(op)
+        return parameters
+
+    def is_parameterized(self) -> bool:
+        """Return True iff the instruction is parameterized."""
+        return any(self.parameters)
+
+    def __eq__(self, other: "Instruction") -> bool:
+        """Check if this Instruction is equal to the `other` instruction.
+
+        Equality is determined by the instruction sharing the same operands and channels.
+        """
+        return isinstance(other, type(self)) and self.operands == other.operands
+
+    def __hash__(self) -> int:
+        return hash((type(self), self.operands, self.name))
+
+    def __add__(self, other):
+        """Return a new schedule with `other` inserted within `self` at `start_time`.
+
+        Args:
+            other (Union['Schedule', 'Instruction']): Schedule or instruction to be appended
+
+        Returns:
+            Schedule: A new schedule with ``schedule`` appended after this instruction at t=0.
+        """
+        return self.append(other)
+
+    def __or__(self, other):
+        """Return a new schedule which is the union of `self` and `other`.
+
+        Args:
+            other (Union['Schedule', 'Instruction']): Schedule or instruction to union with
+
+        Returns:
+            Schedule: A new schedule with ``schedule`` inserted with this instruction at t=0
+        """
+        return self.insert(0, other)
+
+    def __lshift__(self, time: int):
+        """Return a new schedule which is shifted forward by `time`.
+
+        Returns:
+            Schedule: The shifted schedule
+        """
+        return self.shift(time)
+
+    def __repr__(self) -> str:
+        operands = ", ".join(str(op) for op in self.operands)
+        return "{}({}{})".format(
+            self.__class__.__name__, operands, f", name='{self.name}'" if self.name else ""
+        )

qiskit/pulse/instructions/phase.py

@@ -0,0 +1,149 @@
+# 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.
+
+"""The phase instructions update the modulation phase of pulses played on a channel.
+This includes ``SetPhase`` instructions which lock the modulation to a particular phase
+at that moment, and ``ShiftPhase`` instructions which increase the existing phase by a
+relative amount.
+"""
+from typing import Optional, Union, Tuple
+
+from qiskit.circuit import ParameterExpression
+from qiskit.pulse.channels import PulseChannel
+from qiskit.pulse.instructions.instruction import Instruction
+from qiskit.pulse.exceptions import PulseError
+
+
+class ShiftPhase(Instruction):
+    r"""The shift phase instruction updates the modulation phase of proceeding pulses played on the
+    same :py:class:`~qiskit.pulse.channels.Channel`. It is a relative increase in phase determined
+    by the ``phase`` operand.
+
+    In particular, a PulseChannel creates pulses of the form
+
+    .. math::
+        Re[\exp(i 2\pi f jdt + \phi) d_j].
+
+    The ``ShiftPhase`` instruction causes :math:`\phi` to be increased by the instruction's
+    ``phase`` operand. This will affect all pulses following on the same channel.
+
+    The qubit phase is tracked in software, enabling instantaneous, nearly error-free Z-rotations
+    by using a ShiftPhase to update the frame tracking the qubit state.
+    """
+
+    def __init__(
+        self,
+        phase: Union[complex, ParameterExpression],
+        channel: PulseChannel,
+        name: Optional[str] = None,
+    ):
+        """Instantiate a shift phase instruction, increasing the output signal phase on ``channel``
+        by ``phase`` [radians].
+
+        Args:
+            phase: The rotation angle in radians.
+            channel: The channel this instruction operates on.
+            name: Display name for this instruction.
+        """
+        super().__init__(operands=(phase, channel), name=name)
+
+    def _validate(self):
+        """Called after initialization to validate instruction data.
+
+        Raises:
+            PulseError: If the input ``channel`` is not type :class:`PulseChannel`.
+        """
+        if not isinstance(self.channel, PulseChannel):
+            raise PulseError(f"Expected a pulse channel, got {self.channel} instead.")
+
+    @property
+    def phase(self) -> Union[complex, ParameterExpression]:
+        """Return the rotation angle enacted by this instruction in radians."""
+        return self.operands[0]
+
+    @property
+    def channel(self) -> PulseChannel:
+        """Return the :py:class:`~qiskit.pulse.channels.Channel` that this instruction is
+        scheduled on.
+        """
+        return self.operands[1]
+
+    @property
+    def channels(self) -> Tuple[PulseChannel]:
+        """Returns the channels that this schedule uses."""
+        return (self.channel,)
+
+    @property
+    def duration(self) -> int:
+        """Duration of this instruction."""
+        return 0
+
+
+class SetPhase(Instruction):
+    r"""The set phase instruction sets the phase of the proceeding pulses on that channel
+    to ``phase`` radians.
+
+    In particular, a PulseChannel creates pulses of the form
+
+    .. math::
+
+        Re[\exp(i 2\pi f jdt + \phi) d_j]
+
+    The ``SetPhase`` instruction sets :math:`\phi` to the instruction's ``phase`` operand.
+    """
+
+    def __init__(
+        self,
+        phase: Union[complex, ParameterExpression],
+        channel: PulseChannel,
+        name: Optional[str] = None,
+    ):
+        """Instantiate a set phase instruction, setting the output signal phase on ``channel``
+        to ``phase`` [radians].
+
+        Args:
+            phase: The rotation angle in radians.
+            channel: The channel this instruction operates on.
+            name: Display name for this instruction.
+        """
+        super().__init__(operands=(phase, channel), name=name)
+
+    def _validate(self):
+        """Called after initialization to validate instruction data.
+
+        Raises:
+            PulseError: If the input ``channel`` is not type :class:`PulseChannel`.
+        """
+        if not isinstance(self.channel, PulseChannel):
+            raise PulseError(f"Expected a pulse channel, got {self.channel} instead.")
+
+    @property
+    def phase(self) -> Union[complex, ParameterExpression]:
+        """Return the rotation angle enacted by this instruction in radians."""
+        return self.operands[0]
+
+    @property
+    def channel(self) -> PulseChannel:
+        """Return the :py:class:`~qiskit.pulse.channels.Channel` that this instruction is
+        scheduled on.
+        """
+        return self.operands[1]
+
+    @property
+    def channels(self) -> Tuple[PulseChannel]:
+        """Returns the channels that this schedule uses."""
+        return (self.channel,)
+
+    @property
+    def duration(self) -> int:
+        """Duration of this instruction."""
+        return 0

qiskit/pulse/instructions/play.py

@@ -0,0 +1,96 @@
+# 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.
+
+"""An instruction to transmit a given pulse on a ``PulseChannel`` (i.e., those which support
+transmitted pulses, such as ``DriveChannel``).
+"""
+from typing import Optional, Union, Tuple, Set
+
+from qiskit.circuit.parameterexpression import ParameterExpression
+from qiskit.pulse.channels import PulseChannel
+from qiskit.pulse.exceptions import PulseError
+from qiskit.pulse.instructions.instruction import Instruction
+from qiskit.pulse.library.pulse import Pulse
+
+
+class Play(Instruction):
+    """This instruction is responsible for applying a pulse on a channel.
+
+    The pulse specifies the exact time dynamics of the output signal envelope for a limited
+    time. The output is modulated by a phase and frequency which are controlled by separate
+    instructions. The pulse duration must be fixed, and is implicitly given in terms of the
+    cycle time, dt, of the backend.
+    """
+
+    def __init__(self, pulse: Pulse, channel: PulseChannel, name: Optional[str] = None):
+        """Create a new pulse instruction.
+
+        Args:
+            pulse: A pulse waveform description, such as
+                   :py:class:`~qiskit.pulse.library.Waveform`.
+            channel: The channel to which the pulse is applied.
+            name: Name of the instruction for display purposes. Defaults to ``pulse.name``.
+        """
+        if name is None:
+            name = pulse.name
+        super().__init__(operands=(pulse, channel), name=name)
+
+    def _validate(self):
+        """Called after initialization to validate instruction data.
+
+        Raises:
+            PulseError: If pulse is not a Pulse type.
+            PulseError: If the input ``channel`` is not type :class:`PulseChannel`.
+        """
+        if not isinstance(self.pulse, Pulse):
+            raise PulseError("The `pulse` argument to `Play` must be of type `library.Pulse`.")
+
+        if not isinstance(self.channel, PulseChannel):
+            raise PulseError(f"Expected a pulse channel, got {self.channel} instead.")
+
+    @property
+    def pulse(self) -> Pulse:
+        """A description of the samples that will be played."""
+        return self.operands[0]
+
+    @property
+    def channel(self) -> PulseChannel:
+        """Return the :py:class:`~qiskit.pulse.channels.Channel` that this instruction is
+        scheduled on.
+        """
+        return self.operands[1]
+
+    @property
+    def channels(self) -> Tuple[PulseChannel]:
+        """Returns the channels that this schedule uses."""
+        return (self.channel,)
+
+    @property
+    def duration(self) -> Union[int, ParameterExpression]:
+        """Duration of this instruction."""
+        return self.pulse.duration
+
+    @property
+    def parameters(self) -> Set:
+        """Parameters which determine the instruction behavior."""
+        parameters = set()
+
+        # Note that Pulse.parameters returns dict rather than set for convention.
+        # We need special handling for Play instruction.
+        for pulse_param_expr in self.pulse.parameters.values():
+            if isinstance(pulse_param_expr, ParameterExpression):
+                parameters = parameters | pulse_param_expr.parameters
+
+        if self.channel.is_parameterized():
+            parameters = parameters | self.channel.parameters
+
+        return parameters

qiskit/pulse/instructions/reference.py

@@ -0,0 +1,99 @@
+# 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.
+
+"""Reference instruction that is a placeholder for subroutine."""
+
+from typing import Union, Tuple, Set
+
+from qiskit.circuit.parameterexpression import ParameterExpression
+from qiskit.pulse.channels import Channel
+from qiskit.pulse.exceptions import PulseError, UnassignedReferenceError
+from qiskit.pulse.instructions import instruction
+
+
+class Reference(instruction.Instruction):
+    """Pulse compiler directive that refers to a subroutine.
+
+    If a pulse program uses the same subset of instructions multiple times, then
+    using the :class:`~.Reference` class may significantly reduce the memory footprint of
+    the program. This instruction only stores the set of strings to identify the subroutine.
+
+    The actual pulse program can be stored in the :attr:`ScheduleBlock.references` of the
+    :class:`.ScheduleBlock` that this reference instruction belongs to.
+
+    You can later assign schedules with the :meth:`ScheduleBlock.assign_references` method.
+    This allows you to build the main program without knowing the actual subroutine,
+    that is supplied at a later time.
+    """
+
+    # Delimiter for representing nested scope.
+    scope_delimiter = "::"
+
+    # Delimiter for tuple keys.
+    key_delimiter = ","
+
+    def __init__(self, name: str, *extra_keys: str):
+        """Create new reference.
+
+        Args:
+            name: Name of subroutine.
+            extra_keys: Optional. A set of string keys that may be necessary to
+                refer to a particular subroutine. For example, when we use
+                "sx" as a name to refer to the subroutine of an sx pulse,
+                this name might be used among schedules for different qubits.
+                In this example, you may specify "q0" in the extra keys
+                to distinguish the sx schedule for qubit 0 from others.
+                The user can use an arbitrary number of extra string keys to
+                uniquely determine the subroutine.
+        """
+        # Run validation
+        ref_keys = (name,) + tuple(extra_keys)
+        super().__init__(operands=ref_keys, name=name)
+
+    def _validate(self):
+        """Called after initialization to validate instruction data.
+
+        Raises:
+            PulseError: When a key is not a string.
+            PulseError: When a key in ``ref_keys`` contains the scope delimiter.
+        """
+        for key in self.ref_keys:
+            if not isinstance(key, str):
+                raise PulseError(f"Keys must be strings. '{repr(key)}' is not a valid object.")
+            if self.scope_delimiter in key or self.key_delimiter in key:
+                raise PulseError(
+                    f"'{self.scope_delimiter}' and '{self.key_delimiter}' are reserved. "
+                    f"'{key}' is not a valid key string."
+                )
+
+    @property
+    def ref_keys(self) -> Tuple[str, ...]:
+        """Returns unique key of the subroutine."""
+        return self.operands
+
+    @property
+    def duration(self) -> Union[int, ParameterExpression]:
+        """Duration of this instruction."""
+        raise UnassignedReferenceError(f"Subroutine is not assigned to {self.ref_keys}.")
+
+    @property
+    def channels(self) -> Tuple[Channel, ...]:
+        """Returns the channels that this schedule uses."""
+        raise UnassignedReferenceError(f"Subroutine is not assigned to {self.ref_keys}.")
+
+    @property
+    def parameters(self) -> Set:
+        """Parameters which determine the instruction behavior."""
+        return set()
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.key_delimiter.join(self.ref_keys)})"

qiskit/pulse/instructions/snapshot.py

@@ -0,0 +1,80 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2019.
+#
+# 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 simulator instruction to capture output within a simulation. The types of snapshot
+instructions available are determined by the simulator being used.
+"""
+from typing import Optional, Tuple
+
+from qiskit.pulse.channels import SnapshotChannel
+from qiskit.pulse.exceptions import PulseError
+from qiskit.pulse.instructions.instruction import Instruction
+
+
+class Snapshot(Instruction):
+    """An instruction targeted for simulators, to capture a moment in the simulation."""
+
+    def __init__(self, label: str, snapshot_type: str = "statevector", name: Optional[str] = None):
+        """Create new snapshot.
+
+        Args:
+            label: Snapshot label which is used to identify the snapshot in the output.
+            snapshot_type: Type of snapshot, e.g., “state” (take a snapshot of the quantum state).
+                           The types of snapshots offered are defined by the simulator used.
+            name: Snapshot name which defaults to ``label``. This parameter is only for display
+                  purposes and is not taken into account during comparison.
+        """
+        self._channel = SnapshotChannel()
+
+        if name is None:
+            name = label
+        super().__init__(operands=(label, snapshot_type), name=name)
+
+    def _validate(self):
+        """Called after initialization to validate instruction data.
+
+        Raises:
+            PulseError: If snapshot label is invalid.
+        """
+        if not isinstance(self.label, str):
+            raise PulseError("Snapshot label must be a string.")
+
+    @property
+    def label(self) -> str:
+        """Label of snapshot."""
+        return self.operands[0]
+
+    @property
+    def type(self) -> str:
+        """Type of snapshot."""
+        return self.operands[1]
+
+    @property
+    def channel(self) -> SnapshotChannel:
+        """Return the :py:class:`~qiskit.pulse.channels.Channel` that this instruction is
+        scheduled on; trivially, a ``SnapshotChannel``.
+        """
+        return self._channel
+
+    @property
+    def channels(self) -> Tuple[SnapshotChannel]:
+        """Returns the channels that this schedule uses."""
+        return (self.channel,)
+
+    @property
+    def duration(self) -> int:
+        """Duration of this instruction."""
+        return 0
+
+    def is_parameterized(self) -> bool:
+        """Return True iff the instruction is parameterized."""
+        return False