Deprecate WiresEnum, AllWires, and AnyWires (#7313)

PR #7312 just does the
num_wires = None part of this change and will allow us to update
catalyst before merging this PR.

Context:

AllWires and AnyWires are overkill that don't really need to exist.
Setting Operator.num_wires = None can sufficiently communicate "I can
accept any number of wires". We haven't validated AllWires or done
anything special about it for many releases. All these serve to do it
tell the default Operator.__init__ to not validate how many wires the
user passes in. We can do that with None.

All they really do is make the interface more complicated and cluttered.

Description of the Change:

Deprecate AllWires, AnyWires, and WiresEnum.

Benefits:

Cleaner Operator interface.

Possible Drawbacks:

Deprecations and removals always run the risk of breaking something for
someone, but I think this a harmless enough change.

Related GitHub Issues:

[[sc-89159](https://app.shortcut.com/xanaduai/story/89159)]

---------

Co-authored-by: Yushao Chen (Jerry) <[email protected]>

Author: albi3ro

doc/development/deprecations.rst

@@ -9,6 +9,13 @@ deprecations are listed below.
 Pending deprecations
 --------------------
 
+* ``qml.operation.WiresEnum``, ``qml.operation.AllWires``, and ``qml.operation.AnyWires`` are deprecated. If an operation can act
+  on any number of wires ``Operator.num_wires = None`` should be used instead. This is the default, and does not need
+  to be overridden unless the operator developer wants to validate that the correct number of wires is passed.
+
+  - Deprecated in v0.42
+  - Will be removed in v0.43
+
 * The :func:`qml.QNode.get_gradient_fn` method is now deprecated. Instead, use :func:`~.workflow.get_best_diff_method` to obtain the differentiation method.
 
   - Deprecated in v0.42

doc/releases/changelog-dev.md

@@ -201,6 +201,11 @@
 
 <h3>Deprecations 👋</h3>
 
+* `qml.operation.WiresEnum`, `qml.operation.AllWires`, and `qml.operation.AnyWires` are deprecated. To indicate that
+  an operator can act on any number of wires, `Operator.num_wires = None` should be used instead. This is the default
+  and does not need to be overwritten unless the operator developer wants to add wire number validation.
+  [(#7313)](https://github.com/PennyLaneAI/pennylane/pull/7313)
+
 * The :func:`qml.QNode.get_gradient_fn` method is now deprecated. Instead, use :func:`~.workflow.get_best_diff_method` to obtain the differentiation method.
   [(#7323)](https://github.com/PennyLaneAI/pennylane/pull/7323)
 

pennylane/operation.py

@@ -232,6 +232,7 @@
 
 import pennylane as qml
 from pennylane.capture import ABCCaptureMeta, create_operator_primitive
+from pennylane.exceptions import PennyLaneDeprecationWarning
 from pennylane.math import expand_matrix
 from pennylane.queuing import QueuingManager
 from pennylane.typing import TensorLike
@@ -299,27 +300,38 @@ class ParameterFrequenciesUndefinedError(OperatorPropertyUndefined):
 # =============================================================================
 
 
-class WiresEnum(IntEnum):
+class _WiresEnum(IntEnum):
     """Integer enumeration class
     to represent the number of wires
     an operation acts on.
 
+    .. warning::
+
+        This class is deprecated ``Operator.num_wires=None`` should now be used to indicate
+        that an operator can exist on any number of wires.
+
     """
 
     AnyWires = -1
     """A enumeration that represents that an operator can act on any number of wires.
 
+    .. warning::
+
+        ``AnyWires`` is deprecated ``Operator.num_wires=None`` should now be used to indicate
+        that an operator can exist on any number of wires.
+
     """
 
     AllWires = -2
     """A enumeration that represents that an operator acts on all wires in the system.
 
+    .. warning::
 
-    """
+        ``AllWires`` is deprecated ``Operator.num_wires=None`` should now be used to indicate
+        that an operator can exist on any number of wires.
 
+    """
 
-AnyWires = WiresEnum.AnyWires
-AllWires = WiresEnum.AllWires
 
 # =============================================================================
 # Class property
@@ -971,7 +983,7 @@ def terms(self) -> tuple[list[TensorLike], list["Operation"]]:  # pylint: disabl
         """
         raise TermsUndefinedError
 
-    num_wires: Optional[Union[int, WiresEnum]] = None
+    num_wires: Optional[Union[int, _WiresEnum]] = None
     """Number of wires the operator acts on."""
 
     @property
@@ -1135,7 +1147,7 @@ def __init__(
         self._wires: Wires = Wires(wires)
 
         # check that the number of wires given corresponds to required number
-        if (self.num_wires is not None and not isinstance(self.num_wires, WiresEnum)) and len(
+        if (self.num_wires is not None and not isinstance(self.num_wires, _WiresEnum)) and len(
             self._wires
         ) != self.num_wires:
             raise ValueError(
@@ -2475,6 +2487,27 @@ def gen_is_multi_term_hamiltonian(obj):
 
 def __getattr__(name):
     """To facilitate StatePrep rename"""
+    if name == "AnyWires":
+        warnings.warn(
+            "AnyWires is deprecated and will be removed in v0.43. "
+            " If your operation accepts any number of wires, set num_wires=None instead.",
+            PennyLaneDeprecationWarning,
+        )
+        return _WiresEnum.AllWires
+    if name == "AllWires":
+        warnings.warn(
+            "AllWires is deprecated and will be removed in v0.43. "
+            " If your operation accepts any number of wires, set num_wires=None instead.",
+            PennyLaneDeprecationWarning,
+        )
+        return _WiresEnum.AllWires
+    if name == "WiresEnum":
+        warnings.warn(
+            "WiresEnum is deprecated and will be removed in v0.43. "
+            " If your operation accepts any number of wires, set num_wires=None instead.",
+            PennyLaneDeprecationWarning,
+        )
+        return _WiresEnum
     if name == "StatePrep":
         return StatePrepBase
     raise AttributeError(f"module 'pennylane.operation' has no attribute '{name}'")

pennylane/templates/subroutines/select_pauli_rot.py

@@ -16,7 +16,7 @@
 """
 
 import pennylane as qml
-from pennylane.operation import AnyWires, Operation
+from pennylane.operation import Operation
 from pennylane.templates.state_preparations.mottonen import _apply_uniform_rotation_dagger
 
 
@@ -79,7 +79,6 @@ def circuit():
          0.        +0.j 0.        +0.j 0.        +0.j 0.        +0.j]
     """
 
-    num_wires = AnyWires
     grad_method = None
     ndim_params = (1,)
 

tests/test_operation.py

@@ -41,6 +41,19 @@
 I_broadcasted = I[pnp.newaxis]
 
 
+def test_wires_enum_deprecation():
+    """Test that WiresEnum, AllWires, and AnyWires are deprecated."""
+
+    with pytest.warns(qml.PennyLaneDeprecationWarning, match="is deprecated"):
+        _ = qml.operation.WiresEnum
+
+    with pytest.warns(qml.PennyLaneDeprecationWarning, match="is deprecated"):
+        _ = qml.operation.AllWires
+
+    with pytest.warns(qml.PennyLaneDeprecationWarning, match="is deprecated"):
+        _ = qml.operation.AnyWires
+
+
 class TestOperatorConstruction:
     """Test custom operators' construction."""