Add AnnotatedOperation.params and fix some control issues

qiskit/circuit/annotated_operation.py

@@ -230,7 +230,7 @@ def params(self, value: list[ParameterValueType]):
         if hasattr(self.base_op, "params"):
             self.base_op.params = value
         else:
-            raise NotImplementedError(
+            raise AttributeError(
                 f"Cannot set attribute ``params`` on the base operation {self.base_op}."
             )
 
@@ -239,9 +239,7 @@ def validate_parameter(self, parameter: ParameterValueType) -> ParameterValueTyp
         if hasattr(self.base_op, "validate_parameter"):
             return self.base_op.validate_parameter(parameter)
 
-        raise NotImplementedError(
-            f"Cannot set validate parameters on the base operation {self.base_op}."
-        )
+        raise AttributeError(f"Cannot validate parameters on the base operation {self.base_op}.")
 
 
 def _canonicalize_modifiers(modifiers):

qiskit/circuit/gate.py

@@ -118,7 +118,11 @@ def control(
             ctrl_state: the control state in decimal or as a bitstring
                 (e.g. ``'111'``). If ``None``, use ``2**num_ctrl_qubits-1``.
             annotated: indicates whether the controlled gate is implemented
-                as an annotated gate. If ``None``, this is handled as ``False``.
+                as an annotated gate. If ``None``, this is set to ``False``,
+                if the controlled gate can directly be constructed, and otherwise
+                set to ``True``. This allows defering the construction process in case the
+                synthesis of the controlled gate requires more information (e.g.
+                values of unbound parameters).
 
         Returns:
             Controlled version of the given operation.

qiskit/circuit/library/generalized_gates/unitary.py

@@ -174,7 +174,7 @@ def control(
             label: Optional gate label.
             ctrl_state: The control state in decimal or as a bit string (e.g. ``"1011"``).
                 If ``None``, use ``2**num_ctrl_qubits - 1``.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is handled as ``False``.
 
         Returns:

qiskit/circuit/library/standard_gates/h.py

@@ -95,7 +95,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is handled as ``False``.
 
         Returns:

qiskit/circuit/library/standard_gates/p.py

@@ -108,7 +108,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g. ``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is handled as ``False``.
 
         Returns:
@@ -264,7 +264,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is handled as ``False``.
 
         Returns:
@@ -405,7 +405,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is handled as ``False``.
 
         Returns:

qiskit/circuit/library/standard_gates/rx.py

@@ -91,10 +91,10 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
-                as an annotated gate. If ``None``, this is set to ``False``, unless the
-                gate contains free parameters and has more than one control qubit,
-                in which case it cannot yet be synthesized.
+            annotated: indicates whether the controlled gate should be implemented
+                as an annotated gate. If ``None``, this is set to ``True`` if
+                the gate contains free parameters and more than one control qubit, in which
+                case it cannot yet be synthesized. Otherwise it is set to ``False``.
 
         Returns:
             ControlledGate: controlled version of this gate.

qiskit/circuit/library/standard_gates/rxx.py

@@ -128,7 +128,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is set to ``True`` if
                 the gate contains free parameters, in which case it cannot
                 yet be synthesized.

qiskit/circuit/library/standard_gates/ry.py

@@ -90,10 +90,10 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
-                as an annotated gate. If ``None``, this is set to ``False``, unless the
-                gate contains free parameters and has more than one control qubit,
-                in which case it cannot yet be synthesized.
+            annotated: indicates whether the controlled gate should be implemented
+                as an annotated gate. If ``None``, this is set to ``True`` if
+                the gate contains free parameters and more than one control qubit, in which
+                case it cannot yet be synthesized. Otherwise it is set to ``False``.
 
         Returns:
             ControlledGate: controlled version of this gate.

qiskit/circuit/library/standard_gates/ryy.py

@@ -128,7 +128,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is set to ``True`` if
                 the gate contains free parameters, in which case it cannot
                 yet be synthesized.

qiskit/circuit/library/standard_gates/rz.py

@@ -102,10 +102,10 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
-                as an annotated gate. If ``None``, this is set to ``False``, unless the
-                gate contains free parameters and has more than one control qubit,
-                in which case it cannot yet be synthesized.
+            annotated: indicates whether the controlled gate should be implemented
+                as an annotated gate. If ``None``, this is set to ``True`` if
+                the gate contains free parameters and more than one control qubit, in which
+                case it cannot yet be synthesized. Otherwise it is set to ``False``.
 
         Returns:
             ControlledGate: controlled version of this gate.

qiskit/circuit/library/standard_gates/rzx.py

@@ -172,7 +172,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is set to ``True`` if
                 the gate contains free parameters, in which case it cannot
                 yet be synthesized.

qiskit/circuit/library/standard_gates/rzz.py

@@ -136,7 +136,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is set to ``True`` if
                 the gate contains free parameters, in which case it cannot
                 yet be synthesized.

qiskit/circuit/library/standard_gates/s.py

@@ -101,7 +101,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is handled as ``False``.
 
         Returns:
@@ -213,7 +213,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is handled as ``False``.
 
         Returns:

qiskit/circuit/library/standard_gates/swap.py

@@ -105,7 +105,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is handled as ``False``.
 
         Returns:

qiskit/circuit/library/standard_gates/sx.py

@@ -119,7 +119,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is handled as ``False``.
 
         Returns:

qiskit/circuit/library/standard_gates/u.py

@@ -117,10 +117,10 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
-                as an annotated gate. If ``None``, this is set to ``False``, unless the
-                gate contains free parameters and has more than one control qubit,
-                in which case it cannot yet be synthesized.
+            annotated: indicates whether the controlled gate should be implemented
+                as an annotated gate. If ``None``, this is set to ``True`` if
+                the gate contains free parameters and more than one control qubit, in which
+                case it cannot yet be synthesized. Otherwise it is set to ``False``.
 
         Returns:
             ControlledGate: controlled version of this gate.

qiskit/circuit/library/standard_gates/u1.py

@@ -128,7 +128,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate.
 
         Returns:
@@ -278,7 +278,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate.
 
         Returns:
@@ -410,7 +410,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate.
 
         Returns:

qiskit/circuit/library/standard_gates/u3.py

@@ -129,10 +129,10 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
-                as an annotated gate. If ``None``, this is set to ``False``, unless the
-                gate contains free parameters and has more than one control qubit,
-                in which case it cannot yet be synthesized.
+            annotated: indicates whether the controlled gate should be implemented
+                as an annotated gate. If ``None``, this is set to ``True`` if
+                the gate contains free parameters and more than one control qubit, in which
+                case it cannot yet be synthesized. Otherwise it is set to ``False``.
 
         Returns:
             ControlledGate: controlled version of this gate.

qiskit/circuit/library/standard_gates/x.py

@@ -112,7 +112,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g. ``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate.
 
         Returns:
@@ -257,7 +257,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g. ``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate.
 
         Returns:
@@ -453,7 +453,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g. ``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate.
 
         Returns:
@@ -801,7 +801,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g. ``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate.
 
         Returns:
@@ -1047,7 +1047,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g. ``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate.
 
         Returns:
@@ -1222,7 +1222,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g. ``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate.
 
         Returns:

qiskit/circuit/library/standard_gates/xx_minus_yy.py

@@ -173,7 +173,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is set to ``True`` if
                 the gate contains free parameters, in which case it cannot
                 yet be synthesized.

qiskit/circuit/library/standard_gates/xx_plus_yy.py

@@ -177,7 +177,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate. If ``None``, this is set to ``True`` if
                 the gate contains free parameters, in which case it cannot
                 yet be synthesized.

qiskit/circuit/library/standard_gates/y.py

@@ -108,7 +108,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate.
 
         Returns:

qiskit/circuit/library/standard_gates/z.py

@@ -112,7 +112,7 @@ def control(
             label: An optional label for the gate [Default: ``None``]
             ctrl_state: control state expressed as integer,
                 string (e.g.``'110'``), or ``None``. If ``None``, use all 1s.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate.
 
         Returns:

qiskit/circuit/quantumcircuit.py

@@ -1717,7 +1717,7 @@ def control(
             label (str): An optional label to give the controlled operation for visualization.
             ctrl_state (str or int): The control state in decimal or as a bitstring
                 (e.g. '111'). If None, use ``2**num_ctrl_qubits - 1``.
-            annotated: indicates whether the controlled gate can be implemented
+            annotated: indicates whether the controlled gate should be implemented
                 as an annotated gate.
 
         Returns: