deprecate legacy pulse builder command

qiskit/pulse/builder.py

@@ -116,6 +116,9 @@
 
    decoupled_bell_prep_and_measure.draw()
 
+.. warning::
+    Calling gates directly within the pulse builder namespace is deprecated as of qiskit 0.46.0.
+
 With the pulse builder we are able to blend programming on qubits and channels.
 While the pulse schedule is based on instructions that operate on
 channels, the pulse builder automatically handles the mapping from qubits to
@@ -228,6 +231,9 @@
            with pulse.phase_offset(math.pi, d0):
                pulse.play(gaussian_pulse, d0)
 
+.. warning::
+    Calling gates directly within the pulse builder namespace is deprecated as of qiskit 0.46.0.
+
 The above is just a small taste of what is possible with the builder. See the rest of the module
 documentation for more information on its capabilities.
 
@@ -373,10 +379,12 @@
 with :func:`call`.
 
 .. warning::
-    These will be removed in future versions with the release of a circuit
-    builder interface in which it will be possible to calibrate a gate in
+
+    Calling gates directly within the pulse builder namespace is deprecated as of qiskit 0.46.0.
+    In favor of a circuit builder interface in which it is now possible to calibrate a gate
     terms of pulses and use that gate in a circuit.
 
+
 .. code-block::
 
     import math
@@ -477,7 +485,7 @@
 from qiskit.pulse.instructions import directives
 from qiskit.pulse.schedule import Schedule, ScheduleBlock
 from qiskit.pulse.transforms.alignments import AlignmentKind
-
+from qiskit.utils.deprecation import deprecate_func, deprecate_arg
 
 #: contextvars.ContextVar[BuilderContext]: active builder
 BUILDER_CONTEXTVAR = contextvars.ContextVar("backend")
@@ -942,6 +950,8 @@ def get_dt(self):
         return self.backend.configuration().dt
 
 
