toqito.matrix_props.commutant
=============================

.. py:module:: toqito.matrix_props.commutant

.. autoapi-nested-parse::

   Module for computing the commutant of a set of matrices.





Module Contents
---------------

.. py:function:: commutant(A)

   Compute an orthonormal basis for the commutant algebra [@PlanetMathCommutant].

   Given a matrix \(A\) or a set of matrices \(\mathcal{A} = \{A_1, A_2, \dots\}\),
   this function determines an orthonormal basis (with respect to the Hilbert-Schmidt inner product)
   for the algebra of matrices that commute with every matrix in \(\mathcal{A}\).

   The commutant of a single matrix \(A \in \mathbb{C}^{n \times n}\) consists of all matrices
   \(X \in \mathbb{C}^{n \times n}\) satisfying:

   \[
       A X = X A.
   \]

   More generally, for a set of matrices \(\mathcal{A} = \{A_1, A_2, \dots\}\), the commutant
   consists of all matrices \(X\) satisfying:

   \[
       A_i X = X A_i \quad \forall A_i \in \mathcal{A}.
   \]

   This condition can be rewritten in vectorized form as:

   \[
       (A_i \otimes I - I \otimes A_i^T) \text{vec}(X) = 0, \quad \forall A_i \in \mathcal{A}.
   \]

   where \(\text{vec}(X)\) denotes the column-wise vectorization of \(X\).
   The null space of this equation provides a basis for the commutant.

   This implementation is based on [@QETLAB_link].

   .. rubric:: Examples

   Consider the following set of matrices:

   \[
       A_1 = \begin{pmatrix}
               1 & 0 \\
               0 & -1
           \end{pmatrix}, \quad
       A_2 = \begin{pmatrix}
               0 & 1 \\
               1 & 0
           \end{pmatrix}
   \]

   The commutant consists of matrices that commute with both \(A_1\) and \(A_2\).

   ```python exec="1" source="above"
   import numpy as np
   from toqito.matrix_props import commutant

   A1 = np.array([[1, 0], [0, -1]])
   A2 = np.array([[0, 1], [1, 0]])

   basis = commutant([A1, A2])

   print(basis)
   ```


   Now, consider a single matrix:

   \[
       A = \begin{pmatrix}
               1 & 1 \\
               0 & 1
           \end{pmatrix}
   \]

   ```python exec="1" source="above"
   import numpy as np
   from toqito.matrix_props import commutant

   A = np.array([[1, 1], [0, 1]])

   basis = commutant(A)

   for i, basis_ in enumerate(basis):
      print(f"basis{ i} :\n{basis_} \n")
   ```

   :param A: A single matrix of the form np.ndarray or a list of square matrices of the same dimension.

   :returns: A list of matrices forming an orthonormal basis for the commutant.