ScheduleBlock 2/4 - add Call instruction

qiskit/pulse/builder.py

@@ -218,6 +218,7 @@
 
 from qiskit import circuit
 from qiskit.circuit.library import standard_gates as gates
+from qiskit.circuit.parameterexpression import ParameterExpression, ParameterValueType
 from qiskit.pulse import (
     channels as chans,
     configuration,
@@ -451,7 +452,8 @@ def call_schedule(self, schedule: Schedule):
     def call_subroutine(self,
                         subroutine: Union[circuit.QuantumCircuit, Schedule],
                         name: Optional[str] = None,
-                        **kw_params):
+                        value_dict: Optional[Dict[ParameterExpression, ParameterValueType]] = None,
+                        **kw_params: ParameterValueType):
         """Call a schedule or circuit defined outside of the current scope.
 
         The ``subroutine`` is appended to the context schedule as a call instruction.
@@ -462,24 +464,37 @@ def call_subroutine(self,
         Args:
             subroutine: Target schedule or circuit to append to the current context.
             name: Name of subroutine if defined.
-            kw_params: Parameter values to bind to the target subroutine.
+            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.
+
+        Raises:
+            PulseError: If specified parameter is not contained in the subroutine.
         """
         if isinstance(subroutine, circuit.QuantumCircuit):
             self._compile_lazy_circuit()
             subroutine = self._compile_circuit(subroutine)
 
         if len(subroutine.instructions) > 0:
-            value_dict = dict()
+            if value_dict is None:
+                value_dict = dict()
+
+            param_value_map = dict()
             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:
-                        value_dict[param_obj] = assigned_value
+                        param_value_map[param_obj] = assigned_value
                 else:
-                    warnings.warn(f'Parameter {param_name} is not defined in the '
-                                  'target subroutine. Parameter assignment is ignored.',
-                                  UserWarning)
-            call_def = instructions.Call(subroutine, value_dict, name)
+                    raise exceptions.PulseError(
+                        f'Parameter {param_name} is not defined in the target subroutine. '
+                        f'{", ".join(map(str, subroutine.parameters))} can be specified.')
+
+            param_value_map.update(value_dict)
+            call_def = instructions.Call(subroutine, param_value_map, name)
 
             self.append_instruction(call_def)
 
@@ -1689,7 +1704,10 @@ def call_circuit(circ: circuit.QuantumCircuit):
     call(circ)
 
 
-def call(target: Union[circuit.QuantumCircuit, Schedule], **kw_params):
+def call(target: Union[circuit.QuantumCircuit, Schedule],
+         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
     parameters which will be assigned to the target program.
 
@@ -1700,7 +1718,7 @@ def call(target: Union[circuit.QuantumCircuit, Schedule], **kw_params):
 
     Examples:
 
-    .. jupyter-execute::
+    .. code-block:: python
 
         from qiskit import circuit, pulse, schedule, transpile
         from qiskit.test.mock import FakeOpenPulse2Q
@@ -1718,7 +1736,7 @@ def call(target: Union[circuit.QuantumCircuit, Schedule], **kw_params):
 
     This function can optionally take parameter dictionary with the parameterized target program.
 
-    .. jupyter-execute::
+    .. code-block:: python
 
         from qiskit import circuit, pulse
 
@@ -1731,9 +1749,33 @@ def call(target: Union[circuit.QuantumCircuit, Schedule], **kw_params):
             pulse.call(subroutine, amp=0.1)
             pulse.call(subroutine, amp=0.3)
 
+    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.
+
+    .. code-block:: python
+
+        from qiskit import circuit, pulse
+
+        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 main_prog:
+            pulse.call(subroutine, value_dict={amp1: 0.1, amp2: 0.2})
+
     Args:
         target: Target circuit or pulse schedule to call.
-        kw_params: Parameter values to bind to the target subroutine.
+        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.
 
     Raises:
         exceptions.PulseError: If the input ``target`` type is not supported.
@@ -1742,7 +1784,7 @@ def call(target: Union[circuit.QuantumCircuit, Schedule], **kw_params):
         raise exceptions.PulseError(
             'Target of type "{}" is not supported.'.format(type(target)))
 
-    _active_builder().call_subroutine(target, **kw_params)
+    _active_builder().call_subroutine(target, name, value_dict, **kw_params)
 
 
 # Directives

test/python/pulse/test_builder.py

@@ -1109,13 +1109,10 @@ def test_call_with_not_existing_parameter(self):
         with pulse.build() as subroutine:
             pulse.play(pulse.Gaussian(160, amp, 40), pulse.DriveChannel(0))
 
-        with self.assertWarns(UserWarning):
-            with pulse.build() as sched:
+        with self.assertRaises(exceptions.PulseError):
+            with pulse.build():
                 pulse.call(subroutine, amp=0.1)
 
-        # just ignored
-        self.assertTrue(sched.is_parameterized())
-
     def test_call_with_common_parameter(self):
         """Test call subroutine with parameter that is defined multiple times."""
         amp = circuit.Parameter('amp')
@@ -1134,3 +1131,26 @@ def test_call_with_common_parameter(self):
 
         self.assertEqual(play_0.pulse.amp, 0.1)
         self.assertEqual(play_1.pulse.amp, 0.1)
+
+    def test_call_with_parameter_name_collision(self):
+        """Test call subroutine with duplicated parameter names."""
+        amp1 = circuit.Parameter('amp')
+        amp2 = circuit.Parameter('amp')
+        sigma = circuit.Parameter('sigma')
+
+        with pulse.build() as subroutine:
+            pulse.play(pulse.Gaussian(160, amp1, sigma), pulse.DriveChannel(0))
+            pulse.play(pulse.Gaussian(160, amp2, sigma), pulse.DriveChannel(0))
+
+        with pulse.build() as main_prog:
+            pulse.call(subroutine, value_dict={amp1: 0.1, amp2: 0.2}, sigma=40)
+
+        assigned_sched = inline_subroutines(main_prog)
+
+        play_0 = assigned_sched.instructions[0][1]
+        play_1 = assigned_sched.instructions[1][1]
+
+        self.assertEqual(play_0.pulse.amp, 0.1)
+        self.assertEqual(play_0.pulse.sigma, 40)
+        self.assertEqual(play_1.pulse.amp, 0.2)
+        self.assertEqual(play_1.pulse.sigma, 40)