Fix scheduling tests, lints and docs issue.

Author: ElePT

qiskit/pulse/builder.py

@@ -736,6 +736,20 @@ def append_instruction(instruction: instructions.Instruction):
 def num_qubits() -> int:
     """Return number of qubits in the currently active backend.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+        backend = FakeOpenPulse2Q()
+        with pulse.build(backend):
+            print(pulse.num_qubits())
+
+    .. code-block:: text
+
+       2
+
     .. note:: Requires the active builder context to have a backend set.
     """
     if isinstance(active_backend(), BackendV2):
@@ -780,6 +794,20 @@ def samples_to_seconds(samples: int | np.ndarray) -> float | np.ndarray:
 def qubit_channels(qubit: int) -> set[chans.Channel]:
     """Returns the set of channels associated with a qubit.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+        backend = FakeOpenPulse2Q()
+        with pulse.build(backend):
+            print(pulse.qubit_channels(0))
+
+    .. code-block:: text
+
+       {MeasureChannel(0), ControlChannel(0), DriveChannel(0), AcquireChannel(0), ControlChannel(1)}
+
     .. note:: Requires the active builder context to have a backend set.
 
     .. note:: A channel may still be associated with another qubit in this list
@@ -1145,6 +1173,33 @@ def frequency_offset(
 ) -> Generator[None, None, None]:
     """Shift the frequency of inputs channels on entry into context and undo on exit.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        backend = FakeOpenPulse2Q()
+        d0 = pulse.DriveChannel(0)
+
+        with pulse.build(backend) as pulse_prog:
+            # shift frequency by 1GHz
+            with pulse.frequency_offset(1e9, d0):
+                pulse.play(pulse.Constant(10, 1.0), d0)
+
+        assert len(pulse_prog.instructions) == 3
+
+        with pulse.build(backend) as pulse_prog:
+            # Shift frequency by 1GHz.
+            # Undo accumulated phase in the shifted frequency frame
+            # when exiting the context.
+            with pulse.frequency_offset(1e9, d0, compensate_phase=True):
+                pulse.play(pulse.Constant(10, 1.0), d0)
+
+        assert len(pulse_prog.instructions) == 4
+
+
     Args:
         frequency: Amount of frequency offset in Hz.
         channels: Channels to offset frequency of.
@@ -1182,6 +1237,18 @@ def frequency_offset(
 def drive_channel(qubit: int) -> chans.DriveChannel:
     """Return ``DriveChannel`` for ``qubit`` on the active builder backend.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        backend = FakeOpenPulse2Q()
+
+        with pulse.build(backend):
+            assert pulse.drive_channel(0) == pulse.DriveChannel(0)
+
     .. note:: Requires the active builder context to have a backend set.
     """
     # backendV2
@@ -1194,6 +1261,18 @@ def drive_channel(qubit: int) -> chans.DriveChannel:
 def measure_channel(qubit: int) -> chans.MeasureChannel:
     """Return ``MeasureChannel`` for ``qubit`` on the active builder backend.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        backend = FakeOpenPulse2Q()
+
+        with pulse.build(backend):
+            assert pulse.measure_channel(0) == pulse.MeasureChannel(0)
+
     .. note:: Requires the active builder context to have a backend set.
     """
     # backendV2
@@ -1206,6 +1285,18 @@ def measure_channel(qubit: int) -> chans.MeasureChannel:
 def acquire_channel(qubit: int) -> chans.AcquireChannel:
     """Return ``AcquireChannel`` for ``qubit`` on the active builder backend.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        backend = FakeOpenPulse2Q()
+
+        with pulse.build(backend):
+            assert pulse.acquire_channel(0) == pulse.AcquireChannel(0)
+
     .. note:: Requires the active builder context to have a backend set.
     """
     # backendV2
@@ -1221,6 +1312,18 @@ def control_channels(*qubits: Iterable[int]) -> list[chans.ControlChannel]:
     Return the secondary drive channel for the given qubit -- typically
     utilized for controlling multi-qubit interactions.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        backend = FakeOpenPulse2Q()
+
+        with pulse.build(backend):
+            assert pulse.control_channels(0, 1) == [pulse.ControlChannel(0)]
+
     .. note:: Requires the active builder context to have a backend set.
 
     Args:
@@ -1710,8 +1813,65 @@ def barrier(*channels_or_qubits: chans.Channel | int, name: str | None = None):
     """Barrier directive for a set of channels and qubits.
 
     This directive prevents the compiler from moving instructions across
-    the barrier. The barrier allows the pulse compiler to take care of more advanced
-    scheduling alignment operations across channels.
+    the barrier. Consider the case where we want to enforce that one pulse
+    happens after another on separate channels, this can be done with:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        backend = FakeOpenPulse2Q()
+
+        d0 = pulse.DriveChannel(0)
+        d1 = pulse.DriveChannel(1)
+
+        with pulse.build(backend) as barrier_pulse_prog:
+            pulse.play(pulse.Constant(10, 1.0), d0)
+            pulse.barrier(d0, d1)
+            pulse.play(pulse.Constant(10, 1.0), d1)
+
+    Of course this could have been accomplished with:
+
+    .. code-block:: python
+
+        from qiskit.pulse import transforms
+
+        with pulse.build(backend) as aligned_pulse_prog:
+            with pulse.align_sequential():
+                pulse.play(pulse.Constant(10, 1.0), d0)
+                pulse.play(pulse.Constant(10, 1.0), d1)
+
+        barrier_pulse_prog = transforms.target_qobj_transform(barrier_pulse_prog)
+        aligned_pulse_prog = transforms.target_qobj_transform(aligned_pulse_prog)
+
+        assert barrier_pulse_prog == aligned_pulse_prog
+
+    The barrier allows the pulse compiler to take care of more advanced
+    scheduling alignment operations across channels. For example
+    in the case where we are calling an outside circuit or schedule and
+    want to align a pulse at the end of one call:
+
+    .. code-block:: python
+
+        import math
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        backend = FakeOpenPulse2Q()
+
+        d0 = pulse.DriveChannel(0)
+
+        with pulse.build(backend) as pulse_prog:
+            with pulse.align_right():
+                pulse.call(backend.defaults().instruction_schedule_map.get('u1', (1,)))
+                # Barrier qubit 1 and d0.
+                pulse.barrier(1, d0)
+                # Due to barrier this will play before the gate on qubit 1.
+                pulse.play(pulse.Constant(10, 1.0), d0)
+                # This will end at the same time as the pulse above due to
+                # the barrier.
+                pulse.call(backend.defaults().instruction_schedule_map.get('u1', (1,)))
 
     .. note:: Requires the active builder context to have a backend set if
         qubits are barriered on.
@@ -1735,6 +1895,29 @@ def macro(func: Callable):
     behave as if the function code was embedded inline in the parent builder context
     after parameter substitution.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        @pulse.macro
+        def measure(qubit: int):
+            pulse.play(pulse.GaussianSquare(16384, 256, 15872), pulse.measure_channel(qubit))
+            mem_slot = pulse.MemorySlot(qubit)
+            pulse.acquire(16384, pulse.acquire_channel(qubit), mem_slot)
+
+            return mem_slot
+
+        backend = FakeOpenPulse2Q()
+
+        with pulse.build(backend=backend) as sched:
+            mem_slot = measure(0)
+            print(f"Qubit measured into {mem_slot}")
+
+        sched.draw()
+
     Args:
         func: The Python function to enable as a builder macro. There are no
             requirements on the signature of the function, any calls to pulse
@@ -1827,6 +2010,19 @@ def measure_all() -> list[chans.MemorySlot]:
     same time. This is useful for handling device ``meas_map`` and single
     measurement constraints.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        backend = FakeOpenPulse2Q()
+
+        with pulse.build(backend) as pulse_prog:
+            # Measure all qubits and return associated registers.
+            regs = pulse.measure_all()
+
     .. note::
         Requires the active builder context to have a backend set.
 
@@ -1855,6 +2051,19 @@ def delay_qubits(duration: int, *qubits: int):
     r"""Insert delays on all the :class:`channels.Channel`\s that correspond
     to the input ``qubits`` at the same time.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse3Q
+
+        backend = FakeOpenPulse3Q()
+
+        with pulse.build(backend) as pulse_prog:
+            # Delay for 100 cycles on qubits 0, 1 and 2.
+            regs = pulse.delay_qubits(100, 0, 1, 2)
+
     .. note:: Requires the active builder context to have a backend set.
 
     Args:

test/python/compiler/test_transpiler.py

@@ -89,7 +89,6 @@
 from qiskit.transpiler.target import (
     InstructionProperties,
     Target,
-    InstructionDurations,
 )
 
 from test import QiskitTestCase, combine, slow_test  # pylint: disable=wrong-import-order
@@ -1516,37 +1515,27 @@ def test_scheduling_instruction_constraints_backend(self):
         """Test that scheduling-related loose transpile constraints
         work with BackendV2."""
 
-        with self.assertWarnsRegex(
-            DeprecationWarning,
-            expected_regex="argument ``calibrate_instructions`` is deprecated",
-        ):
-            backend_v2 = GenericBackendV2(
-                2,
-                calibrate_instructions=True,
-                coupling_map=[[0, 1]],
-                basis_gates=["cx", "h"],
-                seed=0,
-            )
+        backend = GenericBackendV2(
+            2,
+            coupling_map=[[0, 1]],
+            basis_gates=["cx", "h"],
+            seed=42,
+        )
         qc = QuantumCircuit(2)
         qc.h(0)
-        qc.delay(500, 1, "dt")
+        qc.delay(0.000001, 1, "s")
         qc.cx(0, 1)
-        # update durations
-        durations = InstructionDurations.from_backend(backend_v2)
-        durations.update([("cx", [0, 1], 1000, "dt")])
 
-        with self.assertWarnsRegex(
-            DeprecationWarning,
-            expected_regex="The `target` parameter should be used instead",
-        ):
-            scheduled = transpile(
-                qc,
-                backend=backend_v2,
-                scheduling_method="alap",
-                instruction_durations=durations,
-                layout_method="trivial",
-            )
-        self.assertEqual(scheduled.duration, 1500)
+        # update cx to 2 seconds
+        backend.target.update_instruction_properties("cx", (0, 1), InstructionProperties(0.000001))
+
+        scheduled = transpile(
+            qc,
+            backend=backend,
+            scheduling_method="alap",
+            layout_method="trivial",
+        )
+        self.assertEqual(scheduled.duration, 9010)
 
     def test_scheduling_instruction_constraints(self):
         """Test that scheduling-related loose transpile constraints work with target."""