Pulse reference mechanism

qiskit/pulse/__init__.py

@@ -74,6 +74,7 @@
     call,
     delay,
     play,
+    reference,
     set_frequency,
     set_phase,
     shift_frequency,

qiskit/pulse/builder.py

@@ -11,6 +11,9 @@
 # that they have been altered from the originals.
 
 r"""
+
+.. _pulse_builder:
+
 =============
 Pulse Builder
 =============
@@ -299,6 +302,7 @@
     call
     delay
     play
+    reference
     set_frequency
     set_phase
     shift_frequency
@@ -440,6 +444,8 @@
 import contextvars
 import functools
 import itertools
+import uuid
+import warnings
 from contextlib import contextmanager
 from typing import (
     Any,
@@ -736,6 +742,16 @@ def append_block(self, context_block: ScheduleBlock):
         if len(context_block) > 0:
             self._context_stack[-1].append(context_block)
 
+    def append_reference(self, name: str, *extra_keys: str):
+        """Add external program as a :class:`~qiskit.pulse.instructions.Reference` instruction.
+
+        Args:
+            name: Name of subroutine.
+            extra_keys: Assistance keys to uniquely specify the subroutine.
+        """
+        inst = instructions.Reference(name, *extra_keys)
+        self.append_instruction(inst)
+
     def call_subroutine(
         self,
         subroutine: Union[circuit.QuantumCircuit, Schedule, ScheduleBlock],
@@ -747,7 +763,7 @@ def call_subroutine(
 
         The ``subroutine`` is appended to the context schedule as a call instruction.
         This logic just generates a convenient program representation in the compiler.
-        Thus this doesn't affect execution of inline subroutines.
+        Thus, this doesn't affect execution of inline subroutines.
         See :class:`~pulse.instructions.Call` for more details.
 
         Args:
@@ -769,39 +785,53 @@ def call_subroutine(
             self._compile_lazy_circuit()
             subroutine = self._compile_circuit(subroutine)
 
-        empty_subroutine = True
-        if isinstance(subroutine, Schedule):
-            if len(subroutine.instructions) > 0:
-                empty_subroutine = False
-        elif isinstance(subroutine, ScheduleBlock):
-            if len(subroutine.blocks) > 0:
-                empty_subroutine = False
-        else:
+        if not isinstance(subroutine, (Schedule, ScheduleBlock)):
             raise exceptions.PulseError(
                 f"Subroutine type {subroutine.__class__.__name__} is "
                 "not valid data format. Call QuantumCircuit, "
                 "Schedule, or ScheduleBlock."
             )
 
-        if not empty_subroutine:
-            param_value_map = {}
-            for param_name, assigned_value in kw_params.items():
-                param_objs = subroutine.get_parameters(param_name)
-                if len(param_objs) > 0:
-                    for param_obj in param_objs:
-                        param_value_map[param_obj] = assigned_value
-                else:
-                    raise exceptions.PulseError(
-                        f"Parameter {param_name} is not defined in the target subroutine. "
-                        f'{", ".join(map(str, subroutine.parameters))} can be specified.'
-                    )
-
-            if value_dict:
-                param_value_map.update(value_dict)
+        if len(subroutine) == 0:
+            return
 
-            call_def = instructions.Call(subroutine, param_value_map, name)
-
-            self.append_instruction(call_def)
+        # Create local parameter assignment
+        local_assignment = dict()
+        for param_name, value in kw_params.items():
+            params = subroutine.get_parameters(param_name)
+            if not params:
+                raise exceptions.PulseError(
+                    f"Parameter {param_name} is not defined in the target subroutine. "
+                    f'{", ".join(map(str, subroutine.parameters))} can be specified.'
+                )
+            for param in params:
+                local_assignment[param] = value
+        if value_dict:
+            if local_assignment.keys() & value_dict.keys():
+                warnings.warn(
+                    "Some parameters provided by 'value_dict' conflict with one through "
+                    "keyword arguments. Parameter values in the keyword arguments "
+                    "are overridden by the dictionary values.",
+                    UserWarning,
+                )
+            local_assignment.update(value_dict)
+
+        if isinstance(subroutine, ScheduleBlock):
+            # If subroutine is schedule block, use reference mechanism.
+            if local_assignment:
+                subroutine = subroutine.assign_parameters(local_assignment, inplace=False)
+            if name is None:
+                # Add unique string, not to accidentally override existing reference entry.
+                keys = (subroutine.name, uuid.uuid4().hex)
+            else:
+                keys = (name,)
+            self.append_reference(*keys)
+            self.get_context().assign_references({keys: subroutine}, inplace=True)
+        else:
+            # If subroutine is schedule, use Call instruction.
+            name = name or subroutine.name
+            call_instruction = instructions.Call(subroutine, local_assignment, name)
+            self.append_instruction(call_instruction)
 
     @_requires_backend
     def call_gate(self, gate: circuit.Gate, qubits: Tuple[int, ...], lazy: bool = True):
@@ -1679,18 +1709,17 @@ def acquire(
 
         from qiskit import pulse
 
-        d0 = pulse.MeasureChannel(0)
+        acq0 = pulse.AcquireChannel(0)
         mem0 = pulse.MemorySlot(0)
 
         with pulse.build() as pulse_prog:
-            pulse.acquire(100, d0, mem0)
+            pulse.acquire(100, acq0, mem0)
 
             # measurement metadata
             kernel = pulse.configuration.Kernel('linear_discriminator')
-            pulse.acquire(100, d0, mem0, kernel=kernel)
+            pulse.acquire(100, acq0, mem0, kernel=kernel)
 
-    .. note:: The type of data acquire will depend on the execution
-        ``meas_level``.
+    .. note:: The type of data acquire will depend on the execution ``meas_level``.
 
     Args:
         duration: Duration to acquire data for
@@ -1832,89 +1861,166 @@ def snapshot(label: str, snapshot_type: str = "statevector"):
 
 
 def call(
-    target: Union[circuit.QuantumCircuit, Schedule, ScheduleBlock],
+    target: Optional[Union[circuit.QuantumCircuit, Schedule, ScheduleBlock]],
     name: Optional[str] = None,
     value_dict: Optional[Dict[ParameterValueType, ParameterValueType]] = None,
     **kw_params: ParameterValueType,
 ):
-    """Call the ``target`` within the currently active builder context with arbitrary
+    """Call the subroutine within the currently active builder context with arbitrary
     parameters which will be assigned to the target program.
 
     .. note::
-        The ``target`` program is inserted as a ``Call`` instruction.
-        This instruction defines a subroutine. See :class:`~qiskit.pulse.instructions.Call`
-        for more details.
+
+        If the ``target`` program is a :class:`.ScheduleBlock`, then a :class:`.Reference`
+        instruction will be created and appended to the current context.
+        The ``target`` program will be immediately assigned to the current scope as a subroutine.
+        If the ``target`` program is :class:`.Schedule`, it will be wrapped by the
+        :class:`.Call` instruction and appended to the current context to avoid
+        a mixed representation of :class:`.ScheduleBlock` and :class:`.Schedule`.
+        If the ``target`` program is a :class:`.QuantumCircuit` it will be scheduled
+        and the new :class:`.Schedule` will be added as a :class:`.Call` instruction.
 
     Examples:
 
-    .. code-block:: python
+        1. Calling a schedule block (recommended)
 
-        from qiskit import circuit, pulse, schedule, transpile
-        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+        .. jupyter-execute::
 
-        backend = FakeOpenPulse2Q()
+            from qiskit import circuit, pulse
+            from qiskit.providers.fake_provider import FakeBogotaV2
 
-        qc = circuit.QuantumCircuit(2)
-        qc.cx(0, 1)
-        qc_transpiled = transpile(qc, optimization_level=3)
-        sched = schedule(qc_transpiled, backend)
+            backend = FakeBogotaV2()
 
-        with pulse.build(backend) as pulse_prog:
-                pulse.call(sched)
-                pulse.call(qc)
+            with pulse.build() as x_sched:
+                pulse.play(pulse.Gaussian(160, 0.1, 40), pulse.DriveChannel(0))
 
-    This function can optionally take parameter dictionary with the parameterized target program.
+            with pulse.build() as pulse_prog:
+                pulse.call(x_sched)
 
-    .. code-block:: python
+            print(pulse_prog)
 
-        from qiskit import circuit, pulse
+        The actual program is stored in the reference table attached to the schedule.
 
-        amp = circuit.Parameter('amp')
+        .. jupyter-execute::
 
-        with pulse.build() as subroutine:
-            pulse.play(pulse.Gaussian(160, amp, 40), pulse.DriveChannel(0))
+            print(pulse_prog.references)
 
-        with pulse.build() as main_prog:
-            pulse.call(subroutine, amp=0.1)
-            pulse.call(subroutine, amp=0.3)
+        In addition, you can call a parameterized target program with parameter assignment.
 
-    If there is any parameter name collision, you can distinguish them by specifying
-    each parameter object as a python dictionary. Otherwise ``amp1`` and ``amp2`` will be
-    updated with the same value.
+        .. jupyter-execute::
 
-    .. code-block:: python
+            amp = circuit.Parameter("amp")
 
-        from qiskit import circuit, pulse
+            with pulse.build() as subroutine:
+                pulse.play(pulse.Gaussian(160, amp, 40), pulse.DriveChannel(0))
 
-        amp1 = circuit.Parameter('amp')
-        amp2 = circuit.Parameter('amp')
+            with pulse.build() as pulse_prog:
+                pulse.call(subroutine, amp=0.1)
+                pulse.call(subroutine, amp=0.3)
 
-        with pulse.build() as subroutine:
-            pulse.play(pulse.Gaussian(160, amp1, 40), pulse.DriveChannel(0))
-            pulse.play(pulse.Gaussian(160, amp2, 40), pulse.DriveChannel(1))
+            print(pulse_prog)
 
-        with pulse.build() as main_prog:
-            pulse.call(subroutine, value_dict={amp1: 0.1, amp2: 0.2})
+        If there is a name collision between parameters, you can distinguish them by specifying
+        each parameter object in a python dictionary. For example,
+
+        .. jupyter-execute::
+
+            amp1 = circuit.Parameter('amp')
+            amp2 = circuit.Parameter('amp')
+
+            with pulse.build() as subroutine:
+                pulse.play(pulse.Gaussian(160, amp1, 40), pulse.DriveChannel(0))
+                pulse.play(pulse.Gaussian(160, amp2, 40), pulse.DriveChannel(1))
+
+            with pulse.build() as pulse_prog:
+                pulse.call(subroutine, value_dict={amp1: 0.1, amp2: 0.3})
+
+            print(pulse_prog)
+
+        2. Calling a schedule
+
+        .. jupyter-execute::
+
+            x_sched = backend.instruction_schedule_map.get("x", (0,))
+
+            with pulse.build(backend) as pulse_prog:
+                pulse.call(x_sched)
+
+            print(pulse_prog)
+
+        Currently, the backend calibrated gates are provided in the form of :class:`~.Schedule`.
+        The parameter assignment mechanism is available also for schedules.
+        However, the called schedule is not treated as a reference.
+
+        3. Calling a quantum circuit
+
+        .. jupyter-execute::
+
+            backend = FakeBogotaV2()
+
+            qc = circuit.QuantumCircuit(1)
+            qc.x(0)
+
+            with pulse.build(backend) as pulse_prog:
+                pulse.call(qc)
+
+            print(pulse_prog)
+
+        .. warning::
+
+            Calling a circuit from a schedule is not encouraged. Currently, the Qiskit execution model
+            is migrating toward the pulse gate model, where schedules are attached to
+            circuits through the :meth:`.QuantumCircuit.add_calibration` method.
 
     Args:
         target: Target circuit or pulse schedule to call.
-        name: Name of subroutine if defined.
-        value_dict: Parameter object and assigned value mapping. This is more precise way to
-            identify a parameter since mapping is managed with unique object id rather than
-            name. Especially there is any name collision in a parameter table.
-        kw_params: Parameter values to bind to the target subroutine
-            with string parameter names. If there are parameter name overlapping,
-            these parameters are updated with the same assigned value.
+        name: Optional. A unique name of subroutine if defined. When the name is explicitly
+            provided, one cannot call different schedule blocks with the same name.
+        value_dict: Optional. Parameters assigned to the ``target`` program.
+            If this dictionary is provided, the ``target`` program is copied and
+            then stored in the main built schedule and its parameters are assigned to the given values.
+            This dictionary is keyed on :class:`~.Parameter` objects,
+            allowing parameter name collision to be avoided.
+        kw_params: Alternative way to provide parameters.
+            Since this is keyed on the string parameter name,
+            the parameters having the same name are all updated together.
+            If you want to avoid name collision, use ``value_dict`` with :class:`~.Parameter`
+            objects instead.
 
     Raises:
         exceptions.PulseError: If the input ``target`` type is not supported.
     """
     if not isinstance(target, (circuit.QuantumCircuit, Schedule, ScheduleBlock)):
