Deprecate MPS backend

README.md

@@ -187,9 +187,9 @@ See [examples/models/llama](examples/models/llama/README.md) for complete workfl
 | **Platform**     | **Supported Backends**                                   |
 |------------------|----------------------------------------------------------|
 | Android          | XNNPACK, Vulkan, Qualcomm, MediaTek, Samsung Exynos      |
-| iOS              | XNNPACK, MPS, CoreML (Neural Engine)                     |
+| iOS              | XNNPACK, CoreML (Neural Engine), MPS *(deprecated)*      |
 | Linux / Windows  | XNNPACK, OpenVINO, CUDA *(experimental)*                 |
-| macOS            | XNNPACK, MPS, Metal *(experimental)*                     |
+| macOS            | XNNPACK, Metal *(experimental)*, MPS *(deprecated)*      |
 | Embedded / MCU   | XNNPACK, ARM Ethos-U, NXP, Cadence DSP                   |
 
 See [Backend Documentation](https://docs.pytorch.org/executorch/main/backends-overview.html) for detailed hardware requirements and optimization guides. For desktop/laptop GPU inference with CUDA and Metal, see the [Desktop Guide](desktop/README.md). For Zephyr RTOS integration, see the [Zephyr Guide](zephyr/README.md).

backends/apple/mps/CMakeLists.txt

@@ -5,6 +5,11 @@
 
 cmake_minimum_required(VERSION 3.19)
 
+message(
+  WARNING "[DEPRECATED] The MPS backend is deprecated and will be removed in "
+          "ExecuTorch 1.4. Please migrate to CoreML or the Metal backend."
+)
+
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
 if(NOT CMAKE_CXX_STANDARD)

backends/apple/mps/__init__.py

@@ -3,6 +3,15 @@
 #  Provided subject to the LICENSE file in the top level directory.
 #
 
+import warnings
+
+warnings.warn(
+    "The executorch.backends.apple.mps package is deprecated and will be "
+    "removed in ExecuTorch 1.4. Use executorch.backends.apple.coreml instead.",
+    FutureWarning,
+    stacklevel=2,
+)
+
 from .mps_preprocess import MPSBackend
 
 __all__ = [

backends/apple/mps/mps_preprocess.py

@@ -3,6 +3,17 @@
 #  Provided subject to the LICENSE file in the top level directory.
 #
 import logging
+import warnings
+
+warnings.warn(
+    "The MPS backend is deprecated and will be removed in ExecuTorch 1.4. "
+    "Use the CoreML backend for iOS/macOS GPU acceleration, or the Metal "
+    "backend for macOS desktop GPU workloads. "
+    "See https://docs.pytorch.org/executorch/main/backends-overview.html "
+    "for migration guidance.",
+    FutureWarning,
+    stacklevel=2,
+)
 from typing import ClassVar, Dict, final, List, Tuple
 
 import torch
@@ -27,6 +38,7 @@
     convert_to_flatbuffer,
 )
 from executorch.exir._serialize._program import Cord
+from executorch.exir._warnings import deprecated
 
 from executorch.exir.backend.backend_details import (
     BackendDetails,
@@ -43,8 +55,24 @@
 logging.basicConfig(level=logging.INFO, format=FORMAT)
 
 
+@deprecated(
+    "The MPS backend is deprecated and will be removed in ExecuTorch 1.4. "
+    "Use the CoreML backend for iOS/macOS GPU acceleration, or the Metal "
+    "backend for macOS desktop GPU workloads. "
+    "See https://docs.pytorch.org/executorch/main/backends-overview.html "
+    "for migration guidance.",
+    category=FutureWarning,
+)
 @final
 class MPSBackend(BackendDetails):
+    """MPS backend for Apple GPU acceleration via MPSGraph.
+
+    .. warning::
+
+        ``MPSBackend`` is deprecated and will be removed in ExecuTorch 1.4.
+        Use ``CoreMLBackend`` (iOS/macOS) or the Metal backend (macOS) instead.
+    """
+
     @staticmethod
     def slice_len_max(s):
         assert s.start is not None

backends/apple/mps/partition/__init__.py

@@ -3,6 +3,16 @@
 #  Provided subject to the LICENSE file in the top level directory.
 #
 
+import warnings
+
+warnings.warn(
+    "The executorch.backends.apple.mps.partition package is deprecated and will "
+    "be removed in ExecuTorch 1.4. Use "
+    "executorch.backends.apple.coreml.partition instead.",
+    FutureWarning,
+    stacklevel=2,
+)
+
 from .mps_partitioner import MPSPartitioner
 
 __all__ = [

backends/apple/mps/partition/mps_partitioner.py

@@ -4,12 +4,23 @@
 #
 
 import logging
+import warnings
+
+warnings.warn(
+    "The MPS partitioner is deprecated and will be removed in ExecuTorch 1.4. "
+    "Use CoreMLPartitioner for iOS/macOS GPU acceleration instead. "
+    "See https://docs.pytorch.org/executorch/main/backends-overview.html "
+    "for migration guidance.",
+    FutureWarning,
+    stacklevel=2,
+)
 from typing import Any, cast, Dict, List, Union
 
 import torch
 from executorch.backends.apple.mps import MPSBackend
 from executorch.backends.apple.mps.operators.node_visitor import get_node_visitors
 from executorch.backends.transforms import get_shape
+from executorch.exir._warnings import deprecated
 from executorch.exir.backend.backend_details import CompileSpec
 from executorch.exir.backend.canonical_partitioners.pattern_op_partitioner import (
     generate_partitions_from_list_of_nodes,
@@ -51,7 +62,22 @@ def is_node_supported(self, submodules, node: torch.fx.Node) -> bool:
         return True
 
 
+@deprecated(
+    "The MPS partitioner is deprecated and will be removed in ExecuTorch 1.4. "
+    "Use CoreMLPartitioner for iOS/macOS GPU acceleration instead. "
+    "See https://docs.pytorch.org/executorch/main/backends-overview.html "
+    "for migration guidance.",
+    category=FutureWarning,
+)
 class MPSPartitioner(Partitioner):
+    """Partitioner for the MPS backend.
+
+    .. warning::
+
+        ``MPSPartitioner`` is deprecated and will be removed in ExecuTorch 1.4.
+        Use ``CoreMLPartitioner`` instead.
+    """
+
     def __init__(self, compile_specs: List[CompileSpec]) -> None:
         self.compile_specs = compile_specs
         self.delegation_spec = DelegationSpec(MPSBackend.__name__, compile_specs)

backends/apple/mps/runtime/MPSBackend.mm

@@ -44,6 +44,11 @@ bool is_available() const override {
       BackendInitContext& context,
       FreeableBuffer* processed,
       ArrayRef<CompileSpec> compile_specs) const override {
+    ET_LOG(
+        Info,
+        "The MPS backend is deprecated and will be removed in ExecuTorch 1.4. "
+        "Please migrate to CoreML or the Metal backend.");
+
     auto executor = context.get_runtime_allocator()->allocateInstance<mps::delegate::MPSExecutor>();
     if (executor == nullptr) {
       return Error::MemoryAllocationFailed;

backends/apple/mps/setup.md

@@ -1,5 +1,10 @@
 # Building and Running ExecuTorch with MPS Backend
 
+> **⚠️ Deprecated:** The MPS backend is deprecated as of ExecuTorch 1.2 and will
+> be removed in ExecuTorch 1.4. Please migrate to the
+> [CoreML backend](../coreml/) for iOS/macOS GPU acceleration, or the
+> [Metal backend](../../../desktop/) for macOS desktop GPU workloads.
+
 In this tutorial we will walk you through the process of getting setup to build the MPS backend for ExecuTorch and running a simple model on it.
 
 The MPS backend device maps machine learning computational graphs and primitives on the [MPS Graph](https://developer.apple.com/documentation/metalperformanceshadersgraph/mpsgraph?language=objc) framework and tuned kernels provided by [MPS](https://developer.apple.com/documentation/metalperformanceshaders?language=objc).

backends/apple/mps/test/test_mps_deprecation.py

@@ -0,0 +1,125 @@
+#
+#  Copyright (c) 2023 Apple Inc. All rights reserved.
+#  Provided subject to the LICENSE file in the top level directory.
+#
+
+import sys
+import unittest
+import warnings
+
+
+class TestMPSDeprecation(unittest.TestCase):
+    """Tests that MPS backend deprecation warnings are properly emitted."""
+
+    def setUp(self) -> None:
+        # Clear cached MPS modules so module-level warnings fire again on each test
+        for key in [
+            k for k in sys.modules if k.startswith("executorch.backends.apple.mps")
+        ]:
+            del sys.modules[key]
+
+    def test_mps_package_import_warns(self) -> None:
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            import executorch.backends.apple.mps  # noqa: F401
+
+            future_warnings = [
+                warning
+                for warning in w
+                if issubclass(warning.category, FutureWarning)
+                and "deprecated" in str(warning.message).lower()
+                and "mps" in str(warning.message).lower()
+            ]
+            self.assertTrue(
+                len(future_warnings) > 0,
+                "Importing executorch.backends.apple.mps should emit a FutureWarning",
+            )
+
+    def test_mps_partition_package_import_warns(self) -> None:
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            import executorch.backends.apple.mps.partition  # noqa: F401
+
+            future_warnings = [
+                warning
+                for warning in w
+                if issubclass(warning.category, FutureWarning)
+                and "deprecated" in str(warning.message).lower()
+                and "mps" in str(warning.message).lower()
+            ]
+            self.assertTrue(
+                len(future_warnings) > 0,
+                "Importing executorch.backends.apple.mps.partition should emit a FutureWarning",
+            )
+
+    def test_mps_backend_class_warns(self) -> None:
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            from executorch.backends.apple.mps.mps_preprocess import (  # noqa: F401
+                MPSBackend,
+            )
+
+            future_warnings = [
+                warning
+                for warning in w
+                if issubclass(warning.category, FutureWarning)
+                and "MPS backend is deprecated" in str(warning.message)
+            ]
+            self.assertTrue(
+                len(future_warnings) > 0,
+                "Importing MPSBackend should emit a FutureWarning about deprecation",
+            )
+
+    def test_mps_partitioner_class_warns(self) -> None:
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            from executorch.backends.apple.mps.partition.mps_partitioner import (  # noqa: F401
+                MPSPartitioner,
+            )
+
+            future_warnings = [
+                warning
+                for warning in w
+                if issubclass(warning.category, FutureWarning)
+                and "MPS partitioner is deprecated" in str(warning.message)
+            ]
+            self.assertTrue(
+                len(future_warnings) > 0,
+                "Importing MPSPartitioner should emit a FutureWarning about deprecation",
+            )
+
+    def test_deprecation_message_mentions_alternative(self) -> None:
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            from executorch.backends.apple.mps.mps_preprocess import (  # noqa: F401
+                MPSBackend,
+            )
+
+            future_warnings = [
+                warning for warning in w if issubclass(warning.category, FutureWarning)
+            ]
+            self.assertTrue(len(future_warnings) > 0)
+            message = str(future_warnings[-1].message)
+            self.assertIn(
+                "CoreML",
+                message,
+                "Deprecation warning should mention CoreML as an alternative",
+            )
+
+    def test_deprecation_message_mentions_removal_version(self) -> None:
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            from executorch.backends.apple.mps.mps_preprocess import (  # noqa: F401
+                MPSBackend,
+            )
+
+            future_warnings = [
+                warning for warning in w if issubclass(warning.category, FutureWarning)
+            ]
+            self.assertTrue(len(future_warnings) > 0)
+            message = str(future_warnings[-1].message)
+            self.assertIn(
+                "1.4",
+                message,
+                "Deprecation warning should mention the removal version (1.4)",
+            )

docs/source/backends/mps/mps-overview.md

@@ -1,5 +1,13 @@
 # MPS Backend
 
+:::{warning}
+**Deprecated:** The MPS backend is deprecated as of ExecuTorch 1.2 and will be
+removed in ExecuTorch 1.4. Please migrate to the
+[CoreML backend](../coreml/coreml-overview.md) for iOS/macOS GPU acceleration,
+or the [Metal backend](../../../../desktop/README.md) for macOS desktop GPU
+workloads.
+:::
+
 MPS delegate is the ExecuTorch solution to take advantage of Apple's GPU for on-device ML using the [MPS Graph](https://developer.apple.com/documentation/metalperformanceshadersgraph/mpsgraph?language=objc) framework and tuned kernels provided by [MPS](https://developer.apple.com/documentation/metalperformanceshaders?language=objc).
 
 ## Target Requirements

examples/apple/mps/README.md

@@ -2,6 +2,11 @@ This README gives some examples on backend-specific model workflow.
 
 # MPS Backend
 
+> **⚠️ Deprecated:** The MPS backend is deprecated as of ExecuTorch 1.2 and will
+> be removed in ExecuTorch 1.4. Please migrate to the
+> [CoreML backend](../../../backends/apple/coreml/) for iOS/macOS GPU acceleration,
+> or the [Metal backend](../../../desktop/) for macOS desktop GPU workloads.
+
 [MPS](https://developer.apple.com/documentation/metalperformanceshaders) is a framework of highly optimized compute and graphics shaders, specially tuned to take advantage of the unique hardware characteristics of each GPU family to ensure optimal performance.
 **MPS** backend takes advantage of [MPSGraph](https://developer.apple.com/documentation/metalperformanceshadersgraph/mpsgraph?language=objc) to build, compile, and execute customized multidimensional graphs from the edge dialect ops.
 

examples/apple/mps/scripts/build_mps_executor_runner.sh

@@ -4,6 +4,10 @@
 
 set -e
 
+echo "WARNING: The MPS backend is deprecated and will be removed in ExecuTorch 1.4."
+echo "Please migrate to CoreML or the Metal backend."
+echo ""
+
 MODE="Release"
 OUTPUT="cmake-out"
 

examples/apple/mps/scripts/mps_example.py

@@ -133,6 +133,15 @@ def parse_args():
 
 
 if __name__ == "__main__":  # noqa: C901
+    import warnings
+
+    warnings.warn(
+        "The MPS example script is deprecated and will be removed in "
+        "ExecuTorch 1.4. Please use the CoreML backend examples instead.",
+        FutureWarning,
+        stacklevel=1,
+    )
+
     args = parse_args()
 
     if args.model_name not in MODEL_NAME_TO_MODEL: