"""Checks if the matrix is commuting."""

import numpy as np


def is_commuting(mat_1: np.ndarray, mat_2: np.ndarray) -> bool:
    r"""Determine if two linear operators commute with each other :cite:`WikiComm`.

    For any pair of operators :math:`X, Y \in \text{L}(\mathcal{X})`, the
    Lie bracket :math:`\left[X, Y\right] \in \text{L}(\mathcal{X})` is defined
    as

    .. math::
        \left[X, Y\right] = XY - YX.

    It holds that :math:`\left[X,Y\right]=0` if and only if :math:`X` and
    :math:`Y` commute (Section: Lie Brackets And Commutants from :cite:`Watrous_2018_TQI`).

    Examples
    ==========

    Consider the following matrices:

    .. math::
        A = \begin{pmatrix} 0 & 1 \\ 0 & 0 \end{pmatrix},
        \quad \text{and} \quad
        B = \begin{pmatrix} 1 & 0 \\ 0 & 0 \end{pmatrix}.

    It holds that :math:`AB=0`, however

    .. math::
        BA = \begin{pmatrix} 0 & 1 \\ 0 & 0 \end{pmatrix} = A,

    and hence, do not commute.

    .. jupyter-execute::

     import numpy as np
     from toqito.matrix_props import is_commuting

     mat_1 = np.array([[0, 1], [0, 0]])
     mat_2 = np.array([[1, 0], [0, 0]])

     is_commuting(mat_1, mat_2)

    Consider the following pair of matrices:

    .. math::
        A = \begin{pmatrix}
            1 & 0 & 0 \\
            0 & 1 & 0 \\
            1 & 0 & 2
            \end{pmatrix} \quad \text{and} \quad
        B = \begin{pmatrix}
            2 & 4 & 0 \\
            3 & 1 & 0 \\
            -1 & -4 & 1
            \end{pmatrix}.

    It may be verified that :math:`AB = BA = 0`, and therefore :math:`A` and
    :math:`B` commute.

    .. jupyter-execute::

     import numpy as np
     from toqito.matrix_props import is_commuting

     mat_1 = np.array([[1, 0, 0], [0, 1, 0], [1, 0, 2]])
     mat_2 = np.array([[2, 4, 0], [3, 1, 0], [-1, -4, 1]])

     is_commuting(mat_1, mat_2)

    References
    ==========
    .. bibliography::
        :filter: docname in docnames



    :param mat_1: First matrix to check.
    :param mat_2: Second matrix to check.
    :return: Return `True` if :code:`mat_1` commutes with :code:`mat_2` and False otherwise.

    """
    return np.allclose(mat_1 @ mat_2 - mat_2 @ mat_1, 0)