-        raise exceptions.PulseError(
-            f'Target of type "{target.__class__.__name__}" is not supported.'
-        )
+        raise exceptions.PulseError(f"'{target.__class__.__name__}' is not a valid target object.")
 
-    _active_builder().call_subroutine(target, name, value_dict, **kw_params)
+    _active_builder().call_subroutine(
+        subroutine=target, name=name, value_dict=value_dict, **kw_params
+    )
+
+
+def reference(name: str, *extra_keys: str):
+    """Refer to undefined subroutine by string keys.
+
+    A :class:`~qiskit.pulse.instructions.Reference` instruction is implicitly created
+    and a schedule can be separately registered to the reference at a later stage.
+
+    .. code-block:: python
+
+        from qiskit import pulse
+
+        with pulse.build() as main_prog:
+            pulse.reference("x_gate", "q0")
+
+        with pulse.build() as subroutine:
+            pulse.play(pulse.Gaussian(160, 0.1, 40), pulse.DriveChannel(0))
+
+        main_prog.assign_references(subroutine_dict={("x_gate", "q0"): subroutine})
+
+    Args:
+        name: Name of subroutine.
+        extra_keys: Helper keys to uniquely specify the subroutine.
+    """
+    _active_builder().append_reference(name, *extra_keys)
 
 
 # Directives

qiskit/pulse/exceptions.py

@@ -37,3 +37,7 @@ class NoActiveBuilder(PulseError):
 
 class UnassignedDurationError(PulseError):
     """Raised if instruction duration is unassigned."""
+
+
+class UnassignedReferenceError(PulseError):
+    """Raised if subroutine is unassigned."""

qiskit/pulse/instructions/__init__.py

@@ -42,6 +42,7 @@
 
    Acquire
    Call
+   Reference
    Delay
    Play
    SetFrequency
@@ -63,3 +64,4 @@
 from .phase import ShiftPhase, SetPhase
 from .play import Play
 from .snapshot import Snapshot
+from .reference import Reference