Deprecate control_wires in ControlledQubitUnitary (#6839)

**Context:**
We are in favor of `wires`, just like what we did with
`MultiControlledX`.

!Note: this involves a big user-interface change. With PL version
<=0.40, for ControlledQubitUnitary, we have arg wires to be the
target_wires, and the arg control_wires is a positional arg. To be
consistent with all the other interfaces, we would like to alter this
into wires to be positional and to represent control_wires+target_wires

Before:
```python
mat = np.eye(2)
control_wires = [0]
wires = [1]
ControlledQubitUnitary(mat, control_wires, wires=wires, control_values=...)
```

After:
```python
mat = np.eye(2)
wires = [0, 1]
ControlledQubitUnitary(mat, wires, control_values=...)
```

where the new `wires` should be the concatenate of old `control_wires`
and `wires`

**Description of the Change:**
Besides the modified test files across the whole codebase involving
`ControlledQubitUnitary`, we made the following necessary adjustments
beyond the `__init__` method:
- classmethod `_unflatten`, `_primitive_bind_call` and method
`_controlled` were adjusted accordingly following the new interface
 - move the `TypeError` regarding empty arg `wires` to the beginning.
- add a register for `ControlledQubitUnitary` in
`bind_new_parameters.py` following the pattern of `CRX`
- modified the direct calls of `ControlledQubitUnitary` inside src files
`metric_tensor.py`, `controlled.py` and `matrix_ops.py`.

### **Eco-System**
This is an inevitable breaking change, so we need to immediately inform
the affected repos that depend on latest PennyLane but only apply
corresponding changes after this PR gets merged.

- [ ] labs

- [ ] Catalyst:
[frontend/test/pytest/device/test_decomposition.py](https://github.com/PennyLaneAI/catalyst/blob/286e51910a39c55130de8c1c6a806818a2bcb14b/frontend/test/pytest/device/test_decomposition.py#L52)
PennyLaneAI/catalyst#1483

- [ ] Lightning: PR to fix it
PennyLaneAI/pennylane-lightning#1047
- -
[test_gates.py](https://github.com/PennyLaneAI/pennylane-lightning/blob/290c986e7d087e17dbf3f09c6d2dfc8bd738cc08/tests/test_gates.py#L451)
- -
[test_gates_and_expval.py](https://github.com/PennyLaneAI/pennylane-lightning/blob/290c986e7d087e17dbf3f09c6d2dfc8bd738cc08/tests/lightning_tensor/test_gates_and_expval.py#L72)
- -
[test_measurements_class.py](https://github.com/PennyLaneAI/pennylane-lightning/blob/290c986e7d087e17dbf3f09c6d2dfc8bd738cc08/tests/lightning_qubit/test_measurements_class.py#L814)

- [ ] QML Demos:
[tutorial_classically_boosted_vqe.py](https://github.com/PennyLaneAI/qml/blob/c444cec6201338056304d9d5a293f969a3aeec5e/demonstrations/tutorial_classically_boosted_vqe.py#L451);
PR to fix it PennyLaneAI/qml#1310

### **Plugins**
- [x] Pennylane-AQT: No instances of deprecated code found.
- [x] Pennylane-Qiskit: No instances of deprecated code found.
- [x] Pennylane-IonQ: No instances of deprecated code found.
- [x] Pennylane-Qrack: No instances of deprecated code found.
- [x] Pennylane-Cirq: No instances of deprecated code found.
- [x] Pennylane-Qulacs: No instances of deprecated code found.

**Benefits:**
Unified interfaces with other controlled ops.

**Possible Drawbacks:**
This is a hard change to deprecate this arg. Would have to introduce
errors for testing matrices.

**Related GitHub Issues:**
[sc-80842]

---------

Co-authored-by: Christina Lee <[email protected]>
Co-authored-by: Astral Cai <[email protected]>

Author: 3 people

doc/development/deprecations.rst

@@ -9,6 +9,16 @@ deprecations are listed below.
 Pending deprecations
 --------------------
 
+* The ``ControlledQubitUnitary`` will stop accepting `QubitUnitary` objects as arguments as its ``base``. Instead, use ``qml.ctrl`` to construct a controlled `QubitUnitary`.
+
+  - Deprecated in v0.41
+  - Will be removed in v0.42
+
+* The ``control_wires`` argument in the ``qml.ControlledQubitUnitary`` class is deprecated. Instead, use the ``wires`` argument.
+
+  - Deprecated in v0.41
+  - Will be removed in v0.42
+
 * The property ```MeasurementProcess.return_type``` has been deprecated.
   If observable type checking is needed, please use direct ```isinstance```; if other text information is needed, please use class name, or another internal temporary private member ``_shortname``.
 

doc/releases/changelog-dev.md

@@ -74,6 +74,7 @@
   [(#6803)](https://github.com/PennyLaneAI/pennylane/pull/6803)
 
   After constructing a `QNode`,
+
   ```python
   import pennylane as qml
 
@@ -83,8 +84,10 @@
     qml.CNOT([0,1])
     return qml.probs()
   ```
+
   its settings can be modified with `update`, which returns a new `QNode` object. Here is an example
   of updating a QNode's `diff_method`:
+  
   ```pycon
   >>> print(circuit.diff_method)
   best
@@ -158,6 +161,13 @@
 
 <h3>Deprecations 👋</h3>
 
+* The ``ControlledQubitUnitary`` will stop accepting `QubitUnitary` objects as arguments as its ``base``. Instead, use ``qml.ctrl`` to construct a controlled `QubitUnitary`.
+  [(#6840)](https://github.com/PennyLaneAI/pennylane/pull/6840)
+
+* The `control_wires` argument in `qml.ControlledQubitUnitary` has been deprecated.
+  Instead, use the `wires` argument as the second positional argument.
+  [(#6839)](https://github.com/PennyLaneAI/pennylane/pull/6839)
+
 * The `mcm_method` keyword in `qml.execute` has been deprecated. 
   Instead, use the ``mcm_method`` and ``postselect_mode`` arguments.
   [(#6807)](https://github.com/PennyLaneAI/pennylane/pull/6807)

pennylane/devices/tests/test_gates.py

@@ -72,7 +72,7 @@
     "QubitDensityMatrix": qml.QubitDensityMatrix(np.array([[0.5, 0.0], [0, 0.5]]), wires=[0]),
     "QubitUnitary": qml.QubitUnitary(np.eye(2), wires=[0]),
     "SpecialUnitary": qml.SpecialUnitary(np.array([0.2, -0.1, 2.3]), wires=1),
-    "ControlledQubitUnitary": qml.ControlledQubitUnitary(np.eye(2), control_wires=[1], wires=[0]),
+    "ControlledQubitUnitary": qml.ControlledQubitUnitary(np.eye(2), wires=[1, 0]),
     "MultiControlledX": qml.MultiControlledX(wires=[1, 2, 0]),
     "IntegerComparator": qml.IntegerComparator(1, geq=True, wires=[0, 1, 2]),
     "RX": qml.RX(0, wires=[0]),

pennylane/devices/tests/test_templates.py

@@ -678,7 +678,7 @@ def func(i):
         target_wires = range(m + 1)
         estimation_wires = range(m + 1, n + m + 1)
         dev = device(wires=n + m + 1)
-        check_op_supported(qml.ControlledQubitUnitary(np.eye(2), [1], [0]), dev)
+        check_op_supported(qml.ControlledQubitUnitary(np.eye(2), wires=[1, 0]), dev)
 
         @qml.qnode(dev)
         def circuit():

pennylane/gradients/metric_tensor.py

@@ -73,7 +73,9 @@ def _expand_metric_tensor(
     allow_nonunitary=True,
     aux_wire=None,
     device_wires=None,
-) -> tuple[QuantumScriptBatch, PostprocessingFn]:  # pylint: disable=too-many-arguments
+) -> tuple[
+    QuantumScriptBatch, PostprocessingFn
+]:  # pylint: disable=too-many-arguments, too-many-positional-arguments
     """Set the metric tensor based on whether non-unitary gates are allowed."""
     # pylint: disable=unused-argument,too-many-arguments
 
@@ -88,7 +90,7 @@ def _expand_metric_tensor(
     classical_cotransform=_contract_metric_tensor_with_cjac,
     final_transform=True,
 )
-def metric_tensor(  # pylint:disable=too-many-arguments
+def metric_tensor(  # pylint:disable=too-many-arguments, too-many-positional-arguments
     tape: QuantumScript,
     argnum=None,
     approx=None,
@@ -561,7 +563,8 @@ def _get_gen_op(op, allow_nonunitary, aux_wire):
     except KeyError as e:
         if allow_nonunitary:
             mat = qml.matrix(qml.generator(op)[0])
-            return qml.ControlledQubitUnitary(mat, control_wires=aux_wire, wires=op.wires)
+            wires = [aux_wire, *op.wires]
+            return qml.ControlledQubitUnitary(mat, wires=wires)
 
         raise ValueError(
             f"Generator for operation {op} not known and non-unitary operations "

pennylane/ops/functions/bind_new_parameters.py

@@ -163,6 +163,7 @@ def bind_new_parameters_copy(op, params: Sequence[TensorLike]):  # pylint:disabl
 @bind_new_parameters.register(qml.CRZ)
 @bind_new_parameters.register(qml.CRot)
 @bind_new_parameters.register(qml.ControlledPhaseShift)
+@bind_new_parameters.register(qml.ControlledQubitUnitary)
 def bind_new_parameters_parametric_controlled_ops(
     op: Union[qml.CRX, qml.CRY, qml.CRZ, qml.CRot, qml.ControlledPhaseShift],
     params: Sequence[TensorLike],

pennylane/ops/op_math/controlled.py

@@ -339,7 +339,10 @@ def _try_wrap_in_custom_ctrl_op(op, control, control_values=None, work_wires=Non
 
     if isinstance(op, qml.QubitUnitary):
         return qml.ControlledQubitUnitary(
-            op, control_wires=control, control_values=control_values, work_wires=work_wires
+            op.matrix(),
+            wires=control + op.wires,
+            control_values=control_values,
+            work_wires=work_wires,
         )
 
     return None

pennylane/ops/op_math/controlled_ops.py

@@ -34,17 +34,31 @@
 INV_SQRT2 = 1 / qml.math.sqrt(2)
 
 
+def _deprecate_control_wires(control_wires):
+    if control_wires != "unset":
+        warnings.warn(
+            "The control_wires input to ControlledQubitUnitary is deprecated and will be removed in v0.42. "
+            "Please note that the second positional arg of your input is going to be the new wires, following wires=controlled_wires+target_wires, where target_wires is the optional arg wires in the legacy interface.",
+            qml.PennyLaneDeprecationWarning,
+        )
+
+
 # pylint: disable=too-few-public-methods
 class ControlledQubitUnitary(ControlledOp):
-    r"""ControlledQubitUnitary(U, control_wires, wires, control_values)
-    Apply an arbitrary fixed unitary to ``wires`` with control from the ``control_wires``.
+    r"""ControlledQubitUnitary(U, wires)
+    Apply an arbitrary fixed unitary matrix ``U`` to ``wires``. If ``n = len(wires) `` and ``U`` has ``k`` wires, then the first ``n - k`` from ``wires`` serve as control, and ``U`` lives on the last ``k`` wires.
+
+    .. warning::
+
+        The ``control_wires`` argument is deprecated and will be removed in
+        v0.42. Please use the ``wires`` argument instead.
 
     In addition to default ``Operation`` instance attributes, the following are
     available for ``ControlledQubitUnitary``:
 
-    * ``control_wires``: wires that act as control for the operation
+    * ``control_wires``: (deprecated) wires that act as control for the operation
+    * ``wires``: wires of the final controlled unitary, consisting of control wires following by target wires
     * ``control_values``: the state on which to apply the controlled operation (see below)
-    * ``target_wires``: the wires the unitary matrix will be applied to
     * ``work_wires``: wires made use of during the decomposition of the operation into native operations
 
     **Details:**
@@ -59,9 +73,10 @@ class ControlledQubitUnitary(ControlledOp):
             operation. If passing a matrix, this will be used to construct a QubitUnitary
             operator that will be used as the base operator. If providing a ``qml.QubitUnitary``,
             this will be used as the base directly.
-        control_wires (Union[Wires, Sequence[int], or int]): the control wire(s)
-        wires (Union[Wires, Sequence[int], or int]): the wire(s) the unitary acts on
-            (optional if U is provided as a QubitUnitary)
+        wires (Union[Wires, Sequence[int], or int]): the wires the full
+        controlled unitary acts on, composed of the controlled wires followed
+        by the target wires
+        control_wires (Union[Wires, Sequence[int], or int]): (deprecated) the control wire(s)
         control_values (List[int, bool]): a list providing the state of the control qubits to
             control on (default is the all 1s state)
         unitary_check (bool): whether to check whether an array U is unitary when creating the
@@ -75,16 +90,9 @@ class ControlledQubitUnitary(ControlledOp):
     both wires ``0`` and ``1``:
 
     >>> U = np.array([[ 0.94877869,  0.31594146], [-0.31594146,  0.94877869]])
-    >>> qml.ControlledQubitUnitary(U, control_wires=[0, 1], wires=2)
+    >>> qml.ControlledQubitUnitary(U, wires=[0, 1, 2])
     Controlled(QubitUnitary(array([[ 0.94877869,  0.31594146],
-       [-0.31594146,  0.94877869]]), wires=[2]), control_wires=[0, 1])
-
-    Alternatively, the same operator can be constructed with a QubitUnitary:
-
-    >>> base = qml.QubitUnitary(U, wires=2)
-    >>> qml.ControlledQubitUnitary(base, control_wires=[0, 1])
-    Controlled(QubitUnitary(array([[ 0.94877869,  0.31594146],
-       [-0.31594146,  0.94877869]]), wires=[2]), control_wires=[0, 1])
+        [-0.31594146,  0.94877869]]), wires=[2]), control_wires=[0, 1])
 
     Typically, controlled operations apply a desired gate if the control qubits
     are all in the state :math:`\vert 1\rangle`. However, there are some situations where
@@ -96,11 +104,11 @@ class ControlledQubitUnitary(ControlledOp):
     wire ``3`` conditioned on three wires where the first is in state ``0``, the
     second is in state ``1``, and the third in state ``1``, we can write:
 
-    >>> qml.ControlledQubitUnitary(U, control_wires=[0, 1, 2], wires=3, control_values=[0, 1, 1])
+    >>> qml.ControlledQubitUnitary(U, wires=[0, 1, 2, 3], control_values=[0, 1, 1])
 
     or
 
-    >>> qml.ControlledQubitUnitary(U, control_wires=[0, 1, 2], wires=3, control_values=[False, True, True])
+    >>> qml.ControlledQubitUnitary(U, wires=[0, 1, 2, 3], control_values=[False, True, True])
     """
 
     num_wires = AnyWires
@@ -115,31 +123,41 @@ class ControlledQubitUnitary(ControlledOp):
     grad_method = None
     """Gradient computation method."""
 
+    def _flatten(self):
+        return (self.base.data[0],), (self.wires, tuple(self.control_values), self.work_wires)
+
     @classmethod
     def _unflatten(cls, data, metadata):
-        return cls(
-            data[0], control_wires=metadata[0], control_values=metadata[1], work_wires=metadata[2]
-        )
+        return cls(data[0], wires=metadata[0], control_values=metadata[1], work_wires=metadata[2])
 
     # pylint: disable=arguments-differ, too-many-arguments, unused-argument, too-many-positional-arguments
     @classmethod
     def _primitive_bind_call(
         cls,
         base,
-        control_wires: WiresLike,
-        wires: WiresLike = (),
+        control_wires: WiresLike = "unset",
+        wires: WiresLike = None,
         control_values=None,
         unitary_check=False,
         work_wires: WiresLike = (),
     ):
-        wires = Wires(() if wires is None else wires)
+        _deprecate_control_wires(control_wires)
         work_wires = Wires(() if work_wires is None else work_wires)
-
-        if hasattr(base, "wires") and len(wires) != 0:
+        if hasattr(base, "wires"):
             warnings.warn(
-                "base operator already has wires; values specified through wires kwarg will be ignored."
+                "QubitUnitary input to ControlledQubitUnitary is deprecated and will be removed in v0.42. "
+                "Instead, please use a full matrix as input, or try qml.ctrl for controlled QubitUnitary.",
+                qml.PennyLaneDeprecationWarning,
             )
-            wires = Wires(())
+            base = base.matrix()
+
+        if control_wires == "unset":
+
+            return cls._primitive.bind(
+                base, wires=wires, control_values=control_values, work_wires=work_wires
+            )
+        # Below is the legacy interface, where control_wires provided
+        wires = Wires(() if wires is None else wires)
 
         all_wires = control_wires + wires
         return cls._primitive.bind(
@@ -150,35 +168,58 @@ def _primitive_bind_call(
     def __init__(
         self,
         base,
-        control_wires: WiresLike,
-        wires: WiresLike = (),
+        control_wires: WiresLike = "unset",
+        wires: WiresLike = None,
         control_values=None,
         unitary_check=False,
         work_wires: WiresLike = (),
     ):
-        wires = Wires(() if wires is None else wires)
+        _deprecate_control_wires(control_wires)
         work_wires = Wires(() if work_wires is None else work_wires)
-        control_wires = Wires(control_wires)
 
-        if hasattr(base, "wires") and len(wires) != 0:
+        if hasattr(base, "wires"):
             warnings.warn(
-                "base operator already has wires; values specified through wires kwarg will be ignored."
+                "QubitUnitary input to ControlledQubitUnitary is deprecated and will be removed in v0.42. "
+                "Instead, please use a full matrix as input.",
+                qml.PennyLaneDeprecationWarning,
             )
-            wires = Wires(())
-
-        if isinstance(base, Iterable):
-            if len(wires) == 0:
-                if len(control_wires) > 1:
-                    num_base_wires = int(qml.math.log2(qml.math.shape(base)[-1]))
-                    wires = control_wires[-num_base_wires:]
-                    control_wires = control_wires[:-num_base_wires]
-                else:
-                    raise TypeError(
-                        "Must specify a set of wires. None is not a valid `wires` label."
-                    )
-            # We use type.__call__ instead of calling the class directly so that we don't bind the
-            # operator primitive when new program capture is enabled
-            base = type.__call__(qml.QubitUnitary, base, wires=wires, unitary_check=unitary_check)
+            base = base.matrix()
+
+        if control_wires == "unset":
+            if not wires:
+                raise TypeError("Must specify a set of wires. None is not a valid `wires` label.")
+            control_wires = wires[:-1]  # default
+
+            if isinstance(base, Iterable):
+                num_base_wires = int(qml.math.log2(qml.math.shape(base)[-1]))
+                target_wires = wires[-num_base_wires:]
+                control_wires = wires[:-num_base_wires]
+                # We use type.__call__ instead of calling the class directly so that we don't bind the
+                # operator primitive when new program capture is enabled
+                base = type.__call__(
+                    qml.QubitUnitary, base, wires=target_wires, unitary_check=unitary_check
+                )
+            else:
+                raise ValueError("Base must be a matrix.")
+        else:
+            # Below is the legacy interface, where control_wires provided
+            wires = Wires(() if wires is None else wires)
+            control_wires = Wires(control_wires)
+            if isinstance(base, Iterable):
+                if len(wires) == 0:
+                    if len(control_wires) > 1:
+                        num_base_wires = int(qml.math.log2(qml.math.shape(base)[-1]))
+                        wires = control_wires[-num_base_wires:]
+                        control_wires = control_wires[:-num_base_wires]
+                    else:
+                        raise TypeError(
+                            "Must specify a set of wires. None is not a valid `wires` label."
+                        )
+                # We use type.__call__ instead of calling the class directly so that we don't bind the
+                # operator primitive when new program capture is enabled
+                base = type.__call__(
+                    qml.QubitUnitary, base, wires=wires, unitary_check=unitary_check
+                )
 
         super().__init__(
             base,
@@ -191,9 +232,13 @@ def __init__(
     def _controlled(self, wire):
         ctrl_wires = wire + self.control_wires
         values = None if self.control_values is None else [True] + self.control_values
+        base = self.base
+        if isinstance(self.base, qml.QubitUnitary):
+            base = self.base.matrix()
+
         return ControlledQubitUnitary(
-            self.base,
-            control_wires=ctrl_wires,
+            base,
+            wires=ctrl_wires + self.wires,
             control_values=values,
             work_wires=self.work_wires,
         )

pennylane/ops/qubit/matrix_ops.py

@@ -249,7 +249,7 @@ def pow(self, z: Union[int, float]):
         return [QubitUnitary(pow_mat, wires=self.wires)]
 
     def _controlled(self, wire):
-        return qml.ControlledQubitUnitary(*self.parameters, control_wires=wire, wires=self.wires)
+        return qml.ControlledQubitUnitary(*self.parameters, wires=wire + self.wires)
 
     def label(
         self,

tests/devices/default_tensor/test_default_tensor.py

@@ -65,7 +65,7 @@
     "CPhaseShift10": qml.CPhaseShift10(1.234, wires=[0, 1]),
     "QubitUnitary": qml.QubitUnitary(np.eye(2), wires=[0]),
     "SpecialUnitary": qml.SpecialUnitary(np.array([0.2, -0.1, 2.3]), wires=1),
-    "ControlledQubitUnitary": qml.ControlledQubitUnitary(np.eye(2), control_wires=[1], wires=[0]),
+    "ControlledQubitUnitary": qml.ControlledQubitUnitary(np.eye(2), wires=[1, 0]),
     "MultiControlledX": qml.MultiControlledX(wires=[1, 2, 0]),
     "IntegerComparator": qml.IntegerComparator(1, geq=True, wires=[0, 1, 2]),
     "RX": qml.RX(1.234, wires=[0]),

tests/ops/functions/conftest.py

@@ -40,7 +40,7 @@ def _trotterize_qfunc_dummy(time, theta, phi, wires, flip=False):
     (qml.sum(qml.X(0), qml.X(0), qml.Z(0), qml.Z(0)), {}),
     (qml.BasisState([1], wires=[0]), {"skip_differentiation": True}),
     (
-        qml.ControlledQubitUnitary(np.eye(2), control_wires=1, wires=0),
+        qml.ControlledQubitUnitary(np.eye(2), wires=[1, 0]),
         {"skip_differentiation": True},
     ),
     (

tests/ops/functions/test_bind_new_parameters.py

@@ -156,11 +156,15 @@ def test_scalar_symbolic_ops(op, new_params, expected_op):
             [-0.5, 0.456],
             qml.ctrl(qml.s_prod(-0.5, qml.RX(0.456, 0)), [1]),
         ),
-        (qml.ControlledQubitUnitary(X, [1], [0]), [Y], qml.ControlledQubitUnitary(Y, [1], [0])),
         (
-            qml.ControlledQubitUnitary(qml.QubitUnitary(X, 0), [1]),
+            qml.ControlledQubitUnitary(X, wires=[1, 0]),
             [Y],
-            qml.ControlledQubitUnitary(qml.QubitUnitary(Y, 0), [1]),
+            qml.ControlledQubitUnitary(Y, wires=[1, 0]),
+        ),
+        (
+            qml.ControlledQubitUnitary(qml.QubitUnitary(X, 0).matrix(), wires=[1, 0]),
+            [Y],
+            qml.ControlledQubitUnitary(qml.QubitUnitary(Y, 0).matrix(), wires=[1, 0]),
         ),
     ],
 )