Add working documentation.

qiskit_ibm_provider/transpiler/passes/__init__.py

@@ -29,4 +29,5 @@
 
 # circuit scheduling
 from .scheduling import DynamicCircuitScheduleAnalysis
+from .scheduling import PadDynamicalDecoupling
 from .scheduling import PadDelay

qiskit_ibm_provider/transpiler/passes/scheduling/__init__.py

@@ -15,15 +15,16 @@
 Scheduling (:mod:`qiskit_ibm_provider.transpiler.passes.scheduling`)
 ====================================================================
 
+.. currentmodule:: qiskit_ibm_provider.transpiler.passes.scheduling
+
 A collection of scheduling passes for working with IBM Quantum's next-generation
 backends that support advanced "dynamic circuit" capabilities. Ie.,
 circuits with support for classical control-flow/feedback based off
 of measurement results.
 
 
 Below we demonstrate how to schedule and pad a teleportation circuit with delays
-for a dynamic circuit backend's execution model
-
+for a dynamic circuit backend's execution model:
 
 .. jupyter-execute::
 
@@ -65,6 +66,30 @@
     scheduled_teleport.draw(output="mpl")
 
 
+Instead of padding with delays we may also insert a dynamical decoupling sequence
+using the :class:`PadDynamicalDecoupling` pass as shown below:
+
+.. jupyter-execute::
+
+    from qiskit.circuit.library import XGate
+
+    from qiskit_ibm_provider.transpiler.passes.scheduling import PadDynamicalDecoupling
+
+
+    dd_sequence = [XGate(), XGate()]
+
+    pm = PassManager(
+        [
+            DynamicCircuitScheduleAnalysis(durations),
+            PadDynamicalDecoupling(durations, dd_sequence),
+        ]
+    )
+
+    dd_teleport = pm.run(teleport)
+
+    dd_teleport.draw(output="mpl")
+
+
 Scheduling & Dynamical Decoupling
 =================================
 .. autosummary::
@@ -73,11 +98,13 @@
     BlockBasePadder
     DynamicCircuitScheduleAnalysis
     PadDelay
+    PadDynamicalDecoupling
 
 
 
 """
 
 from .block_base_padder import BlockBasePadder
+from .dynamical_decoupling import PadDynamicalDecoupling
 from .pad_delay import PadDelay
 from .scheduler import DynamicCircuitScheduleAnalysis

qiskit_ibm_provider/transpiler/passes/scheduling/dynamical_decoupling.py

@@ -44,7 +44,9 @@ class PadDynamicalDecoupling(BlockBasePadder):
     This can be used, for instance, as a Hahn echo.
     This pass ensures that the inserted sequence preserves the circuit exactly
     (including global phase).
+
     .. jupyter-execute::
+
         import numpy as np
         from qiskit.circuit import QuantumCircuit
         from qiskit.circuit.library import XGate
@@ -65,14 +67,18 @@ class PadDynamicalDecoupling(BlockBasePadder):
              ("cx", [1, 2], 200), ("cx", [2, 3], 300),
              ("x", None, 50), ("measure", None, 1000)]
         )
+
     .. jupyter-execute::
+
         # balanced X-X sequence on all qubits
         dd_sequence = [XGate(), XGate()]
         pm = PassManager([DynamicCircuitScheduleAnalysis(durations),
                           PadDynamicalDecoupling(durations, dd_sequence)])
         circ_dd = pm.run(circ)
-        timeline_drawer(circ_dd)
+        circ_dd.draw()
+
     .. jupyter-execute::
+
         # Uhrig sequence on qubit 0
         n = 8
         dd_sequence = [XGate()] * n
@@ -84,13 +90,15 @@ def uhrig_pulse_location(k):
         spacing.append(1 - sum(spacing))
         pm = PassManager(
             [
-                ALAPScheduleAnalysis(durations),
+                DynamicCircuitScheduleAnalysis(durations),
                 PadDynamicalDecoupling(durations, dd_sequence, qubits=[0], spacing=spacing),
             ]
         )
         circ_dd = pm.run(circ)
-        timeline_drawer(circ_dd)
+        circ_dd.draw()
+
     .. note::
+
         You need to call
         :class:`~qiskit_ibm_provider.transpiler.passes.scheduling.DynamicCircuitScheduleAnalysis`
         before running dynamical decoupling to guarantee your circuit satisfies acquisition
@@ -108,6 +116,7 @@ def __init__(
         extra_slack_distribution: str = "middle",
     ):
         """Dynamical decoupling initializer.
+
         Args:
             durations: Durations of instructions to be used in scheduling.
             dd_sequence: Sequence of gates to apply in idle spots.
@@ -133,14 +142,16 @@ def __init__(
                 the created sequence being shorter than the idle time
                 that you want to fill with the sequence, i.e. `extra slack`.
                 This option takes following values.
-                    - "middle": Put the extra slack to the interval at the middle of the sequence.
-                    - "edges": Divide the extra slack as evenly as possible into
+
+                    * "middle": Put the extra slack to the interval at the middle of the sequence.
+                    * "edges": Divide the extra slack as evenly as possible into
                       intervals at beginning and end of the sequence.
         Raises:
             TranspilerError: When invalid DD sequence is specified.
             TranspilerError: When pulse gate with the duration which is
                 non-multiple of the alignment constraint value is found.
         """
+
         super().__init__()
         self._durations = durations
         self._dd_sequence = dd_sequence