[New Device Capabilities] Add capabilities to the device API

doc/releases/changelog-dev.md

@@ -3,17 +3,39 @@
 # Release 0.40.0-dev (development release)
 
 <h3>New features since last release</h3>
-
-* A `DeviceCapabilities` data class is defined to contain all capabilities of the device's execution interface (i.e. its implementation of `Device.execute`). A TOML file can be used to define the capabilities of a device, and it can be loaded into a `DeviceCapabilities` object.
-  [(#6407)](https://github.com/PennyLaneAI/pennylane/pull/6407)
 
-  ```pycon
-  >>> from pennylane.devices.capabilities import load_toml_file, parse_toml_document, DeviceCapabilities
-  >>> document = load_toml_file("my_device.toml")
-  >>> capabilities = parse_toml_document(document)
-  >>> isinstance(capabilities, DeviceCapabilities)
-  True
-  ```
+* Developers of plugin devices now have the option of providing a TOML-formatted configuration file
+  to declare the capabilities of the device. See [Device Capabilities](https://docs.pennylane.ai/en/latest/development/plugins.html#device-capabilities) for details.
+  [(#6407)](https://github.com/PennyLaneAI/pennylane/pull/6407)
+  [(#6433)](https://github.com/PennyLaneAI/pennylane/pull/6433)
+
+  * An internal module `pennylane.devices.capabilities` is added that defines a new `DeviceCapabilites`
+    data class, as well as functions that load and parse the TOML-formatted configuration files.
+
+    ```pycon
+      >>> from pennylane.devices.capabilities import DeviceCapabilities
+      >>> capabilities = DeviceCapabilities.from_toml_file("my_device.toml")
+      >>> isinstance(capabilities, DeviceCapabilities)
+      True
+    ```
+
+  * Devices that extends `qml.devices.Device` now has an optional class attribute `capabilities`
+    that is an instance of the `DeviceCapabilities` data class, constructed from the configuration
+    file if it exists. Otherwise, it is set to `None`.
+
+    ```python
+    from pennylane.devices import Device
+
+    class MyDevice(Device):
+
+        config_filepath = "path/to/config.toml"
+
+        ...
+    ```
+    ```pycon
+    >>> isinstance(MyDevice.capabilities, DeviceCapabilities)
+    True
+    ```
 
 <h4>New API for Qubit Mixed</h4>
 
@@ -109,11 +131,11 @@
 
 This release contains contributions from (in alphabetical order):
 
-Shiwen An
+Shiwen An,
 Astral Cai,
 Yushao Chen,
 Pietropaolo Frisoni,
 Austin Huang,
 Christina Lee,
 Andrija Paurevic,
-Justin Pickering
+Justin Pickering,

pennylane/devices/__init__.py

@@ -24,7 +24,6 @@
 .. autosummary::
     :toctree: api
 
-
     default_qubit
     default_gaussian
     default_mixed
@@ -147,6 +146,7 @@ def execute(self, circuits, execution_config = qml.devices.DefaultExecutionConfi
 """
 
 
+from .capabilities import DeviceCapabilities
 from .execution_config import ExecutionConfig, DefaultExecutionConfig, MCMConfig
 from .device_constructor import device, refresh_devices
 from .device_api import Device

pennylane/devices/capabilities.py

@@ -14,7 +14,7 @@
 """
 Defines the DeviceCapabilities class, and tools to load it from a TOML file.
 """
-
+import re
 import sys
 from dataclasses import dataclass, field, replace
 from enum import Enum
@@ -79,6 +79,23 @@ def __and__(self, other: "OperatorProperties") -> "OperatorProperties":
         )
 
 
+def _supports_operator(op_name: str, op_dict: dict[str, OperatorProperties]) -> bool:
+    """Checks if the given operator is supported by name."""
+
+    if op_name in op_dict:
+        return True
+
+    if match := re.match(r"Adjoint\((.*)\)", op_name):
+        base_op_name = match.group(1)
+        return base_op_name in op_dict and op_dict[base_op_name].invertible
+
+    if match := re.match(r"C\((.*)\)", op_name):
+        base_op_name = match.group(1)
+        return base_op_name in op_dict and op_dict[base_op_name].controllable
+
+    return False
+
+
 @dataclass
 class DeviceCapabilities:  # pylint: disable=too-many-instance-attributes
     """Capabilities of a quantum device.
@@ -152,6 +169,14 @@ def from_toml_file(cls, file_path: str, runtime_interface="pennylane") -> "Devic
         update_device_capabilities(capabilities, document, runtime_interface)
         return capabilities
 
+    def supports_operation(self, operation_name: str) -> bool:
+        """Checks if the given operation is supported by name."""
+        return _supports_operator(operation_name, self.operations)
+
+    def supports_observable(self, observable_name: str) -> bool:
+        """Checks if the given observable is supported by name."""
+        return _supports_operator(observable_name, self.observables)
+
 
 VALID_COMPILATION_OPTIONS = {
     "qjit_compatible",
@@ -322,7 +347,7 @@ def _get_compilation_options(document: dict, prefix: str = "") -> dict[str, bool
     return section
 
 
-def _get_options(document: dict) -> dict[str, str]:
+def _get_options(document: dict) -> dict[str, any]:
     """Get custom options"""
     return document.get("options", {})
 
@@ -337,7 +362,7 @@ def parse_toml_document(document: dict) -> DeviceCapabilities:
     """
 
     schema = int(document["schema"])
-    assert schema in ALL_SUPPORTED_SCHEMAS, f"Unsupported capabilities TOML schema {schema}"
+    assert schema in ALL_SUPPORTED_SCHEMAS, f"Unsupported config TOML schema {schema}"
     operations = _get_operations(document)
     observables = _get_observables(document)
     measurement_processes = _get_measurement_processes(document)

pennylane/devices/device_api.py

@@ -16,6 +16,7 @@
 """
 # pylint: disable=comparison-with-callable
 import abc
+import warnings
 from collections.abc import Iterable
 from dataclasses import replace
 from numbers import Number
@@ -29,6 +30,7 @@
 from pennylane.typing import Result, ResultBatch
 from pennylane.wires import Wires
 
+from .capabilities import DeviceCapabilities
 from .execution_config import DefaultExecutionConfig, ExecutionConfig
 
 
@@ -45,7 +47,7 @@ class Device(abc.ABC):
         **Streamlined interface:** Only methods that are required to interact with the rest of PennyLane will be placed in the
         interface. Developers will be able to clearly see what they can change while still having a fully functional device.
 
-        **Reduction of duplicate methods:** Methods that solve similar problems are combined together. Only one place will have
+        **Reduction of duplicate methods:** Methods that solve similar problems are combined. Only one place will have
         to solve each individual problem.
 
         **Support for dynamic execution configurations:** Properties such as shots belong to specific executions.
@@ -121,6 +123,25 @@ class Device(abc.ABC):
 
     """
 
+    config_filepath: Optional[str] = None
+    """A device can use a `toml` file to specify the capabilities of the backend device. If this
+    is provided, the file will be loaded into a :class:`~.DeviceCapabilities` object assigned to
+    the :attr:`capabilities` attribute."""
+
+    capabilities: Optional[DeviceCapabilities] = None
+    """A :class:`~.DeviceCapabilities` object describing the capabilities of the backend device."""
+
+    def __init_subclass__(cls, **kwargs):
+        if cls.config_filepath is not None:
+            # TODO: remove this try-except block once all TOML files are updated to the new schema.
+            try:
+                cls.capabilities = DeviceCapabilities.from_toml_file(cls.config_filepath)
+            except AssertionError as e:
+                if "Unsupported config TOML schema" not in str(e):
+                    raise e  # pragma: no cover
+                warnings.warn(str(e))
+        super().__init_subclass__(**kwargs)
+
     @property
     def name(self) -> str:
         """The name of the device or set of devices.

pennylane/devices/legacy_facade.py

@@ -168,6 +168,7 @@ def __init__(self, device: "qml.devices.LegacyDevice"):
             )
 
         self._device = device
+        self.config_filepath = getattr(self._device, "config_filepath", None)
 
     @property
     def tracker(self):

pennylane/devices/preprocess.py

@@ -21,7 +21,7 @@
 from collections.abc import Callable, Generator, Sequence
 from copy import copy
 from itertools import chain
-from typing import Optional, Union
+from typing import Optional, Type, Union
 
 import pennylane as qml
 from pennylane import Snapshot, transform
@@ -48,7 +48,7 @@ def _operator_decomposition_gen(
     max_expansion: Optional[int] = None,
     current_depth=0,
     name: str = "device",
-    error: Optional[Exception] = None,
+    error: Optional[Type[Exception]] = None,
 ) -> Generator[qml.operation.Operator, None, None]:
     """A generator that yields the next operation that is accepted."""
     if error is None:
@@ -302,7 +302,7 @@ def decompose(
     ] = None,
     max_expansion: Union[int, None] = None,
     name: str = "device",
-    error: Optional[Exception] = None,
+    error: Optional[Type[Exception]] = None,
 ) -> tuple[QuantumScriptBatch, PostprocessingFn]:
     """Decompose operations until the stopping condition is met.
 
@@ -456,7 +456,9 @@ def validate_observables(
         if m.obs is not None:
             if isinstance(m.obs, Tensor):
                 if any(not stopping_condition(o) for o in m.obs.obs):
-                    raise qml.DeviceError(f"Observable {repr(m.obs)} not supported on {name}")
+                    raise qml.DeviceError(  # pragma: no cover
+                        f"Observable {repr(m.obs)} not supported on {name}"  # pragma: no cover
+                    )  # pragma: no cover
             elif not stopping_condition(m.obs):
                 raise qml.DeviceError(f"Observable {repr(m.obs)} not supported on {name}")
 

pennylane/devices/tests/conftest.py

@@ -65,14 +65,27 @@ def _init_state(n):
     return _init_state
 
 
+def get_legacy_capabilities(dev):
+    """Gets the capabilities dictionary of a device."""
+
+    if isinstance(dev, qml.devices.LegacyDeviceFacade):
+        return dev.target_device.capabilities()
+
+    if isinstance(dev, qml.devices.LegacyDevice):
+        return dev.capabilities()
+
+    return {}
+
+
 @pytest.fixture(scope="session")
 def skip_if():
     """Fixture to skip tests."""
 
     def _skip_if(dev, capabilities):
         """Skip test if device has any of the given capabilities."""
 
-        dev_capabilities = dev.capabilities()
+        dev_capabilities = get_legacy_capabilities(dev)
+
         for capability, value in capabilities.items():
             # skip if capability not found, or if capability has specific value
             if capability not in dev_capabilities or dev_capabilities[capability] == value:

pennylane/devices/tests/test_compare_default_qubit.py

@@ -22,6 +22,8 @@
 from pennylane import numpy as pnp  # Import from PennyLane to mirror the standard approach in demos
 from pennylane.templates.layers import RandomLayers
 
+from .conftest import get_legacy_capabilities
+
 pytestmark = pytest.mark.skip_unsupported
 
 
@@ -147,9 +149,8 @@ def test_pauliz_expectation_analytic(self, device, tol):
         if dev.name == dev_def.name:
             pytest.skip("Device is default.qubit.")
 
-        supports_tensor = isinstance(dev, qml.devices.Device) or (
-            "supports_tensor_observables" in dev.capabilities()
-            and dev.capabilities()["supports_tensor_observables"]
+        supports_tensor = isinstance(dev, qml.devices.Device) or get_legacy_capabilities(dev).get(
+            "supports_tensor_observables", False
         )
 
         if not supports_tensor:
@@ -186,9 +187,8 @@ def test_random_circuit(self, device, tol, ret):
         if dev.name == dev_def.name:
             pytest.skip("Device is default.qubit.")
 
-        supports_tensor = isinstance(dev, qml.devices.Device) or (
-            "supports_tensor_observables" in dev.capabilities()
-            and dev.capabilities()["supports_tensor_observables"]
+        supports_tensor = isinstance(dev, qml.devices.Device) or get_legacy_capabilities(dev).get(
+            "supports_tensor_observables", False
         )
 
         if not supports_tensor:

pennylane/devices/tests/test_measurements.py

@@ -29,6 +29,8 @@
 )
 from pennylane.wires import Wires
 
+from .conftest import get_legacy_capabilities
+
 pytestmark = pytest.mark.skip_unsupported
 
 # ==========================================================
@@ -140,9 +142,8 @@ def test_tensor_observables_can_be_implemented(self, device_kwargs):
         This test is skipped for devices that do not support tensor observables."""
         device_kwargs["wires"] = 2
         dev = qml.device(**device_kwargs)
-        supports_tensor = isinstance(dev, qml.devices.Device) or (
-            "supports_tensor_observables" in dev.capabilities()
-            and dev.capabilities()["supports_tensor_observables"]
+        supports_tensor = isinstance(dev, qml.devices.Device) or get_legacy_capabilities(dev).get(
+            "supports_tensor_observables", False
         )
         if not supports_tensor:
             pytest.skip("Device does not support tensor observables.")

pennylane/devices/tests/test_properties.py

@@ -18,6 +18,8 @@
 import pennylane as qml
 import pennylane.numpy as pnp
 
+from .conftest import get_legacy_capabilities
+
 try:
     import tensorflow as tf
 
@@ -113,7 +115,7 @@ def test_has_capabilities_dictionary(self, device_kwargs):
         dev = qml.device(**device_kwargs)
         if isinstance(dev, qml.devices.Device):
             pytest.skip("test is old interface specific.")
-        cap = dev.capabilities()
+        cap = get_legacy_capabilities(dev)
         assert isinstance(cap, dict)
 
     def test_model_is_defined_valid_and_correct(self, device_kwargs):
@@ -122,7 +124,7 @@ def test_model_is_defined_valid_and_correct(self, device_kwargs):
         dev = qml.device(**device_kwargs)
         if isinstance(dev, qml.devices.Device):
             pytest.skip("test is old interface specific.")
-        cap = dev.capabilities()
+        cap = get_legacy_capabilities(dev)
         assert "model" in cap
         assert cap["model"] in ["qubit", "cv"]
 
@@ -149,7 +151,7 @@ def test_passthru_interface_is_correct(self, device_kwargs):
         dev = qml.device(**device_kwargs)
         if isinstance(dev, qml.devices.Device):
             pytest.skip("test is old interface specific.")
-        cap = dev.capabilities()
+        cap = get_legacy_capabilities(dev)
 
         if "passthru_interface" not in cap:
             pytest.skip("No passthru_interface capability specified by device.")
@@ -200,7 +202,7 @@ def test_supports_tensor_observables(self, device_kwargs):
         dev = qml.device(**device_kwargs)
         if isinstance(dev, qml.devices.Device):
             pytest.skip("test is old interface specific.")
-        cap = dev.capabilities()
+        cap = get_legacy_capabilities(dev)
 
         if "supports_tensor_observables" not in cap:
             pytest.skip("No supports_tensor_observables capability specified by device.")
@@ -226,7 +228,7 @@ def test_returns_state(self, device_kwargs):
         dev = qml.device(**device_kwargs)
         if isinstance(dev, qml.devices.Device):
             pytest.skip("test is old interface specific.")
-        cap = dev.capabilities()
+        cap = get_legacy_capabilities(dev)
 
         @qml.qnode(dev)
         def circuit():
@@ -263,7 +265,7 @@ def test_returns_probs(self, device_kwargs):
         dev = qml.device(**device_kwargs)
         if isinstance(dev, qml.devices.Device):
             pytest.skip("test is old interface specific.")
-        cap = dev.capabilities()
+        cap = get_legacy_capabilities(dev)
 
         if "returns_probs" not in cap:
             pytest.skip("No returns_probs capability specified by device.")
@@ -290,7 +292,7 @@ def test_supports_broadcasting(self, device_kwargs, mocker):
         dev = qml.device(**device_kwargs)
         if isinstance(dev, qml.devices.Device):
             pytest.skip("test is old interface specific.")
-        cap = dev.capabilities()
+        cap = get_legacy_capabilities(dev)
 
         assert "supports_broadcasting" in cap