Repository: PennyLaneAI/pennylane (python)

Issue:
[unitaryhack] Deprecate `qml.inv`
*This issue has been tagged for contributions during [unitaryHACK](https://unitaryfund.github.io/unitaryhack/participating-projects.html)*

Currently, PennyLane has two functions for inverting quantum operations:

* [`qml.inv()`](https://github.com/PennyLaneAI/pennylane/blob/4ece39acb42dacafd5b5cc566c4d3f0512dfa6fb/pennylane/utils.py#L236) accepts a list of operations, unqueues them from the tape, inverts them, and re-queues.

* [`qml.adjoint()`](https://github.com/PennyLaneAI/pennylane/blob/master/pennylane/transforms/adjoint.py) transforms a function that queues operations to one that queues the inverse.

While both have very different internal implementations, for end users, they provide pretty much the same functionality; `qml.adjoint()`, however, is more general and `qml.inv()` has been marked for removal.

Further, the term `adjoint` is already in use for the adjoint differentiation method, and could be confusing to have two independent concepts share the same term.

So we can kill two birds with one stone:

- Remove `qml.inv()`
- Rename the `qml.adjoint()` transform to `qml.inv()`.

This has the advantage that existing users code that uses `qml.inv()` should continue to work as is.

Pull request description:
[unitaryHACK] Deprecated qml.inv()
**Context:**
Deprecated qml.inv(). 

**Description of the Change:**
Added warnings in the documentation and code

**Benefits:**
Want to shift users to qml.adjoint() as it is a more general function

**Related GitHub Issues:**
Fixes #1195 

Patch:
diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md
index 912f61439..b15e59151 100644
--- a/.github/CHANGELOG.md
+++ b/.github/CHANGELOG.md
@@ -159,6 +159,9 @@ random_mat2 = rng.standard_normal(3, requires_grad=False)
 
 <h3>Improvements</h3>
 
+* The `qml.inv()` function is now deprecated with a warning to use the more general `qml.adjoint()`.
+  [(#1325)](https://github.com/PennyLaneAI/pennylane/pull/1325)
+
 * The `MultiControlledX` gate now has a decomposition defined. When controlling on three or more wires,
   an ancilla register of worker wires is required to support the decomposition.
   [(#1287)](https://github.com/PennyLaneAI/pennylane/pull/1287)
@@ -252,7 +255,7 @@ random_mat2 = rng.standard_normal(3, requires_grad=False)
 
 This release contains contributions from (in alphabetical order):
 
-Vishnu Ajith, Thomas Bromley, Olivia Di Matteo, Diego Guala, Anthony Hayes, Josh Izaac, Brian Shi, Antal Száva, Pavan Jayasinha
+Vishnu Ajith, Thomas Bromley, Olivia Di Matteo, Tanya Garg, Diego Guala, Anthony Hayes, Josh Izaac, Brian Shi, Antal Száva, Pavan Jayasinha
 
 # Release 0.15.1 (current release)
 
diff --git a/pennylane/utils.py b/pennylane/utils.py
index 258b7f6bf..2cbe58ef4 100644
--- a/pennylane/utils.py
+++ b/pennylane/utils.py
@@ -22,6 +22,7 @@ import inspect
 import itertools
 import numbers
 from operator import matmul
+import warnings
 
 import numpy as np
 
@@ -239,6 +240,10 @@ def inv(operation_list):
     If the inversion happens inside a QNode, the operations are removed and requeued
     in the reversed order for proper inversion.
 
+    .. warning::
+        Use of :func:`~.inv()` is deprecated and should be replaced with
+        :func:`~.adjoint()`.
+
     **Example:**
 
     The following example illuminates the inversion of a template:
@@ -291,6 +296,11 @@ def inv(operation_list):
     Returns:
         List[~.Operation]: The inverted list of operations
     """
+
+    warnings.warn(
+        "Use of qml.inv() is deprecated and should be replaced with qml.adjoint().",
+        UserWarning,
+    )
     if isinstance(operation_list, qml.operation.Operation):
         operation_list = [operation_list]
     elif operation_list is None:


Test patch:
diff --git a/tests/test_utils.py b/tests/test_utils.py
index ab886069f..14344939e 100644
--- a/tests/test_utils.py
+++ b/tests/test_utils.py
@@ -833,3 +833,12 @@ class TestInv:
             ValueError, match="The given operation_list does not only contain Operations"
         ):
             pu.inv(arg)
+
+    def test_warning(self):
+        """Test that the warning is generated."""
+
+        with pytest.warns(
+            UserWarning,
+            match=r"Use of qml\.inv\(\) is deprecated and should be replaced with qml\.adjoint\(\)\.",
+        ):
+            qml.inv(qml.Hadamard(wires=[0]))