Deprecate pulse parameter scoping

qiskit/pulse/schedule.py

@@ -51,6 +51,7 @@
 from qiskit.pulse.instructions import Instruction, Reference
 from qiskit.pulse.utils import instruction_duration_validation
 from qiskit.pulse.reference_manager import ReferenceManager
+from qiskit.utils.deprecation import deprecate_func
 from qiskit.utils.multiprocessing import is_main_process
 
 
@@ -880,6 +881,12 @@ class ScheduleBlock:
 
     .. rubric:: Program Scoping
 
+    .. note::
+
+        The :meth:`~ScheduleBlock.scoped_parameters` and
+        :meth:`~ScheduleBlock.search_parameters` methods described in this
+        section are deprecated.
+
     When you call a subroutine from another subroutine, or append a schedule block
     to another schedule block, the management of references and parameters
     can be a hard task. Schedule block offers a convenient feature to help with this
@@ -1225,9 +1232,22 @@ def parameters(self) -> Set[Parameter]:
 
         return out_params
 
+    @deprecate_func(
+        additional_msg=(
+            "There is no alternative to this method. Parameters must be mapped "
+            "to references by checking the reference schedules directly."
+        ),
+        since="0.46.0",
+        removal_timeline="in the Qiskit 1.0 release",
+    )
     def scoped_parameters(self) -> Tuple[Parameter]:
         """Return unassigned parameters with scoped names.
 
+        .. warning::
+
+            Scoped parameters do not work correctly with Qiskit's data model for parameter
+            assignment.  This implementation is consequently being removed in Qiskit 1.0.
+
         .. note::
 
             If a parameter is defined within a nested scope,
@@ -1623,9 +1643,22 @@ def get_parameters(self, parameter_name: str) -> List[Parameter]:
         matched = [p for p in self.parameters if p.name == parameter_name]
         return matched
 
+    @deprecate_func(
+        additional_msg=(
+            "There is no alternative to this method. Parameters must be mapped "
+            "to references by checking the reference schedules directly."
+        ),
+        since="0.46.0",
+        removal_timeline="in the Qiskit 1.0 release",
+    )
     def search_parameters(self, parameter_regex: str) -> List[Parameter]:
         """Search parameter with regular expression.
 
+        .. warning::
+
+            Scoped parameters do not work correctly with Qiskit's data model for parameter
+            assignment.  This implementation is consequently being removed in Qiskit 1.0.
+
         This method looks for the scope-aware parameters.
         For example,
 

releasenotes/notes/deprecate-pulse-parameter-scoping-6b6b50a394b57937.yaml

@@ -0,0 +1,11 @@
+---
+deprecations:
+  - |
+    The :meth:`.ScheduleBlock.scoped_parameters` and
+    :meth:`.ScheduleBlock.search_parameters` methods have been deprecated.
+    These methods produce :class:`.Parameter` objects with names modified to
+    indicate pulse scoping. The original intention of the methods was that
+    these objects would still link to the original unscoped :class:`.Parameter`
+    objects. However, the modification of the name breaks the link so that
+    assigning using the scoped version does not work. See `#11654
+    <https://github.com/Qiskit/qiskit/issues/11654>`__ for more context.

test/python/pulse/test_reference.py

@@ -56,14 +56,16 @@ def test_append_schedule_parameter_scope(self):
         with pulse.build() as sched_z1:
             builder.append_schedule(sched_y1)
 
-        sched_param = next(iter(sched_z1.scoped_parameters()))
+        with self.assertWarns(DeprecationWarning):
+            sched_param = next(iter(sched_z1.scoped_parameters()))
         self.assertEqual(sched_param.name, "root::name")
 
         # object equality
-        self.assertEqual(
-            sched_z1.search_parameters("root::name")[0],
-            param,
-        )
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(
+                sched_z1.search_parameters("root::name")[0],
+                param,
+            )
 
     def test_refer_schedule(self):
         """Test refer to schedule by name.
@@ -108,20 +110,23 @@ def test_refer_schedule_parameter_scope(self):
         sched_y1.assign_references({("x1", "d0"): sched_x1})
         sched_z1.assign_references({("y1", "d0"): sched_y1})
 
-        sched_param = next(iter(sched_z1.scoped_parameters()))
+        with self.assertWarns(DeprecationWarning):
+            sched_param = next(iter(sched_z1.scoped_parameters()))
         self.assertEqual(sched_param.name, "root::y1,d0::x1,d0::name")
 
         # object equality
-        self.assertEqual(
-            sched_z1.search_parameters("root::y1,d0::x1,d0::name")[0],
-            param,
-        )
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(
+                sched_z1.search_parameters("root::y1,d0::x1,d0::name")[0],
+                param,
+            )
 
         # regex
-        self.assertEqual(
-            sched_z1.search_parameters(r"\S::x1,d0::name")[0],
-            param,
-        )
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(
+                sched_z1.search_parameters(r"\S::x1,d0::name")[0],
+                param,
+            )
 
     def test_call_schedule(self):
         """Test call schedule.
@@ -160,20 +165,23 @@ def test_call_schedule_parameter_scope(self):
         with pulse.build() as sched_z1:
             builder.call(sched_y1, name="y1")
 
-        sched_param = next(iter(sched_z1.scoped_parameters()))
+        with self.assertWarns(DeprecationWarning):
+            sched_param = next(iter(sched_z1.scoped_parameters()))
         self.assertEqual(sched_param.name, "root::y1::x1::name")
 
         # object equality
-        self.assertEqual(
-            sched_z1.search_parameters("root::y1::x1::name")[0],
-            param,
-        )
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(
+                sched_z1.search_parameters("root::y1::x1::name")[0],
+                param,
+            )
 
         # regex
-        self.assertEqual(
-            sched_z1.search_parameters(r"\S::x1::name")[0],
-            param,
-        )
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(
+                sched_z1.search_parameters(r"\S::x1::name")[0],
+                param,
+            )
 
     def test_append_and_call_schedule(self):
         """Test call and append schedule.
@@ -368,7 +376,8 @@ def test_special_parameter_name(self):
             pulse.reference("sub", "q0")
         sched_y1.assign_references({("sub", "q0"): sched_x1})
 
-        ret_param = sched_y1.search_parameters(r"\Ssub,q0::my.parameter_object")[0]
+        with self.assertWarns(DeprecationWarning):
+            ret_param = sched_y1.search_parameters(r"\Ssub,q0::my.parameter_object")[0]
 
         self.assertEqual(param, ret_param)
 
@@ -392,10 +401,13 @@ def test_parameter_in_multiple_scope(self):
             pulse.call(sched_y1, name="y1")
 
         self.assertEqual(len(sched_z1.parameters), 1)
-        self.assertEqual(len(sched_z1.scoped_parameters()), 2)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(len(sched_z1.scoped_parameters()), 2)
 
-        self.assertEqual(sched_z1.search_parameters("root::x1::name")[0], param)
-        self.assertEqual(sched_z1.search_parameters("root::y1::name")[0], param)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(sched_z1.search_parameters("root::x1::name")[0], param)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(sched_z1.search_parameters("root::y1::name")[0], param)
 
     def test_parallel_alignment_equality(self):
         """Testcase for potential edge case.
@@ -558,7 +570,8 @@ def test_lazy_ecr(self):
         self.assertSetEqual(params, {"cr"})
 
         # Parameter names are scoepd
-        scoped_params = {p.name for p in sched.scoped_parameters()}
+        with self.assertWarns(DeprecationWarning):
+            scoped_params = {p.name for p in sched.scoped_parameters()}
         self.assertSetEqual(scoped_params, {"root::cr"})
 
         # Assign CR and XP schedule to the empty reference
@@ -571,7 +584,8 @@ def test_lazy_ecr(self):
         self.assertEqual(assigned_refs[("xp", "q0")], self.xp_sched)
 
         # Parameter added from subroutines
-        scoped_params = {p.name for p in sched.scoped_parameters()}
+        with self.assertWarns(DeprecationWarning):
+            scoped_params = {p.name for p in sched.scoped_parameters()}
         ref_params = {
             # This is the cr parameter that belongs to phase_offset instruction in the root scope
             "root::cr",
@@ -594,7 +608,8 @@ def test_lazy_ecr(self):
         self.assertEqual(len(params), 2)
 
         # Get parameter with scope, only xp amp
-        params = sched.search_parameters(parameter_regex="root::xp,q0::amp")
+        with self.assertWarns(DeprecationWarning):
+            params = sched.search_parameters(parameter_regex="root::xp,q0::amp")
         self.assertEqual(len(params), 1)
 
     def test_cnot(self):
@@ -614,11 +629,13 @@ def test_cnot(self):
             pulse.call(ecr_sched, name="ecr")
 
         # get parameter with scope, full scope is not needed
-        xp_amp = cx_sched.search_parameters(r"\S:xp::amp")[0]
+        with self.assertWarns(DeprecationWarning):
+            xp_amp = cx_sched.search_parameters(r"\S:xp::amp")[0]
         self.assertEqual(self.xp_amp, xp_amp)
 
         # get parameter with scope, of course full scope can be specified
-        xp_amp_full_scoped = cx_sched.search_parameters("root::ecr::xp::amp")[0]
+        with self.assertWarns(DeprecationWarning):
+            xp_amp_full_scoped = cx_sched.search_parameters("root::ecr::xp::amp")[0]
         self.assertEqual(xp_amp_full_scoped, xp_amp)
 
         # assign parameters