+@deprecate_arg(name="default_transpiler_settings", since="0.46.0")
+@deprecate_arg(name="default_circuit_scheduler_settings", since="0.46.0")
 def build(
     backend=None,
     schedule: Optional[ScheduleBlock] = None,
@@ -1197,6 +1207,7 @@ def _qubits_to_channels(*channels_or_qubits: Union[int, chans.Channel]) -> Set[c
     return channels
 
 
+@deprecate_func(since="0.46.0")
 def active_transpiler_settings() -> Dict[str, Any]:
     """Return the current active builder context's transpiler settings.
 
@@ -1223,6 +1234,7 @@ def active_transpiler_settings() -> Dict[str, Any]:
     return dict(_active_builder().transpiler_settings)
 
 
+@deprecate_func(since="0.46.0")
 def active_circuit_scheduler_settings() -> Dict[str, Any]:
     """Return the current active builder context's circuit scheduler settings.
 
@@ -1507,6 +1519,7 @@ def general_transforms(alignment_context: AlignmentKind) -> ContextManager[None]
         builder.append_subroutine(current)
 
 
+@deprecate_func(since="0.46.0")
 @contextmanager
 def transpiler_settings(**settings) -> ContextManager[None]:
     """Set the currently active transpiler settings for this context.
@@ -1992,6 +2005,12 @@ def snapshot(label: str, snapshot_type: str = "statevector"):
     append_instruction(instructions.Snapshot(label, snapshot_type=snapshot_type))
 
 
+@deprecate_arg(
+    name="target",
+    since="0.46.0",
+    deprecation_description="QuantumCircuit type for the argument target",
+    predicate=lambda qc_arg: isinstance(qc_arg, circuit.QuantumCircuit),
+)
 def call(
     target: Optional[Union[circuit.QuantumCircuit, Schedule, ScheduleBlock]],
     name: Optional[str] = None,
@@ -2210,9 +2229,9 @@ def call(
 
         .. 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.
+            Calling a circuit from a schedule is deprecated as of qiskit 0.46.0. The Qiskit execution
+            model has 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.
@@ -2549,14 +2568,14 @@ def delay_qubits(duration: int, *qubits: Union[int, Iterable[int]]):
 
 
 # Gate instructions
+@deprecate_func(
+    since="0.46.0",
+    additional_msg="Instead use: ``backend.target['gate_name'][(qubit,)].calibration``",
+)
 def call_gate(gate: circuit.Gate, qubits: Tuple[int, ...], lazy: bool = True):
     """Call a gate and lazily schedule it to its corresponding
     pulse instruction.
 
-    .. note::
-        Calling gates directly within the pulse builder namespace will be
-        deprecated in the future in favor of tight integration with a circuit
-        builder interface which is under development.
 
     Examples:
 
@@ -2602,14 +2621,13 @@ def call_gate(gate: circuit.Gate, qubits: Tuple[int, ...], lazy: bool = True):
     _active_builder().call_gate(gate, qubits, lazy=lazy)
 
 
+@deprecate_func(
+    since="0.46.0", additional_msg="Instead use: ``backend.target['cx'][(qubit,)].calibration``"
+)
 def cx(control: int, target: int):  # pylint: disable=invalid-name
     """Call a :class:`~qiskit.circuit.library.standard_gates.CXGate` on the
     input physical qubits.
 
-    .. note::
-        Calling gates directly within the pulse builder namespace will be
-        deprecated in the future in favor of tight integration with a circuit
-        builder interface which is under development.
 
     Examples:
 
@@ -2627,14 +2645,11 @@ def cx(control: int, target: int):  # pylint: disable=invalid-name
     call_gate(gates.CXGate(), (control, target))
 
 
+@deprecate_func(since="0.46.0")
 def u1(theta: float, qubit: int):  # pylint: disable=invalid-name
     """Call a :class:`~qiskit.circuit.library.standard_gates.U1Gate` on the
     input physical qubit.
 
-    .. note::
-        Calling gates directly within the pulse builder namespace will be
-        deprecated in the future in favor of tight integration with a circuit
-        builder interface which is under development.
 
     Examples:
 
@@ -2654,14 +2669,11 @@ def u1(theta: float, qubit: int):  # pylint: disable=invalid-name
     call_gate(gates.U1Gate(theta), qubit)
 
 
+@deprecate_func(since="0.46.0")
 def u2(phi: float, lam: float, qubit: int):  # pylint: disable=invalid-name
     """Call a :class:`~qiskit.circuit.library.standard_gates.U2Gate` on the
     input physical qubit.
 
-    .. note::
-        Calling gates directly within the pulse builder namespace will be
-        deprecated in the future in favor of tight integration with a circuit
-        builder interface which is under development.
 
     Examples:
 
@@ -2681,14 +2693,11 @@ def u2(phi: float, lam: float, qubit: int):  # pylint: disable=invalid-name
     call_gate(gates.U2Gate(phi, lam), qubit)
 
 
+@deprecate_func(since="0.46.0")
 def u3(theta: float, phi: float, lam: float, qubit: int):  # pylint: disable=invalid-name
     """Call a :class:`~qiskit.circuit.library.standard_gates.U3Gate` on the
     input physical qubit.
 
-    .. note::
-        Calling gates directly within the pulse builder namespace will be
-        deprecated in the future in favor of tight integration with a circuit
-        builder interface which is under development.
 
     Examples:
 
@@ -2708,14 +2717,13 @@ def u3(theta: float, phi: float, lam: float, qubit: int):  # pylint: disable=inv
     call_gate(gates.U3Gate(theta, phi, lam), qubit)
 
 
+@deprecate_func(
+    since="0.46.0", additional_msg="Instead use: ``backend.target['x'][(qubit,)].calibration``"
+)
 def x(qubit: int):
     """Call a :class:`~qiskit.circuit.library.standard_gates.XGate` on the
     input physical qubit.
 
-    .. note::
-        Calling gates directly within the pulse builder namespace will be
-        deprecated in the future in favor of tight integration with a circuit
-        builder interface which is under development.
 
     Examples:
 

releasenotes/notes/Deprecate_legacy_pulse_builder_command-2a3c8dcbceae624e.yaml

@@ -0,0 +1,35 @@
+---
+deprecations:
+  - |
+    Deprecated injecting circuit gate operation into the pulse context.
+
+    Deprecated
+    :func:`~qiskit.pulse.builder.call_gate`,
+    :func:`~qiskit.pulse.builder.cx`,
+    :func:`~qiskit.pulse.builder.u1`,
+    :func:`~qiskit.pulse.builder.u2`,
+    :func:`~qiskit.pulse.builder.u3`,
+    :func:`~qiskit.pulse.builder.x`
+
+    .. code-block:: python
+
+       # This example shows how to get pulse gate instructions.
+       from qiskit.providers.fake_provider import FakePerth
+       backend=FakePerth()
+       sched=backend.target['x'][(qubit,)].calibration
+
+    Deprecated
+    :func:`~qiskit.pulse.builder.active_transpiler_settings`
+    :func:`~qiskit.pulse.builder.active_circuit_scheduler_settings`
+    :func:`~qiskit.pulse.builder.transpiler_settings`
+    Modified module doc of :mod:`qiskit.pulse.builder` related with example
+    code with circuit elements.
+    Deprecated arguments :code:`default_transpiler_settings`, :code:`default_circuit_scheduler_settings`
+    in :func:`~qiskit.pulse.builder.build`
+    Deprecated argument of :class:`.QuantumCircuit` type in :func:`~qiskit.pulse.builder.call`
+
+    Modified related tests in
+    :file:`test/python/pulse/test_builder.py`,
+    :file:`test/python/pulse/test_block.py`
+    :file:`test/python/pulse/test_builder_v2.py`
+    :file:`test/python/transpiler/test_calibrationbuilder.py`

test/python/pulse/test_block.py

@@ -793,7 +793,8 @@ def test_filter_channels_nested_block(self):
                 pulse.delay(5, self.d0)
 
                 with pulse.build(self.backend) as cx_blk:
-                    pulse.cx(0, 1)
+                    with self.assertWarns(DeprecationWarning):
+                        pulse.cx(0, 1)
 
                 pulse.call(cx_blk)