Repository: PennyLaneAI/pennylane

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.

Discussion:
codecov[bot]: # [Codecov](https://codecov.io/gh/PennyLaneAI/pennylane/pull/1325?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PennyLaneAI) Report
> Merging [#1325](https://codecov.io/gh/PennyLaneAI/pennylane/pull/1325?src=pr&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PennyLaneAI) (6219b51) into [master](https://codecov.io/gh/PennyLaneAI/pennylane/commit/b715b35f8424f2207d38f75d38a71afc6669a7fd?el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PennyLaneAI) (b715b35) will **increase** coverage by `0.00%`.
> The diff coverage is `100.00%`.

[![Impacted file tree graph](https://codecov.io/gh/PennyLaneAI/pennylane/pull/1325/graphs/tree.svg?width=650&height=150&src=pr&token=9S3YzlUgGk&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PennyLaneAI)](https://codecov.io/gh/PennyLaneAI/pennylane/pull/1325?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PennyLaneAI)

```diff
@@           Coverage Diff           @@
##           master    #1325   +/-   ##
=======================================
  Coverage   98.16%   98.16%           
=======================================
  Files         148      148           
  Lines       11446    11448    +2     
=======================================
+ Hits        11236    11238    +2     
  Misses        210      210           
```


| [Impacted Files](https://codecov.io/gh/PennyLaneAI/pennylane/pull/1325?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PennyLaneAI) | Coverage Δ | |
|---|---|---|
| [pennylane/utils.py](https://codecov.io/gh/PennyLaneAI/pennylane/pull/1325/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PennyLaneAI#diff-cGVubnlsYW5lL3V0aWxzLnB5) | `96.00% <100.00%> (+0.05%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/PennyLaneAI/pennylane/pull/1325?src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PennyLaneAI).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PennyLaneAI)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/PennyLaneAI/pennylane/pull/1325?src=pr&el=footer&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PennyLaneAI). Last update [b715b35...6219b51](https://codecov.io/gh/PennyLaneAI/pennylane/pull/1325?src=pr&el=lastupdated&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PennyLaneAI). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PennyLaneAI).

tgag17: Thanks for the review @josh146! I have made the required commits

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]))