matrix.similar_matrices
=======================

.. py:module:: matrix.similar_matrices

.. autoapi-nested-parse::

   Determine whether two square matrices are similar.

   Two square matrices :math:`A` and :math:`B` of the same size are similar if
   there exists an invertible matrix :math:`P` such that :math:`P^{-1} A P = B`.
   This implementation relies on SymPy to compute the Jordan canonical form of
   both matrices.  Two matrices are similar precisely when their Jordan forms are
   equal up to permutation of the Jordan blocks.
   * https://en.wikipedia.org/wiki/Jordan_matrix
   * https://en.wikipedia.org/wiki/Jordan_normal_form

   Examples
   --------
   >>> are_similar_matrices([[3, 1], [0, 3]], [[3, 0], [0, 3]])
   False
   >>> from sympy import Matrix
   >>> matrix_a = [[3, 1], [0, 3]]
   >>> transform = Matrix([[1, 1], [0, 1]])
   >>> matrix_b = (transform.inv() * Matrix(matrix_a) * transform).tolist()
   >>> are_similar_matrices(matrix_a, matrix_b)
   True
   >>> are_similar_matrices(
   ...     [[1, 2, 0], [0, 1, 0], [0, 0, 3]],
   ...     [[1, 0, 0], [0, 1, 0], [0, 0, 3]],
   ... )
   False
   >>> are_similar_matrices([[1, 2], [0, 1]], [[1, 2, 0], [0, 1, 0]])
   Traceback (most recent call last):
       ...
   ValueError: both matrices must be square with the same dimensions



Functions
---------

.. autoapisummary::

   matrix.similar_matrices.are_similar_matrices


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

.. py:function:: are_similar_matrices(matrix_a: MatrixLike, matrix_b: MatrixLike, *, simplify_entries: bool = True) -> bool

   Return ``True`` if ``matrix_a`` and ``matrix_b`` are similar matrices.

   Parameters
   ----------
   matrix_a, matrix_b:
       Square matrices represented as nested sequences (or SymPy matrices).
   simplify_entries:
       If ``True`` (default), the function attempts to simplify each entry so
       that values that are algebraically equal are treated as such. Set this
       to ``False`` to skip simplification when working with symbolic inputs
       that should remain untouched.

   Raises
   ------
   ValueError
       If the matrices are not square or their dimensions do not match.
   TypeError
       If either matrix cannot be interpreted as a numeric matrix.