Optimize BasisRotation for real-valued inputs and extend theory in docstring (#7765)

**Context:**
`qml.BasisRotation` implements a basis rotation in the space of
orbitals, mapped to quantum circuits.
In general, the decomposition contains `PhaseShift` and
`SingleExcitation` gates.
If the rotation matrix is real-valued, and thus orthogonal, the
decomposition can be simplified to Givens rotations (`SingleExcitation`)
only (for special orthogonal, i.e., determinant $1$), or Givens
rotations and a single `PhaseShift` (determinant $-1$).
In addition, we recently gained some insight in how to understand the
mapping from orbital rotations to qubits.

**Description of the Change:**
Add a branch to the decomposition of `qml.BasisRotation` that is
triggered if the rotation matrix has a real number data type. It uses
zero or one `PhaseShift` operations instead of up to $(N^2+N)/2$ phase
shifts, and the same number of `SingleExcitation` gates as the
complex-valued decomposition.

The second major change is an extension of the theory part of the
docstring of `BasisRotation`, including a Lie algebraic explanation for
the mapping.

**Benefits:**
Cheaper decomposition. More math context in docs.

**Possible Drawbacks:**
More complex decomposition logic.

**Related GitHub Issues:**

[sc-94397]

**To do**
- [x] First docstring pass
- [x] Second docstring pass
- [x] test completion (matrix tests?)
- [x] reduce logic if possible
- [x] changelog

---------

Co-authored-by: Utkarsh <[email protected]>
Co-authored-by: Pablo Antonio Moreno Casares <[email protected]>

Author: 3 people

doc/code/qml_math.rst

@@ -13,8 +13,13 @@ Overview
 Utility functions for decompositions
 ------------------------------------
 
-.. currentmodule:: pennylane.math.decomposition
+.. autosummary::
+    :toctree: api
 
-.. automodapi:: pennylane.math.decomposition
-    :no-heading:
-    :no-inherited-members:
+    ~decomposition.decomp_int_to_powers_of_two
+    ~decomposition.givens_decomposition
+    ~decomposition.su2su2_to_tensor_products
+    ~decomposition.xyx_rotation_angles
+    ~decomposition.xzx_rotation_angles
+    ~decomposition.zxz_rotation_angles
+    ~decomposition.zyz_rotation_angles

doc/releases/changelog-dev.md

@@ -64,6 +64,11 @@
 
 <h3>Improvements 🛠</h3>
 
+* The decomposition of :class:`~.BasisRotation` has been optimized to skip redundant phase shift gates
+  with angle :math:`\pm \pi` for real-valued, i.e., orthogonal, rotation matrices. This uses the fact that
+  no or single :class:`~.PhaseShift` gate is required in case the matrix has a determinant :math:`\pm 1`.
+  [(#7765)](https://github.com/PennyLaneAI/pennylane/pull/7765)
+
 * Changed how basis states are assigned internally in `qml.Superposition`, improving its
   decomposition slightly both regarding classical computing time and gate decomposition.
   [(#7880)](https://github.com/PennyLaneAI/pennylane/pull/7880)
@@ -147,6 +152,12 @@
 
 <h4>Other improvements</h4>
 
+* The matrix factorization using :func:`~.math.decomposition.givens_decomposition` has
+  been optimized to factor out the redundant sign in the diagonal phase matrix for the
+  real-valued (orthogonal) rotation matrices. For example, in case the determinant of a matrix is
+  :math:`-1`, only a single element of the phase matrix is required.
+  [(#7765)](https://github.com/PennyLaneAI/pennylane/pull/7765)
+
 * Added the `NumQubitsOp` operation to the `Quantum` dialect of the Python compiler.
 [(#8063)](https://github.com/PennyLaneAI/pennylane/pull/8063)
 
@@ -169,8 +180,6 @@
           ╚═══╝      
   ```
 
-
-
 * PennyLane is now compatible with `quimb` 1.11.2 after a bug affecting `default.tensor` was fixed.
   [(#7931)](https://github.com/PennyLaneAI/pennylane/pull/7931)
 
@@ -576,6 +585,11 @@
 
 <h3>Documentation 📝</h3>
 
+* The theoretical background section of :class:`~.BasisRotation` has been extended to explain
+  the underlying Lie group/algebra homomorphism between the (dense) rotation matrix and the
+  performed operations on the target qubits.
+  [(#7765)](https://github.com/PennyLaneAI/pennylane/pull/7765)
+
 * Updated the code examples in the documentation of :func:`~.specs`.
   [(#8003)](https://github.com/PennyLaneAI/pennylane/pull/8003)
 

pennylane/math/__init__.py

@@ -142,6 +142,39 @@ def get_dtype_name(x) -> str:
     return ar.get_dtype_name(x)
 
 
+def is_real_obj_or_close(obj):
+    """Convert an array to its real part if it is close to being real-valued, and afterwards
+    return whether the resulting data type is real.
+
+    Args:
+        obj (array): Array to check for being (close to) real.
+
+    Returns:
+        bool: Whether the array ``obj``, after potentially converting it to a real matrix,
+        has a real data type. This is obtained by checking whether the data type name starts with
+        ``"complex"`` and returning the negated result of this.
+
+    >>> x = jnp.array(0.4)
+    >>> qml.math.is_real_obj_or_close(x)
+    True
+
+    >>> x = tf.Variable(0.4+0.2j)
+    >>> qml.math.is_real_obj_or_close(x)
+    False
+
+    >>> x = torch.tensor(0.4+1e-13j)
+    >>> qml.math.is_real_obj_or_close(x)
+    True
+
+    Default absolute and relative tolerances of
+    ``qml.math.allclose`` are used to determine whether the
+    input is close to real-valued.
+    """
+    if not is_abstract(obj) and allclose(ar.imag(obj), 0.0):
+        obj = ar.real(obj)
+    return not get_dtype_name(obj).startswith("complex")
+
+
 class NumpyMimic(ar.autoray.NumpyMimic):
     """Subclass of the Autoray NumpyMimic class in order to support
     the NumPy fft submodule"""
@@ -202,6 +235,7 @@ def __getattr__(name):
     "in_backprop",
     "is_abstract",
     "is_independent",
+    "is_real_obj_or_close",
     "iscomplex",
     "jacobian",
     "kron",