From 6c23c79e6346ba92158859f745d01735cd070e8a Mon Sep 17 00:00:00 2001
From: Alec Edgington <54802828+cqc-alec@users.noreply.github.com>
Date: Tue, 19 Nov 2024 10:18:02 +0000
Subject: [PATCH] Deprecate `GlobalisePhasedX` (#1683)

---
 pytket/binders/passes.cpp         | 13 ++++++++++++-
 pytket/binders/transform.cpp      | 13 ++++++++++++-
 pytket/docs/changelog.rst         |  1 +
 pytket/pytket/_tket/passes.pyi    |  2 ++
 pytket/pytket/_tket/transform.pyi |  2 ++
 5 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/pytket/binders/passes.cpp b/pytket/binders/passes.cpp
index 081937323d..fe3c71a2ca 100644
--- a/pytket/binders/passes.cpp
+++ b/pytket/binders/passes.cpp
@@ -489,7 +489,16 @@ PYBIND11_MODULE(passes, m) {
       "DecomposeMultiQubitsCX", &DecomposeMultiQubitsCX,
       "Converts all multi-qubit gates into CX and single-qubit gates.");
   m.def(
-      "GlobalisePhasedX", &GlobalisePhasedX,
+      "GlobalisePhasedX",
+      [](bool squash) {
+        PyErr_WarnEx(
+            PyExc_DeprecationWarning,
+            "The GlobalisePhasedX pass is unreliable and deprecated. It will "
+            "be removed no earlier that three months after the pytket 1.35 "
+            "release.",
+            1);
+        return GlobalisePhasedX(squash);
+      },
       "Turns all PhasedX and NPhasedX gates into global gates\n\n"
       "Replaces any PhasedX gates with global NPhasedX gates. "
       "By default, this transform will squash all single-qubit gates "
@@ -499,6 +508,8 @@ PYBIND11_MODULE(passes, m) {
       "performance. If squashing is disabled, each non-global PhasedX gate "
       "will be replaced with two global NPhasedX, but any other gates will "
       "be left untouched."
+      "\n\nDEPRECATED: This pass will be removed no earlier than three months "
+      "after the pytket 1.35 release."
       "\n\n:param squash: Whether to squash the circuit in pre-processing "
       "(default: true)."
       "\n\nIf squash=true (default), the `GlobalisePhasedX` transform's "
diff --git a/pytket/binders/transform.cpp b/pytket/binders/transform.cpp
index cfd70bcec3..2aaf153972 100644
--- a/pytket/binders/transform.cpp
+++ b/pytket/binders/transform.cpp
@@ -386,7 +386,16 @@ PYBIND11_MODULE(transform, m) {
           "DecomposeNPhasedX", &Transforms::decompose_NPhasedX,
           "Decompose NPhasedX gates into single-qubit PhasedX gates.")
       .def_static(
-          "GlobalisePhasedX", &Transforms::globalise_PhasedX,
+          "GlobalisePhasedX",
+          [](bool squash) {
+            PyErr_WarnEx(
+                PyExc_DeprecationWarning,
+                "The GlobalisePhasedX transform is unreliable and deprecated. "
+                "It will be removed no earlier than three months after the "
+                "pytket 1.35 release.",
+                1);
+            return Transforms::globalise_PhasedX(squash);
+          },
           "Turns all PhasedX and NPhasedX gates into global gates\n\n"
           "Replaces any PhasedX gates with global NPhasedX gates. "
           "By default, this transform will squash all single-qubit gates "
@@ -396,6 +405,8 @@ PYBIND11_MODULE(transform, m) {
           "performance. If squashing is disabled, each non-global PhasedX gate "
           "will be replaced with two global NPhasedX, but any other gates will "
           "be left untouched."
+          "\n\nDEPRECATED: This transform will be removed no earlier than "
+          "three months after the pytket 1.35 release."
           "\n\n:param squash: Whether to squash the circuit in pre-processing "
           "(default: true)."
           "\n\nIf squash=true (default), the `GlobalisePhasedX` transform's "
diff --git a/pytket/docs/changelog.rst b/pytket/docs/changelog.rst
index 1e78fcedc6..0c5e383cf0 100644
--- a/pytket/docs/changelog.rst
+++ b/pytket/docs/changelog.rst
@@ -24,6 +24,7 @@ Features:
 Deprecations:
 
 * Deprecate `ClassicalExpBox` and related methods, in favour of `ClExprOp`.
+* Deprecate `GlobalisePhasedX` pass and transform.
 
 Fixes:
 
diff --git a/pytket/pytket/_tket/passes.pyi b/pytket/pytket/_tket/passes.pyi
index e9fd51a094..2e19b05c54 100644
--- a/pytket/pytket/_tket/passes.pyi
+++ b/pytket/pytket/_tket/passes.pyi
@@ -439,6 +439,8 @@ def GlobalisePhasedX(squash: bool = True) -> BasePass:
     
     Replaces any PhasedX gates with global NPhasedX gates. By default, this transform will squash all single-qubit gates to PhasedX and Rz gates before proceeding further. Existing non-global NPhasedX will not be preserved. This is the recommended setting for best performance. If squashing is disabled, each non-global PhasedX gate will be replaced with two global NPhasedX, but any other gates will be left untouched.
     
+    DEPRECATED: This pass will be removed no earlier than three months after the pytket 1.35 release.
+    
     :param squash: Whether to squash the circuit in pre-processing (default: true).
     
     If squash=true (default), the `GlobalisePhasedX` transform's `apply` method will always return true. For squash=false, `apply()` will return true if the circuit was changed and false otherwise.
diff --git a/pytket/pytket/_tket/transform.pyi b/pytket/pytket/_tket/transform.pyi
index ce620128b2..3648de26da 100644
--- a/pytket/pytket/_tket/transform.pyi
+++ b/pytket/pytket/_tket/transform.pyi
@@ -158,6 +158,8 @@ class Transform:
         
         Replaces any PhasedX gates with global NPhasedX gates. By default, this transform will squash all single-qubit gates to PhasedX and Rz gates before proceeding further. Existing non-global NPhasedX will not be preserved. This is the recommended setting for best performance. If squashing is disabled, each non-global PhasedX gate will be replaced with two global NPhasedX, but any other gates will be left untouched.
         
+        DEPRECATED: This transform will be removed no earlier than three months after the pytket 1.35 release.
+        
         :param squash: Whether to squash the circuit in pre-processing (default: true).
         
         If squash=true (default), the `GlobalisePhasedX` transform's `apply` method will always return true. For squash=false, `apply()` will return true if the circuit was changed and false otherwise.