Add files using upload-large-folder tool

.gitattributes

@@ -442,3 +442,5 @@ tuning-competition-baseline/.venv/lib/python3.11/site-packages/nvidia/cudnn/lib/
 .venv/lib/python3.11/site-packages/sympy/simplify/__pycache__/hyperexpand.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
 .venv/lib/python3.11/site-packages/sympy/crypto/__pycache__/crypto.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
 .venv/lib/python3.11/site-packages/sympy/simplify/tests/__pycache__/test_simplify.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/sympy/plotting/__pycache__/series.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/sympy/plotting/tests/__pycache__/test_series.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text

.venv/lib/python3.11/site-packages/sympy/matrices/common.py

@@ -0,0 +1,3263 @@
+"""
+A module contining deprecated matrix mixin classes.
+
+The classes in this module are deprecated and will be removed in a future
+release. They are kept here for backwards compatibility in case downstream
+code was subclassing them.
+
+Importing anything else from this module is deprecated so anything here
+should either not be used or should be imported from somewhere else.
+"""
+
+from collections import defaultdict
+from collections.abc import Iterable
+from inspect import isfunction
+from functools import reduce
+
+from sympy.assumptions.refine import refine
+from sympy.core import SympifyError, Add
+from sympy.core.basic import Atom
+from sympy.core.decorators import call_highest_priority
+from sympy.core.logic import fuzzy_and, FuzzyBool
+from sympy.core.numbers import Integer
+from sympy.core.mod import Mod
+from sympy.core.singleton import S
+from sympy.core.symbol import Symbol
+from sympy.core.sympify import sympify
+from sympy.functions.elementary.complexes import Abs, re, im
+from sympy.utilities.exceptions import sympy_deprecation_warning
+from .utilities import _dotprodsimp, _simplify
+from sympy.polys.polytools import Poly
+from sympy.utilities.iterables import flatten, is_sequence
+from sympy.utilities.misc import as_int, filldedent
+from sympy.tensor.array import NDimArray
+
+from .utilities import _get_intermediate_simp_bool
+
+
+# These exception types were previously defined in this module but were moved
+# to exceptions.py. We reimport them here for backwards compatibility in case
+# downstream code was importing them from here.
+from .exceptions import ( # noqa: F401
+    MatrixError, ShapeError, NonSquareMatrixError, NonInvertibleMatrixError,
+    NonPositiveDefiniteMatrixError
+)
+
+
+_DEPRECATED_MIXINS = (
+    'MatrixShaping',
+    'MatrixSpecial',
+    'MatrixProperties',
+    'MatrixOperations',
+    'MatrixArithmetic',
+    'MatrixCommon',
+    'MatrixDeterminant',
+    'MatrixReductions',
+    'MatrixSubspaces',
+    'MatrixEigen',
+    'MatrixCalculus',
+    'MatrixDeprecated',
+)
+
+
+class _MatrixDeprecatedMeta(type):
+
+    #
+    # Override the default __instancecheck__ implementation to ensure that
+    # e.g. isinstance(M, MatrixCommon) still works when M is one of the
+    # matrix classes. Matrix no longer inherits from MatrixCommon so
+    # isinstance(M, MatrixCommon) would now return False by default.
+    #
+    # There were lots of places in the codebase where this was being done
+    # so it seems likely that downstream code may be doing it too. All use
+    # of these mixins is deprecated though so we give a deprecation warning
+    # unconditionally if they are being used with isinstance.
+    #
+    # Any code seeing this deprecation warning should be changed to use
+    # isinstance(M, MatrixBase) instead which also works in previous versions
+    # of SymPy.
+    #
+
+    def __instancecheck__(cls, instance):
+
+        sympy_deprecation_warning(
+            f"""
+            Checking whether an object is an instance of {cls.__name__} is
+            deprecated.
+
+            Use `isinstance(obj, Matrix)` instead of `isinstance(obj, {cls.__name__})`.
+            """,
+            deprecated_since_version="1.13",
+            active_deprecations_target="deprecated-matrix-mixins",
+            stacklevel=3,
+        )
+
+        from sympy.matrices.matrixbase import MatrixBase
+        from sympy.matrices.matrices import (
+            MatrixDeterminant,
+            MatrixReductions,
+            MatrixSubspaces,
+            MatrixEigen,
+            MatrixCalculus,
+            MatrixDeprecated
+        )
+
+        all_mixins = (
+            MatrixRequired,
+            MatrixShaping,
+            MatrixSpecial,
+            MatrixProperties,
+            MatrixOperations,
+            MatrixArithmetic,
+            MatrixCommon,
+            MatrixDeterminant,
+            MatrixReductions,
+            MatrixSubspaces,
+            MatrixEigen,
+            MatrixCalculus,
+            MatrixDeprecated
+        )
+
+        if cls in all_mixins and isinstance(instance, MatrixBase):
+            return True
+        else:
+            return super().__instancecheck__(instance)
+
+
+class MatrixRequired(metaclass=_MatrixDeprecatedMeta):
+    """Deprecated mixin class for making matrix classes."""
+
+    rows = None  # type: int
+    cols = None  # type: int
+    _simplify = None
+
+    def __init_subclass__(cls, **kwargs):
+
+        # Warn if any downstream code is subclassing this class or any of the
+        # deprecated mixin classes that are all ultimately subclasses of this
+        # class.
+        #
+        # We don't want to warn about the deprecated mixins themselves being
+        # created, but only about them being used as mixins by downstream code.
+        # Otherwise just importing this module would trigger a warning.
+        # Ultimately the whole module should be deprecated and removed but for
+        # SymPy 1.13 it is premature to do that given that this module was the
+        # main way to import matrix exception types in all previous versions.
+
+        if cls.__name__ not in _DEPRECATED_MIXINS:
+            sympy_deprecation_warning(
+                f"""
+                Inheriting from the Matrix mixin classes is deprecated.
+
+                The class {cls.__name__} is subclassing a deprecated mixin.
+                """,
+                deprecated_since_version="1.13",
+                active_deprecations_target="deprecated-matrix-mixins",
+                stacklevel=3,
+            )
+
+        super().__init_subclass__(**kwargs)
+
+    @classmethod
+    def _new(cls, *args, **kwargs):
+        """`_new` must, at minimum, be callable as
+        `_new(rows, cols, mat) where mat is a flat list of the
+        elements of the matrix."""
+        raise NotImplementedError("Subclasses must implement this.")
+
+    def __eq__(self, other):
+        raise NotImplementedError("Subclasses must implement this.")
+
+    def __getitem__(self, key):
+        """Implementations of __getitem__ should accept ints, in which
+        case the matrix is indexed as a flat list, tuples (i,j) in which
+        case the (i,j) entry is returned, slices, or mixed tuples (a,b)
+        where a and b are any combination of slices and integers."""
+        raise NotImplementedError("Subclasses must implement this.")
+
+    def __len__(self):
+        """The total number of entries in the matrix."""
+        raise NotImplementedError("Subclasses must implement this.")
+
+    @property
+    def shape(self):
+        raise NotImplementedError("Subclasses must implement this.")
+
+
+class MatrixShaping(MatrixRequired):
+    """Provides basic matrix shaping and extracting of submatrices"""
+
+    def _eval_col_del(self, col):
+        def entry(i, j):
+            return self[i, j] if j < col else self[i, j + 1]
+        return self._new(self.rows, self.cols - 1, entry)
+
+    def _eval_col_insert(self, pos, other):
+
+        def entry(i, j):
+            if j < pos:
+                return self[i, j]
+            elif pos <= j < pos + other.cols:
+                return other[i, j - pos]
+            return self[i, j - other.cols]
+
+        return self._new(self.rows, self.cols + other.cols, entry)
+
+    def _eval_col_join(self, other):
+        rows = self.rows
+
+        def entry(i, j):
+            if i < rows:
+                return self[i, j]
+            return other[i - rows, j]
+
+        return classof(self, other)._new(self.rows + other.rows, self.cols,
+                                         entry)
+
+    def _eval_extract(self, rowsList, colsList):
+        mat = list(self)
+        cols = self.cols
+        indices = (i * cols + j for i in rowsList for j in colsList)
+        return self._new(len(rowsList), len(colsList),
+                         [mat[i] for i in indices])
+
+    def _eval_get_diag_blocks(self):
+        sub_blocks = []
+
+        def recurse_sub_blocks(M):
+            i = 1
+            while i <= M.shape[0]:
+                if i == 1:
+                    to_the_right = M[0, i:]
+                    to_the_bottom = M[i:, 0]
+                else:
+                    to_the_right = M[:i, i:]
+                    to_the_bottom = M[i:, :i]
+                if any(to_the_right) or any(to_the_bottom):
+                    i += 1
+                    continue
+                else:
+                    sub_blocks.append(M[:i, :i])
+                    if M.shape == M[:i, :i].shape:
+                        return
+                    else:
+                        recurse_sub_blocks(M[i:, i:])
+                        return
+
+        recurse_sub_blocks(self)
+        return sub_blocks
+
+    def _eval_row_del(self, row):
+        def entry(i, j):
+            return self[i, j] if i < row else self[i + 1, j]
+        return self._new(self.rows - 1, self.cols, entry)
+
+    def _eval_row_insert(self, pos, other):
+        entries = list(self)
+        insert_pos = pos * self.cols
+        entries[insert_pos:insert_pos] = list(other)
+        return self._new(self.rows + other.rows, self.cols, entries)
+
+    def _eval_row_join(self, other):
+        cols = self.cols
+
+        def entry(i, j):
+            if j < cols:
+                return self[i, j]
+            return other[i, j - cols]
+
+        return classof(self, other)._new(self.rows, self.cols + other.cols,
+                                         entry)
+
+    def _eval_tolist(self):
+        return [list(self[i,:]) for i in range(self.rows)]
+
+    def _eval_todok(self):
+        dok = {}
+        rows, cols = self.shape
+        for i in range(rows):
+            for j in range(cols):
+                val = self[i, j]
+                if val != self.zero:
+                    dok[i, j] = val
+        return dok
+
+    def _eval_vec(self):
+        rows = self.rows
+
+        def entry(n, _):
+            # we want to read off the columns first
+            j = n // rows
+            i = n - j * rows
+            return self[i, j]
+
+        return self._new(len(self), 1, entry)
+
+    def _eval_vech(self, diagonal):
+        c = self.cols
+        v = []
+        if diagonal:
+            for j in range(c):
+                for i in range(j, c):
+                    v.append(self[i, j])
+        else:
+            for j in range(c):
+                for i in range(j + 1, c):
+                    v.append(self[i, j])
+        return self._new(len(v), 1, v)
+
+    def col_del(self, col):
+        """Delete the specified column."""
+        if col < 0:
+            col += self.cols
+        if not 0 <= col < self.cols:
+            raise IndexError("Column {} is out of range.".format(col))
+        return self._eval_col_del(col)
+
+    def col_insert(self, pos, other):
+        """Insert one or more columns at the given column position.
+
+        Examples
+        ========
+
+        >>> from sympy import zeros, ones
+        >>> M = zeros(3)
+        >>> V = ones(3, 1)
+        >>> M.col_insert(1, V)
+        Matrix([
+        [0, 1, 0, 0],
+        [0, 1, 0, 0],
+        [0, 1, 0, 0]])
+
+        See Also
+        ========
+
+        col
+        row_insert
+        """
+        # Allows you to build a matrix even if it is null matrix
+        if not self:
+            return type(self)(other)
+
+        pos = as_int(pos)
+
+        if pos < 0:
+            pos = self.cols + pos
+        if pos < 0:
+            pos = 0
+        elif pos > self.cols:
+            pos = self.cols
+
+        if self.rows != other.rows:
+            raise ShapeError(
+                "The matrices have incompatible number of rows ({} and {})"
+                .format(self.rows, other.rows))
+
+        return self._eval_col_insert(pos, other)
+
+    def col_join(self, other):
+        """Concatenates two matrices along self's last and other's first row.
+
+        Examples
+        ========
+
+        >>> from sympy import zeros, ones
+        >>> M = zeros(3)
+        >>> V = ones(1, 3)
+        >>> M.col_join(V)
+        Matrix([
+        [0, 0, 0],
+        [0, 0, 0],
+        [0, 0, 0],
+        [1, 1, 1]])
+
+        See Also
+        ========
+
+        col
+        row_join
+        """
+        # A null matrix can always be stacked (see  #10770)
+        if self.rows == 0 and self.cols != other.cols:
+            return self._new(0, other.cols, []).col_join(other)
+
+        if self.cols != other.cols:
+            raise ShapeError(
+                "The matrices have incompatible number of columns ({} and {})"
+                .format(self.cols, other.cols))
+        return self._eval_col_join(other)
+
+    def col(self, j):
+        """Elementary column selector.
+
+        Examples
+        ========
+
+        >>> from sympy import eye
+        >>> eye(2).col(0)
+        Matrix([
+        [1],
+        [0]])
+
+        See Also
+        ========
+
+        row
+        col_del
+        col_join
+        col_insert
+        """
+        return self[:, j]
+
+    def extract(self, rowsList, colsList):
+        r"""Return a submatrix by specifying a list of rows and columns.
+        Negative indices can be given. All indices must be in the range
+        $-n \le i < n$ where $n$ is the number of rows or columns.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> m = Matrix(4, 3, range(12))
+        >>> m
+        Matrix([
+        [0,  1,  2],
+        [3,  4,  5],
+        [6,  7,  8],
+        [9, 10, 11]])
+        >>> m.extract([0, 1, 3], [0, 1])
+        Matrix([
+        [0,  1],
+        [3,  4],
+        [9, 10]])
+
+        Rows or columns can be repeated:
+
+        >>> m.extract([0, 0, 1], [-1])
+        Matrix([
+        [2],
+        [2],
+        [5]])
+
+        Every other row can be taken by using range to provide the indices:
+
+        >>> m.extract(range(0, m.rows, 2), [-1])
+        Matrix([
+        [2],
+        [8]])
+
+        RowsList or colsList can also be a list of booleans, in which case
+        the rows or columns corresponding to the True values will be selected:
+
+        >>> m.extract([0, 1, 2, 3], [True, False, True])
+        Matrix([
+        [0,  2],
+        [3,  5],
+        [6,  8],
+        [9, 11]])
+        """
+
+        if not is_sequence(rowsList) or not is_sequence(colsList):
+            raise TypeError("rowsList and colsList must be iterable")
+        # ensure rowsList and colsList are lists of integers
+        if rowsList and all(isinstance(i, bool) for i in rowsList):
+            rowsList = [index for index, item in enumerate(rowsList) if item]
+        if colsList and all(isinstance(i, bool) for i in colsList):
+            colsList = [index for index, item in enumerate(colsList) if item]
+
+        # ensure everything is in range
+        rowsList = [a2idx(k, self.rows) for k in rowsList]
+        colsList = [a2idx(k, self.cols) for k in colsList]
+
+        return self._eval_extract(rowsList, colsList)
+
+    def get_diag_blocks(self):
+        """Obtains the square sub-matrices on the main diagonal of a square matrix.
+
+        Useful for inverting symbolic matrices or solving systems of
+        linear equations which may be decoupled by having a block diagonal
+        structure.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> from sympy.abc import x, y, z
+        >>> A = Matrix([[1, 3, 0, 0], [y, z*z, 0, 0], [0, 0, x, 0], [0, 0, 0, 0]])
+        >>> a1, a2, a3 = A.get_diag_blocks()
+        >>> a1
+        Matrix([
+        [1,    3],
+        [y, z**2]])
+        >>> a2
+        Matrix([[x]])
+        >>> a3
+        Matrix([[0]])
+
+        """
+        return self._eval_get_diag_blocks()
+
+    @classmethod
+    def hstack(cls, *args):
+        """Return a matrix formed by joining args horizontally (i.e.
+        by repeated application of row_join).
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix, eye
+        >>> Matrix.hstack(eye(2), 2*eye(2))
+        Matrix([
+        [1, 0, 2, 0],
+        [0, 1, 0, 2]])
+        """
+        if len(args) == 0:
+            return cls._new()
+
+        kls = type(args[0])
+        return reduce(kls.row_join, args)
+
+    def reshape(self, rows, cols):
+        """Reshape the matrix. Total number of elements must remain the same.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> m = Matrix(2, 3, lambda i, j: 1)
+        >>> m
+        Matrix([
+        [1, 1, 1],
+        [1, 1, 1]])
+        >>> m.reshape(1, 6)
+        Matrix([[1, 1, 1, 1, 1, 1]])
+        >>> m.reshape(3, 2)
+        Matrix([
+        [1, 1],
+        [1, 1],
+        [1, 1]])
+
+        """
+        if self.rows * self.cols != rows * cols:
+            raise ValueError("Invalid reshape parameters %d %d" % (rows, cols))
+        return self._new(rows, cols, lambda i, j: self[i * cols + j])
+
+    def row_del(self, row):
+        """Delete the specified row."""
+        if row < 0:
+            row += self.rows
+        if not 0 <= row < self.rows:
+            raise IndexError("Row {} is out of range.".format(row))
+
+        return self._eval_row_del(row)
+
+    def row_insert(self, pos, other):
+        """Insert one or more rows at the given row position.
+
+        Examples
+        ========
+
+        >>> from sympy import zeros, ones
+        >>> M = zeros(3)
+        >>> V = ones(1, 3)
+        >>> M.row_insert(1, V)
+        Matrix([
+        [0, 0, 0],
+        [1, 1, 1],
+        [0, 0, 0],
+        [0, 0, 0]])
+
+        See Also
+        ========
+
+        row
+        col_insert
+        """
+        # Allows you to build a matrix even if it is null matrix
+        if not self:
+            return self._new(other)
+
+        pos = as_int(pos)
+
+        if pos < 0:
+            pos = self.rows + pos
+        if pos < 0:
+            pos = 0
+        elif pos > self.rows:
+            pos = self.rows
+
+        if self.cols != other.cols:
+            raise ShapeError(
+                "The matrices have incompatible number of columns ({} and {})"
+                .format(self.cols, other.cols))
+
+        return self._eval_row_insert(pos, other)
+
+    def row_join(self, other):
+        """Concatenates two matrices along self's last and rhs's first column
+
+        Examples
+        ========
+
+        >>> from sympy import zeros, ones
+        >>> M = zeros(3)
+        >>> V = ones(3, 1)
+        >>> M.row_join(V)
+        Matrix([
+        [0, 0, 0, 1],
+        [0, 0, 0, 1],
+        [0, 0, 0, 1]])
+
+        See Also
+        ========
+
+        row
+        col_join
+        """
+        # A null matrix can always be stacked (see  #10770)
+        if self.cols == 0 and self.rows != other.rows:
+            return self._new(other.rows, 0, []).row_join(other)
+
+        if self.rows != other.rows:
+            raise ShapeError(
+                "The matrices have incompatible number of rows ({} and {})"
+                .format(self.rows, other.rows))
+        return self._eval_row_join(other)
+
+    def diagonal(self, k=0):
+        """Returns the kth diagonal of self. The main diagonal
+        corresponds to `k=0`; diagonals above and below correspond to
+        `k > 0` and `k < 0`, respectively. The values of `self[i, j]`
+        for which `j - i = k`, are returned in order of increasing
+        `i + j`, starting with `i + j = |k|`.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> m = Matrix(3, 3, lambda i, j: j - i); m
+        Matrix([
+        [ 0,  1, 2],
+        [-1,  0, 1],
+        [-2, -1, 0]])
+        >>> _.diagonal()
+        Matrix([[0, 0, 0]])
+        >>> m.diagonal(1)
+        Matrix([[1, 1]])
+        >>> m.diagonal(-2)
+        Matrix([[-2]])
+
+        Even though the diagonal is returned as a Matrix, the element
+        retrieval can be done with a single index:
+
+        >>> Matrix.diag(1, 2, 3).diagonal()[1]  # instead of [0, 1]
+        2
+
+        See Also
+        ========
+
+        diag
+        """
+        rv = []
+        k = as_int(k)
+        r = 0 if k > 0 else -k
+        c = 0 if r else k
+        while True:
+            if r == self.rows or c == self.cols:
+                break
+            rv.append(self[r, c])
+            r += 1
+            c += 1
+        if not rv:
+            raise ValueError(filldedent('''
+            The %s diagonal is out of range [%s, %s]''' % (
+            k, 1 - self.rows, self.cols - 1)))
+        return self._new(1, len(rv), rv)
+
+    def row(self, i):
+        """Elementary row selector.
+
+        Examples
+        ========
+
+        >>> from sympy import eye
+        >>> eye(2).row(0)
+        Matrix([[1, 0]])
+
+        See Also
+        ========
+
+        col
+        row_del
+        row_join
+        row_insert
+        """
+        return self[i, :]
+
+    @property
+    def shape(self):
+        """The shape (dimensions) of the matrix as the 2-tuple (rows, cols).
+
+        Examples
+        ========
+
+        >>> from sympy import zeros
+        >>> M = zeros(2, 3)
+        >>> M.shape
+        (2, 3)
+        >>> M.rows
+        2
+        >>> M.cols
+        3
+        """
+        return (self.rows, self.cols)
+
+    def todok(self):
+        """Return the matrix as dictionary of keys.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> M = Matrix.eye(3)
+        >>> M.todok()
+        {(0, 0): 1, (1, 1): 1, (2, 2): 1}
+        """
+        return self._eval_todok()
+
+    def tolist(self):
+        """Return the Matrix as a nested Python list.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix, ones
+        >>> m = Matrix(3, 3, range(9))
+        >>> m
+        Matrix([
+        [0, 1, 2],
+        [3, 4, 5],
+        [6, 7, 8]])
+        >>> m.tolist()
+        [[0, 1, 2], [3, 4, 5], [6, 7, 8]]
+        >>> ones(3, 0).tolist()
+        [[], [], []]
+
+        When there are no rows then it will not be possible to tell how
+        many columns were in the original matrix:
+
+        >>> ones(0, 3).tolist()
+        []
+
+        """
+        if not self.rows:
+            return []
+        if not self.cols:
+            return [[] for i in range(self.rows)]
+        return self._eval_tolist()
+
+    def todod(M):
+        """Returns matrix as dict of dicts containing non-zero elements of the Matrix
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> A = Matrix([[0, 1],[0, 3]])
+        >>> A
+        Matrix([
+        [0, 1],
+        [0, 3]])
+        >>> A.todod()
+        {0: {1: 1}, 1: {1: 3}}
+
+
+        """
+        rowsdict = {}
+        Mlol = M.tolist()
+        for i, Mi in enumerate(Mlol):
+            row = {j: Mij for j, Mij in enumerate(Mi) if Mij}
+            if row:
+                rowsdict[i] = row
+        return rowsdict
+
+    def vec(self):
+        """Return the Matrix converted into a one column matrix by stacking columns
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> m=Matrix([[1, 3], [2, 4]])
+        >>> m
+        Matrix([
+        [1, 3],
+        [2, 4]])
+        >>> m.vec()
+        Matrix([
+        [1],
+        [2],
+        [3],
+        [4]])
+
+        See Also
+        ========
+
+        vech
+        """
+        return self._eval_vec()
+
+    def vech(self, diagonal=True, check_symmetry=True):
+        """Reshapes the matrix into a column vector by stacking the
+        elements in the lower triangle.
+
+        Parameters
+        ==========
+
+        diagonal : bool, optional
+            If ``True``, it includes the diagonal elements.
+
+        check_symmetry : bool, optional
+            If ``True``, it checks whether the matrix is symmetric.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> m=Matrix([[1, 2], [2, 3]])
+        >>> m
+        Matrix([
+        [1, 2],
+        [2, 3]])
+        >>> m.vech()
+        Matrix([
+        [1],
+        [2],
+        [3]])
+        >>> m.vech(diagonal=False)
+        Matrix([[2]])
+
+        Notes
+        =====
+
+        This should work for symmetric matrices and ``vech`` can
+        represent symmetric matrices in vector form with less size than
+        ``vec``.
+
+        See Also
+        ========
+
+        vec
+        """
+        if not self.is_square:
+            raise NonSquareMatrixError
+
+        if check_symmetry and not self.is_symmetric():
+            raise ValueError("The matrix is not symmetric.")
+
+        return self._eval_vech(diagonal)
+
+    @classmethod
+    def vstack(cls, *args):
+        """Return a matrix formed by joining args vertically (i.e.
+        by repeated application of col_join).
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix, eye
+        >>> Matrix.vstack(eye(2), 2*eye(2))
+        Matrix([
+        [1, 0],
+        [0, 1],
+        [2, 0],
+        [0, 2]])
+        """
+        if len(args) == 0:
+            return cls._new()
+
+        kls = type(args[0])
+        return reduce(kls.col_join, args)
+
+
+class MatrixSpecial(MatrixRequired):
+    """Construction of special matrices"""
+
+    @classmethod
+    def _eval_diag(cls, rows, cols, diag_dict):
+        """diag_dict is a defaultdict containing
+        all the entries of the diagonal matrix."""
+        def entry(i, j):
+            return diag_dict[(i, j)]
+        return cls._new(rows, cols, entry)
+
+    @classmethod
+    def _eval_eye(cls, rows, cols):
+        vals = [cls.zero]*(rows*cols)
+        vals[::cols+1] = [cls.one]*min(rows, cols)
+        return cls._new(rows, cols, vals, copy=False)
+
+    @classmethod
+    def _eval_jordan_block(cls, size: int, eigenvalue, band='upper'):
+        if band == 'lower':
+            def entry(i, j):
+                if i == j:
+                    return eigenvalue
+                elif j + 1 == i:
+                    return cls.one
+                return cls.zero
+        else:
+            def entry(i, j):
+                if i == j:
+                    return eigenvalue
+                elif i + 1 == j:
+                    return cls.one
+                return cls.zero
+        return cls._new(size, size, entry)
+
+    @classmethod
+    def _eval_ones(cls, rows, cols):
+        def entry(i, j):
+            return cls.one
+        return cls._new(rows, cols, entry)
+
+    @classmethod
+    def _eval_zeros(cls, rows, cols):
+        return cls._new(rows, cols, [cls.zero]*(rows*cols), copy=False)
+
+    @classmethod
+    def _eval_wilkinson(cls, n):
+        def entry(i, j):
+            return cls.one if i + 1 == j else cls.zero
+
+        D = cls._new(2*n + 1, 2*n + 1, entry)
+
+        wminus = cls.diag(list(range(-n, n + 1)), unpack=True) + D + D.T
+        wplus = abs(cls.diag(list(range(-n, n + 1)), unpack=True)) + D + D.T
+
+        return wminus, wplus
+
+    @classmethod
+    def diag(kls, *args, strict=False, unpack=True, rows=None, cols=None, **kwargs):
+        """Returns a matrix with the specified diagonal.
+        If matrices are passed, a block-diagonal matrix
+        is created (i.e. the "direct sum" of the matrices).
+
+        kwargs
+        ======
+
+        rows : rows of the resulting matrix; computed if
+               not given.
+
+        cols : columns of the resulting matrix; computed if
+               not given.
+
+        cls : class for the resulting matrix
+
+        unpack : bool which, when True (default), unpacks a single
+        sequence rather than interpreting it as a Matrix.
+
+        strict : bool which, when False (default), allows Matrices to
+        have variable-length rows.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> Matrix.diag(1, 2, 3)
+        Matrix([
+        [1, 0, 0],
+        [0, 2, 0],
+        [0, 0, 3]])
+
+        The current default is to unpack a single sequence. If this is
+        not desired, set `unpack=False` and it will be interpreted as
+        a matrix.
+
+        >>> Matrix.diag([1, 2, 3]) == Matrix.diag(1, 2, 3)
+        True
+
+        When more than one element is passed, each is interpreted as
+        something to put on the diagonal. Lists are converted to
+        matrices. Filling of the diagonal always continues from
+        the bottom right hand corner of the previous item: this
+        will create a block-diagonal matrix whether the matrices
+        are square or not.
+
+        >>> col = [1, 2, 3]
+        >>> row = [[4, 5]]
+        >>> Matrix.diag(col, row)
+        Matrix([
+        [1, 0, 0],
+        [2, 0, 0],
+        [3, 0, 0],
+        [0, 4, 5]])
+
+        When `unpack` is False, elements within a list need not all be
+        of the same length. Setting `strict` to True would raise a
+        ValueError for the following:
+
+        >>> Matrix.diag([[1, 2, 3], [4, 5], [6]], unpack=False)
+        Matrix([
+        [1, 2, 3],
+        [4, 5, 0],
+        [6, 0, 0]])
+
+        The type of the returned matrix can be set with the ``cls``
+        keyword.
+
+        >>> from sympy import ImmutableMatrix
+        >>> from sympy.utilities.misc import func_name
+        >>> func_name(Matrix.diag(1, cls=ImmutableMatrix))
+        'ImmutableDenseMatrix'
+
+        A zero dimension matrix can be used to position the start of
+        the filling at the start of an arbitrary row or column:
+
+        >>> from sympy import ones
+        >>> r2 = ones(0, 2)
+        >>> Matrix.diag(r2, 1, 2)
+        Matrix([
+        [0, 0, 1, 0],
+        [0, 0, 0, 2]])
+
+        See Also
+        ========
+        eye
+        diagonal
+        .dense.diag
+        .expressions.blockmatrix.BlockMatrix
+        .sparsetools.banded
+       """
+        from sympy.matrices.matrixbase import MatrixBase
+        from sympy.matrices.dense import Matrix
+        from sympy.matrices import SparseMatrix
+        klass = kwargs.get('cls', kls)
+        if unpack and len(args) == 1 and is_sequence(args[0]) and \
+                not isinstance(args[0], MatrixBase):
+            args = args[0]
+
+        # fill a default dict with the diagonal entries
+        diag_entries = defaultdict(int)
+        rmax = cmax = 0  # keep track of the biggest index seen
+        for m in args:
+            if isinstance(m, list):
+                if strict:
+                    # if malformed, Matrix will raise an error
+                    _ = Matrix(m)
+                    r, c = _.shape
+                    m = _.tolist()
+                else:
+                    r, c, smat = SparseMatrix._handle_creation_inputs(m)
+                    for (i, j), _ in smat.items():
+                        diag_entries[(i + rmax, j + cmax)] = _
+                    m = []  # to skip process below
+            elif hasattr(m, 'shape'):  # a Matrix
+                # convert to list of lists
+                r, c = m.shape
+                m = m.tolist()
+            else:  # in this case, we're a single value
+                diag_entries[(rmax, cmax)] = m
+                rmax += 1
+                cmax += 1
+                continue
+            # process list of lists
+            for i, mi in enumerate(m):
+                for j, _ in enumerate(mi):
+                    diag_entries[(i + rmax, j + cmax)] = _
+            rmax += r
+            cmax += c
+        if rows is None:
+            rows, cols = cols, rows
+        if rows is None:
+            rows, cols = rmax, cmax
+        else:
+            cols = rows if cols is None else cols
+        if rows < rmax or cols < cmax:
+            raise ValueError(filldedent('''
+                The constructed matrix is {} x {} but a size of {} x {}
+                was specified.'''.format(rmax, cmax, rows, cols)))
+        return klass._eval_diag(rows, cols, diag_entries)
+
+    @classmethod
+    def eye(kls, rows, cols=None, **kwargs):
+        """Returns an identity matrix.
+
+        Parameters
+        ==========
+
+        rows : rows of the matrix
+        cols : cols of the matrix (if None, cols=rows)
+
+        kwargs
+        ======
+        cls : class of the returned matrix
+        """
+        if cols is None:
+            cols = rows
+        if rows < 0 or cols < 0:
+            raise ValueError("Cannot create a {} x {} matrix. "
+                             "Both dimensions must be positive".format(rows, cols))
+        klass = kwargs.get('cls', kls)
+        rows, cols = as_int(rows), as_int(cols)
+
+        return klass._eval_eye(rows, cols)
+
+    @classmethod
+    def jordan_block(kls, size=None, eigenvalue=None, *, band='upper', **kwargs):
+        """Returns a Jordan block
+
+        Parameters
+        ==========
+
+        size : Integer, optional
+            Specifies the shape of the Jordan block matrix.
+
+        eigenvalue : Number or Symbol
+            Specifies the value for the main diagonal of the matrix.
+
+            .. note::
+                The keyword ``eigenval`` is also specified as an alias
+                of this keyword, but it is not recommended to use.
+
+                We may deprecate the alias in later release.
+
+        band : 'upper' or 'lower', optional
+            Specifies the position of the off-diagonal to put `1` s on.
+
+        cls : Matrix, optional
+            Specifies the matrix class of the output form.
+
+            If it is not specified, the class type where the method is
+            being executed on will be returned.
+
+        Returns
+        =======
+
+        Matrix
+            A Jordan block matrix.
+
+        Raises
+        ======
+
+        ValueError
+            If insufficient arguments are given for matrix size
+            specification, or no eigenvalue is given.
+
+        Examples
+        ========
+
+        Creating a default Jordan block:
+
+        >>> from sympy import Matrix
+        >>> from sympy.abc import x
+        >>> Matrix.jordan_block(4, x)
+        Matrix([
+        [x, 1, 0, 0],
+        [0, x, 1, 0],
+        [0, 0, x, 1],
+        [0, 0, 0, x]])
+
+        Creating an alternative Jordan block matrix where `1` is on
+        lower off-diagonal:
+
+        >>> Matrix.jordan_block(4, x, band='lower')
+        Matrix([
+        [x, 0, 0, 0],
+        [1, x, 0, 0],
+        [0, 1, x, 0],
+        [0, 0, 1, x]])
+
+        Creating a Jordan block with keyword arguments
+
+        >>> Matrix.jordan_block(size=4, eigenvalue=x)
+        Matrix([
+        [x, 1, 0, 0],
+        [0, x, 1, 0],
+        [0, 0, x, 1],
+        [0, 0, 0, x]])
+
+        References
+        ==========
+
+        .. [1] https://en.wikipedia.org/wiki/Jordan_matrix
+        """
+        klass = kwargs.pop('cls', kls)
+
+        eigenval = kwargs.get('eigenval', None)
+        if eigenvalue is None and eigenval is None:
+            raise ValueError("Must supply an eigenvalue")
+        elif eigenvalue != eigenval and None not in (eigenval, eigenvalue):
+            raise ValueError(
+                "Inconsistent values are given: 'eigenval'={}, "
+                "'eigenvalue'={}".format(eigenval, eigenvalue))
+        else:
+            if eigenval is not None:
+                eigenvalue = eigenval
+
+        if size is None:
+            raise ValueError("Must supply a matrix size")
+
+        size = as_int(size)
+        return klass._eval_jordan_block(size, eigenvalue, band)
+
+    @classmethod
+    def ones(kls, rows, cols=None, **kwargs):
+        """Returns a matrix of ones.
+
+        Parameters
+        ==========
+
+        rows : rows of the matrix
+        cols : cols of the matrix (if None, cols=rows)
+
+        kwargs
+        ======
+        cls : class of the returned matrix
+        """
+        if cols is None:
+            cols = rows
+        klass = kwargs.get('cls', kls)
+        rows, cols = as_int(rows), as_int(cols)
+
+        return klass._eval_ones(rows, cols)
+
+    @classmethod
+    def zeros(kls, rows, cols=None, **kwargs):
+        """Returns a matrix of zeros.
+
+        Parameters
+        ==========
+
+        rows : rows of the matrix
+        cols : cols of the matrix (if None, cols=rows)
+
+        kwargs
+        ======
+        cls : class of the returned matrix
+        """
+        if cols is None:
+            cols = rows
+        if rows < 0 or cols < 0:
+            raise ValueError("Cannot create a {} x {} matrix. "
+                             "Both dimensions must be positive".format(rows, cols))
+        klass = kwargs.get('cls', kls)
+        rows, cols = as_int(rows), as_int(cols)
+
+        return klass._eval_zeros(rows, cols)
+
+    @classmethod
+    def companion(kls, poly):
+        """Returns a companion matrix of a polynomial.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix, Poly, Symbol, symbols
+        >>> x = Symbol('x')
+        >>> c0, c1, c2, c3, c4 = symbols('c0:5')
+        >>> p = Poly(c0 + c1*x + c2*x**2 + c3*x**3 + c4*x**4 + x**5, x)
+        >>> Matrix.companion(p)
+        Matrix([
+        [0, 0, 0, 0, -c0],
+        [1, 0, 0, 0, -c1],
+        [0, 1, 0, 0, -c2],
+        [0, 0, 1, 0, -c3],
+        [0, 0, 0, 1, -c4]])
+        """
+        poly = kls._sympify(poly)
+        if not isinstance(poly, Poly):
+            raise ValueError("{} must be a Poly instance.".format(poly))
+        if not poly.is_monic:
+            raise ValueError("{} must be a monic polynomial.".format(poly))
+        if not poly.is_univariate:
+            raise ValueError(
+                "{} must be a univariate polynomial.".format(poly))
+
+        size = poly.degree()
+        if not size >= 1:
+            raise ValueError(
+                "{} must have degree not less than 1.".format(poly))
+
+        coeffs = poly.all_coeffs()
+        def entry(i, j):
+            if j == size - 1:
+                return -coeffs[-1 - i]
+            elif i == j + 1:
+                return kls.one
+            return kls.zero
+        return kls._new(size, size, entry)
+
+
+    @classmethod
+    def wilkinson(kls, n, **kwargs):
+        """Returns two square Wilkinson Matrix of size 2*n + 1
+        $W_{2n + 1}^-, W_{2n + 1}^+ =$ Wilkinson(n)
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> wminus, wplus = Matrix.wilkinson(3)
+        >>> wminus
+        Matrix([
+        [-3,  1,  0, 0, 0, 0, 0],
+        [ 1, -2,  1, 0, 0, 0, 0],
+        [ 0,  1, -1, 1, 0, 0, 0],
+        [ 0,  0,  1, 0, 1, 0, 0],
+        [ 0,  0,  0, 1, 1, 1, 0],
+        [ 0,  0,  0, 0, 1, 2, 1],
+        [ 0,  0,  0, 0, 0, 1, 3]])
+        >>> wplus
+        Matrix([
+        [3, 1, 0, 0, 0, 0, 0],
+        [1, 2, 1, 0, 0, 0, 0],
+        [0, 1, 1, 1, 0, 0, 0],
+        [0, 0, 1, 0, 1, 0, 0],
+        [0, 0, 0, 1, 1, 1, 0],
+        [0, 0, 0, 0, 1, 2, 1],
+        [0, 0, 0, 0, 0, 1, 3]])
+
+        References
+        ==========
+
+        .. [1] https://blogs.mathworks.com/cleve/2013/04/15/wilkinsons-matrices-2/
+        .. [2] J. H. Wilkinson, The Algebraic Eigenvalue Problem, Claredon Press, Oxford, 1965, 662 pp.
+
+        """
+        klass = kwargs.get('cls', kls)
+        n = as_int(n)
+        return klass._eval_wilkinson(n)
+
+class MatrixProperties(MatrixRequired):
+    """Provides basic properties of a matrix."""
+
+    def _eval_atoms(self, *types):
+        result = set()
+        for i in self:
+            result.update(i.atoms(*types))
+        return result
+
+    def _eval_free_symbols(self):
+        return set().union(*(i.free_symbols for i in self if i))
+
+    def _eval_has(self, *patterns):
+        return any(a.has(*patterns) for a in self)
+
+    def _eval_is_anti_symmetric(self, simpfunc):
+        if not all(simpfunc(self[i, j] + self[j, i]).is_zero for i in range(self.rows) for j in range(self.cols)):
+            return False
+        return True
+
+    def _eval_is_diagonal(self):
+        for i in range(self.rows):
+            for j in range(self.cols):
+                if i != j and self[i, j]:
+                    return False
+        return True
+
+    # _eval_is_hermitian is called by some general SymPy
+    # routines and has a different *args signature.  Make
+    # sure the names don't clash by adding `_matrix_` in name.
+    def _eval_is_matrix_hermitian(self, simpfunc):
+        mat = self._new(self.rows, self.cols, lambda i, j: simpfunc(self[i, j] - self[j, i].conjugate()))
+        return mat.is_zero_matrix
+
+    def _eval_is_Identity(self) -> FuzzyBool:
+        def dirac(i, j):
+            if i == j:
+                return 1
+            return 0
+
+        return all(self[i, j] == dirac(i, j)
+                for i in range(self.rows)
+                for j in range(self.cols))
+
+    def _eval_is_lower_hessenberg(self):
+        return all(self[i, j].is_zero
+                   for i in range(self.rows)
+                   for j in range(i + 2, self.cols))
+
+    def _eval_is_lower(self):
+        return all(self[i, j].is_zero
+                   for i in range(self.rows)
+                   for j in range(i + 1, self.cols))
+
+    def _eval_is_symbolic(self):
+        return self.has(Symbol)
+
+    def _eval_is_symmetric(self, simpfunc):
+        mat = self._new(self.rows, self.cols, lambda i, j: simpfunc(self[i, j] - self[j, i]))
+        return mat.is_zero_matrix
+
+    def _eval_is_zero_matrix(self):
+        if any(i.is_zero == False for i in self):
+            return False
+        if any(i.is_zero is None for i in self):
+            return None
+        return True
+
+    def _eval_is_upper_hessenberg(self):
+        return all(self[i, j].is_zero
+                   for i in range(2, self.rows)
+                   for j in range(min(self.cols, (i - 1))))
+
+    def _eval_values(self):
+        return [i for i in self if not i.is_zero]
+
+    def _has_positive_diagonals(self):
+        diagonal_entries = (self[i, i] for i in range(self.rows))
+        return fuzzy_and(x.is_positive for x in diagonal_entries)
+
+    def _has_nonnegative_diagonals(self):
+        diagonal_entries = (self[i, i] for i in range(self.rows))
+        return fuzzy_and(x.is_nonnegative for x in diagonal_entries)
+
+    def atoms(self, *types):
+        """Returns the atoms that form the current object.
+
+        Examples
+        ========
+
+        >>> from sympy.abc import x, y
+        >>> from sympy import Matrix
+        >>> Matrix([[x]])
+        Matrix([[x]])
+        >>> _.atoms()
+        {x}
+        >>> Matrix([[x, y], [y, x]])
+        Matrix([
+        [x, y],
+        [y, x]])
+        >>> _.atoms()
+        {x, y}
+        """
+
+        types = tuple(t if isinstance(t, type) else type(t) for t in types)
+        if not types:
+            types = (Atom,)
+        return self._eval_atoms(*types)
+
+    @property
+    def free_symbols(self):
+        """Returns the free symbols within the matrix.
+
+        Examples
+        ========
+
+        >>> from sympy.abc import x
+        >>> from sympy import Matrix
+        >>> Matrix([[x], [1]]).free_symbols
+        {x}
+        """
+        return self._eval_free_symbols()
+
+    def has(self, *patterns):
+        """Test whether any subexpression matches any of the patterns.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix, SparseMatrix, Float
+        >>> from sympy.abc import x, y
+        >>> A = Matrix(((1, x), (0.2, 3)))
+        >>> B = SparseMatrix(((1, x), (0.2, 3)))
+        >>> A.has(x)
+        True
+        >>> A.has(y)
+        False
+        >>> A.has(Float)
+        True
+        >>> B.has(x)
+        True
+        >>> B.has(y)
+        False
+        >>> B.has(Float)
+        True
+        """
+        return self._eval_has(*patterns)
+
+    def is_anti_symmetric(self, simplify=True):
+        """Check if matrix M is an antisymmetric matrix,
+        that is, M is a square matrix with all M[i, j] == -M[j, i].
+
+        When ``simplify=True`` (default), the sum M[i, j] + M[j, i] is
+        simplified before testing to see if it is zero. By default,
+        the SymPy simplify function is used. To use a custom function
+        set simplify to a function that accepts a single argument which
+        returns a simplified expression. To skip simplification, set
+        simplify to False but note that although this will be faster,
+        it may induce false negatives.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix, symbols
+        >>> m = Matrix(2, 2, [0, 1, -1, 0])
+        >>> m
+        Matrix([
+        [ 0, 1],
+        [-1, 0]])
+        >>> m.is_anti_symmetric()
+        True
+        >>> x, y = symbols('x y')
+        >>> m = Matrix(2, 3, [0, 0, x, -y, 0, 0])
+        >>> m
+        Matrix([
+        [ 0, 0, x],
+        [-y, 0, 0]])
+        >>> m.is_anti_symmetric()
+        False
+
+        >>> from sympy.abc import x, y
+        >>> m = Matrix(3, 3, [0, x**2 + 2*x + 1, y,
+        ...                   -(x + 1)**2, 0, x*y,
+        ...                   -y, -x*y, 0])
+
+        Simplification of matrix elements is done by default so even
+        though two elements which should be equal and opposite would not
+        pass an equality test, the matrix is still reported as
+        anti-symmetric:
+
+        >>> m[0, 1] == -m[1, 0]
+        False
+        >>> m.is_anti_symmetric()
+        True
+
+        If ``simplify=False`` is used for the case when a Matrix is already
+        simplified, this will speed things up. Here, we see that without
+        simplification the matrix does not appear anti-symmetric:
+
+        >>> print(m.is_anti_symmetric(simplify=False))
+        None
+
+        But if the matrix were already expanded, then it would appear
+        anti-symmetric and simplification in the is_anti_symmetric routine
+        is not needed:
+
+        >>> m = m.expand()
+        >>> m.is_anti_symmetric(simplify=False)
+        True
+        """
+        # accept custom simplification
+        simpfunc = simplify
+        if not isfunction(simplify):
+            simpfunc = _simplify if simplify else lambda x: x
+
+        if not self.is_square:
+            return False
+        return self._eval_is_anti_symmetric(simpfunc)
+
+    def is_diagonal(self):
+        """Check if matrix is diagonal,
+        that is matrix in which the entries outside the main diagonal are all zero.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix, diag
+        >>> m = Matrix(2, 2, [1, 0, 0, 2])
+        >>> m
+        Matrix([
+        [1, 0],
+        [0, 2]])
+        >>> m.is_diagonal()
+        True
+
+        >>> m = Matrix(2, 2, [1, 1, 0, 2])
+        >>> m
+        Matrix([
+        [1, 1],
+        [0, 2]])
+        >>> m.is_diagonal()
+        False
+
+        >>> m = diag(1, 2, 3)
+        >>> m
+        Matrix([
+        [1, 0, 0],
+        [0, 2, 0],
+        [0, 0, 3]])
+        >>> m.is_diagonal()
+        True
+
+        See Also
+        ========
+
+        is_lower
+        is_upper
+        sympy.matrices.matrixbase.MatrixCommon.is_diagonalizable
+        diagonalize
+        """
+        return self._eval_is_diagonal()
+
+    @property
+    def is_weakly_diagonally_dominant(self):
+        r"""Tests if the matrix is row weakly diagonally dominant.
+
+        Explanation
+        ===========
+
+        A $n, n$ matrix $A$ is row weakly diagonally dominant if
+
+        .. math::
+            \left|A_{i, i}\right| \ge \sum_{j = 0, j \neq i}^{n-1}
+            \left|A_{i, j}\right| \quad {\text{for all }}
+            i \in \{ 0, ..., n-1 \}
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> A = Matrix([[3, -2, 1], [1, -3, 2], [-1, 2, 4]])
+        >>> A.is_weakly_diagonally_dominant
+        True
+
+        >>> A = Matrix([[-2, 2, 1], [1, 3, 2], [1, -2, 0]])
+        >>> A.is_weakly_diagonally_dominant
+        False
+
+        >>> A = Matrix([[-4, 2, 1], [1, 6, 2], [1, -2, 5]])
+        >>> A.is_weakly_diagonally_dominant
+        True
+
+        Notes
+        =====
+
+        If you want to test whether a matrix is column diagonally
+        dominant, you can apply the test after transposing the matrix.
+        """
+        if not self.is_square:
+            return False
+
+        rows, cols = self.shape
+
+        def test_row(i):
+            summation = self.zero
+            for j in range(cols):
+                if i != j:
+                    summation += Abs(self[i, j])
+            return (Abs(self[i, i]) - summation).is_nonnegative
+
+        return fuzzy_and(test_row(i) for i in range(rows))
+
+    @property
+    def is_strongly_diagonally_dominant(self):
+        r"""Tests if the matrix is row strongly diagonally dominant.
+
+        Explanation
+        ===========
+
+        A $n, n$ matrix $A$ is row strongly diagonally dominant if
+
+        .. math::
+            \left|A_{i, i}\right| > \sum_{j = 0, j \neq i}^{n-1}
+            \left|A_{i, j}\right| \quad {\text{for all }}
+            i \in \{ 0, ..., n-1 \}
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> A = Matrix([[3, -2, 1], [1, -3, 2], [-1, 2, 4]])
+        >>> A.is_strongly_diagonally_dominant
+        False
+
+        >>> A = Matrix([[-2, 2, 1], [1, 3, 2], [1, -2, 0]])
+        >>> A.is_strongly_diagonally_dominant
+        False
+
+        >>> A = Matrix([[-4, 2, 1], [1, 6, 2], [1, -2, 5]])
+        >>> A.is_strongly_diagonally_dominant
+        True
+
+        Notes
+        =====
+
+        If you want to test whether a matrix is column diagonally
+        dominant, you can apply the test after transposing the matrix.
+        """
+        if not self.is_square:
+            return False
+
+        rows, cols = self.shape
+
+        def test_row(i):
+            summation = self.zero
+            for j in range(cols):
+                if i != j:
+                    summation += Abs(self[i, j])
+            return (Abs(self[i, i]) - summation).is_positive
+
+        return fuzzy_and(test_row(i) for i in range(rows))
+
+    @property
+    def is_hermitian(self):
+        """Checks if the matrix is Hermitian.
+
+        In a Hermitian matrix element i,j is the complex conjugate of
+        element j,i.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> from sympy import I
+        >>> from sympy.abc import x
+        >>> a = Matrix([[1, I], [-I, 1]])
+        >>> a
+        Matrix([
+        [ 1, I],
+        [-I, 1]])
+        >>> a.is_hermitian
+        True
+        >>> a[0, 0] = 2*I
+        >>> a.is_hermitian
+        False
+        >>> a[0, 0] = x
+        >>> a.is_hermitian
+        >>> a[0, 1] = a[1, 0]*I
+        >>> a.is_hermitian
+        False
+        """
+        if not self.is_square:
+            return False
+
+        return self._eval_is_matrix_hermitian(_simplify)
+
+    @property
+    def is_Identity(self) -> FuzzyBool:
+        if not self.is_square:
+            return False
+        return self._eval_is_Identity()
+
+    @property
+    def is_lower_hessenberg(self):
+        r"""Checks if the matrix is in the lower-Hessenberg form.
+
+        The lower hessenberg matrix has zero entries
+        above the first superdiagonal.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> a = Matrix([[1, 2, 0, 0], [5, 2, 3, 0], [3, 4, 3, 7], [5, 6, 1, 1]])
+        >>> a
+        Matrix([
+        [1, 2, 0, 0],
+        [5, 2, 3, 0],
+        [3, 4, 3, 7],
+        [5, 6, 1, 1]])
+        >>> a.is_lower_hessenberg
+        True
+
+        See Also
+        ========
+
+        is_upper_hessenberg
+        is_lower
+        """
+        return self._eval_is_lower_hessenberg()
+
+    @property
+    def is_lower(self):
+        """Check if matrix is a lower triangular matrix. True can be returned
+        even if the matrix is not square.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> m = Matrix(2, 2, [1, 0, 0, 1])
+        >>> m
+        Matrix([
+        [1, 0],
+        [0, 1]])
+        >>> m.is_lower
+        True
+
+        >>> m = Matrix(4, 3, [0, 0, 0, 2, 0, 0, 1, 4, 0, 6, 6, 5])
+        >>> m
+        Matrix([
+        [0, 0, 0],
+        [2, 0, 0],
+        [1, 4, 0],
+        [6, 6, 5]])
+        >>> m.is_lower
+        True
+
+        >>> from sympy.abc import x, y
+        >>> m = Matrix(2, 2, [x**2 + y, y**2 + x, 0, x + y])
+        >>> m
+        Matrix([
+        [x**2 + y, x + y**2],
+        [       0,    x + y]])
+        >>> m.is_lower
+        False
+
+        See Also
+        ========
+
+        is_upper
+        is_diagonal
+        is_lower_hessenberg
+        """
+        return self._eval_is_lower()
+
+    @property
+    def is_square(self):
+        """Checks if a matrix is square.
+
+        A matrix is square if the number of rows equals the number of columns.
+        The empty matrix is square by definition, since the number of rows and
+        the number of columns are both zero.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> a = Matrix([[1, 2, 3], [4, 5, 6]])
+        >>> b = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+        >>> c = Matrix([])
+        >>> a.is_square
+        False
+        >>> b.is_square
+        True
+        >>> c.is_square
+        True
+        """
+        return self.rows == self.cols
+
+    def is_symbolic(self):
+        """Checks if any elements contain Symbols.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> from sympy.abc import x, y
+        >>> M = Matrix([[x, y], [1, 0]])
+        >>> M.is_symbolic()
+        True
+
+        """
+        return self._eval_is_symbolic()
+
+    def is_symmetric(self, simplify=True):
+        """Check if matrix is symmetric matrix,
+        that is square matrix and is equal to its transpose.
+
+        By default, simplifications occur before testing symmetry.
+        They can be skipped using 'simplify=False'; while speeding things a bit,
+        this may however induce false negatives.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> m = Matrix(2, 2, [0, 1, 1, 2])
+        >>> m
+        Matrix([
+        [0, 1],
+        [1, 2]])
+        >>> m.is_symmetric()
+        True
+
+        >>> m = Matrix(2, 2, [0, 1, 2, 0])
+        >>> m
+        Matrix([
+        [0, 1],
+        [2, 0]])
+        >>> m.is_symmetric()
+        False
+
+        >>> m = Matrix(2, 3, [0, 0, 0, 0, 0, 0])
+        >>> m
+        Matrix([
+        [0, 0, 0],
+        [0, 0, 0]])
+        >>> m.is_symmetric()
+        False
+
+        >>> from sympy.abc import x, y
+        >>> m = Matrix(3, 3, [1, x**2 + 2*x + 1, y, (x + 1)**2, 2, 0, y, 0, 3])
+        >>> m
+        Matrix([
+        [         1, x**2 + 2*x + 1, y],
+        [(x + 1)**2,              2, 0],
+        [         y,              0, 3]])
+        >>> m.is_symmetric()
+        True
+
+        If the matrix is already simplified, you may speed-up is_symmetric()
+        test by using 'simplify=False'.
+
+        >>> bool(m.is_symmetric(simplify=False))
+        False
+        >>> m1 = m.expand()
+        >>> m1.is_symmetric(simplify=False)
+        True
+        """
+        simpfunc = simplify
+        if not isfunction(simplify):
+            simpfunc = _simplify if simplify else lambda x: x
+
+        if not self.is_square:
+            return False
+
+        return self._eval_is_symmetric(simpfunc)
+
+    @property
+    def is_upper_hessenberg(self):
+        """Checks if the matrix is the upper-Hessenberg form.
+
+        The upper hessenberg matrix has zero entries
+        below the first subdiagonal.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> a = Matrix([[1, 4, 2, 3], [3, 4, 1, 7], [0, 2, 3, 4], [0, 0, 1, 3]])
+        >>> a
+        Matrix([
+        [1, 4, 2, 3],
+        [3, 4, 1, 7],
+        [0, 2, 3, 4],
+        [0, 0, 1, 3]])
+        >>> a.is_upper_hessenberg
+        True
+
+        See Also
+        ========
+
+        is_lower_hessenberg
+        is_upper
+        """
+        return self._eval_is_upper_hessenberg()
+
+    @property
+    def is_upper(self):
+        """Check if matrix is an upper triangular matrix. True can be returned
+        even if the matrix is not square.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> m = Matrix(2, 2, [1, 0, 0, 1])
+        >>> m
+        Matrix([
+        [1, 0],
+        [0, 1]])
+        >>> m.is_upper
+        True
+
+        >>> m = Matrix(4, 3, [5, 1, 9, 0, 4, 6, 0, 0, 5, 0, 0, 0])
+        >>> m
+        Matrix([
+        [5, 1, 9],
+        [0, 4, 6],
+        [0, 0, 5],
+        [0, 0, 0]])
+        >>> m.is_upper
+        True
+
+        >>> m = Matrix(2, 3, [4, 2, 5, 6, 1, 1])
+        >>> m
+        Matrix([
+        [4, 2, 5],
+        [6, 1, 1]])
+        >>> m.is_upper
+        False
+
+        See Also
+        ========
+
+        is_lower
+        is_diagonal
+        is_upper_hessenberg
+        """
+        return all(self[i, j].is_zero
+                   for i in range(1, self.rows)
+                   for j in range(min(i, self.cols)))
+
+    @property
+    def is_zero_matrix(self):
+        """Checks if a matrix is a zero matrix.
+
+        A matrix is zero if every element is zero.  A matrix need not be square
+        to be considered zero.  The empty matrix is zero by the principle of
+        vacuous truth.  For a matrix that may or may not be zero (e.g.
+        contains a symbol), this will be None
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix, zeros
+        >>> from sympy.abc import x
+        >>> a = Matrix([[0, 0], [0, 0]])
+        >>> b = zeros(3, 4)
+        >>> c = Matrix([[0, 1], [0, 0]])
+        >>> d = Matrix([])
+        >>> e = Matrix([[x, 0], [0, 0]])
+        >>> a.is_zero_matrix
+        True
+        >>> b.is_zero_matrix
+        True
+        >>> c.is_zero_matrix
+        False
+        >>> d.is_zero_matrix
+        True
+        >>> e.is_zero_matrix
+        """
+        return self._eval_is_zero_matrix()
+
+    def values(self):
+        """Return non-zero values of self."""
+        return self._eval_values()
+
+
+class MatrixOperations(MatrixRequired):
+    """Provides basic matrix shape and elementwise
+    operations.  Should not be instantiated directly."""
+
+    def _eval_adjoint(self):
+        return self.transpose().conjugate()
+
+    def _eval_applyfunc(self, f):
+        out = self._new(self.rows, self.cols, [f(x) for x in self])
+        return out
+
+    def _eval_as_real_imag(self):  # type: ignore
+        return (self.applyfunc(re), self.applyfunc(im))
+
+    def _eval_conjugate(self):
+        return self.applyfunc(lambda x: x.conjugate())
+
+    def _eval_permute_cols(self, perm):
+        # apply the permutation to a list
+        mapping = list(perm)
+
+        def entry(i, j):
+            return self[i, mapping[j]]
+
+        return self._new(self.rows, self.cols, entry)
+
+    def _eval_permute_rows(self, perm):
+        # apply the permutation to a list
+        mapping = list(perm)
+
+        def entry(i, j):
+            return self[mapping[i], j]
+
+        return self._new(self.rows, self.cols, entry)
+
+    def _eval_trace(self):
+        return sum(self[i, i] for i in range(self.rows))
+
+    def _eval_transpose(self):
+        return self._new(self.cols, self.rows, lambda i, j: self[j, i])
+
+    def adjoint(self):
+        """Conjugate transpose or Hermitian conjugation."""
+        return self._eval_adjoint()
+
+    def applyfunc(self, f):
+        """Apply a function to each element of the matrix.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> m = Matrix(2, 2, lambda i, j: i*2+j)
+        >>> m
+        Matrix([
+        [0, 1],
+        [2, 3]])
+        >>> m.applyfunc(lambda i: 2*i)
+        Matrix([
+        [0, 2],
+        [4, 6]])
+
+        """
+        if not callable(f):
+            raise TypeError("`f` must be callable.")
+
+        return self._eval_applyfunc(f)
+
+    def as_real_imag(self, deep=True, **hints):
+        """Returns a tuple containing the (real, imaginary) part of matrix."""
+        # XXX: Ignoring deep and hints...
+        return self._eval_as_real_imag()
+
+    def conjugate(self):
+        """Return the by-element conjugation.
+
+        Examples
+        ========
+
+        >>> from sympy import SparseMatrix, I
+        >>> a = SparseMatrix(((1, 2 + I), (3, 4), (I, -I)))
+        >>> a
+        Matrix([
+        [1, 2 + I],
+        [3,     4],
+        [I,    -I]])
+        >>> a.C
+        Matrix([
+        [ 1, 2 - I],
+        [ 3,     4],
+        [-I,     I]])
+
+        See Also
+        ========
+
+        transpose: Matrix transposition
+        H: Hermite conjugation
+        sympy.matrices.matrixbase.MatrixBase.D: Dirac conjugation
+        """
+        return self._eval_conjugate()
+
+    def doit(self, **hints):
+        return self.applyfunc(lambda x: x.doit(**hints))
+
+    def evalf(self, n=15, subs=None, maxn=100, chop=False, strict=False, quad=None, verbose=False):
+        """Apply evalf() to each element of self."""
+        options = {'subs':subs, 'maxn':maxn, 'chop':chop, 'strict':strict,
+                'quad':quad, 'verbose':verbose}
+        return self.applyfunc(lambda i: i.evalf(n, **options))
+
+    def expand(self, deep=True, modulus=None, power_base=True, power_exp=True,
+               mul=True, log=True, multinomial=True, basic=True, **hints):
+        """Apply core.function.expand to each entry of the matrix.
+
+        Examples
+        ========
+
+        >>> from sympy.abc import x
+        >>> from sympy import Matrix
+        >>> Matrix(1, 1, [x*(x+1)])
+        Matrix([[x*(x + 1)]])
+        >>> _.expand()
+        Matrix([[x**2 + x]])
+
+        """
+        return self.applyfunc(lambda x: x.expand(
+            deep, modulus, power_base, power_exp, mul, log, multinomial, basic,
+            **hints))
+
+    @property
+    def H(self):
+        """Return Hermite conjugate.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix, I
+        >>> m = Matrix((0, 1 + I, 2, 3))
+        >>> m
+        Matrix([
+        [    0],
+        [1 + I],
+        [    2],
+        [    3]])
+        >>> m.H
+        Matrix([[0, 1 - I, 2, 3]])
+
+        See Also
+        ========
+
+        conjugate: By-element conjugation
+        sympy.matrices.matrixbase.MatrixBase.D: Dirac conjugation
+        """
+        return self.T.C
+
+    def permute(self, perm, orientation='rows', direction='forward'):
+        r"""Permute the rows or columns of a matrix by the given list of
+        swaps.
+
+        Parameters
+        ==========
+
+        perm : Permutation, list, or list of lists
+            A representation for the permutation.
+
+            If it is ``Permutation``, it is used directly with some
+            resizing with respect to the matrix size.
+
+            If it is specified as list of lists,
+            (e.g., ``[[0, 1], [0, 2]]``), then the permutation is formed
+            from applying the product of cycles. The direction how the
+            cyclic product is applied is described in below.
+
+            If it is specified as a list, the list should represent
+            an array form of a permutation. (e.g., ``[1, 2, 0]``) which
+            would would form the swapping function
+            `0 \mapsto 1, 1 \mapsto 2, 2\mapsto 0`.
+
+        orientation : 'rows', 'cols'
+            A flag to control whether to permute the rows or the columns
+
+        direction : 'forward', 'backward'
+            A flag to control whether to apply the permutations from
+            the start of the list first, or from the back of the list
+            first.
+
+            For example, if the permutation specification is
+            ``[[0, 1], [0, 2]]``,
+
+            If the flag is set to ``'forward'``, the cycle would be
+            formed as `0 \mapsto 2, 2 \mapsto 1, 1 \mapsto 0`.
+
+            If the flag is set to ``'backward'``, the cycle would be
+            formed as `0 \mapsto 1, 1 \mapsto 2, 2 \mapsto 0`.
+
+            If the argument ``perm`` is not in a form of list of lists,
+            this flag takes no effect.
+
+        Examples
+        ========
+
+        >>> from sympy import eye
+        >>> M = eye(3)
+        >>> M.permute([[0, 1], [0, 2]], orientation='rows', direction='forward')
+        Matrix([
+        [0, 0, 1],
+        [1, 0, 0],
+        [0, 1, 0]])
+
+        >>> from sympy import eye
+        >>> M = eye(3)
+        >>> M.permute([[0, 1], [0, 2]], orientation='rows', direction='backward')
+        Matrix([
+        [0, 1, 0],
+        [0, 0, 1],
+        [1, 0, 0]])
+
+        Notes
+        =====
+
+        If a bijective function
+        `\sigma : \mathbb{N}_0 \rightarrow \mathbb{N}_0` denotes the
+        permutation.
+
+        If the matrix `A` is the matrix to permute, represented as
+        a horizontal or a vertical stack of vectors:
+
+        .. math::
+            A =
+            \begin{bmatrix}
+            a_0 \\ a_1 \\ \vdots \\ a_{n-1}
+            \end{bmatrix} =
+            \begin{bmatrix}
+            \alpha_0 & \alpha_1 & \cdots & \alpha_{n-1}
+            \end{bmatrix}
+
+        If the matrix `B` is the result, the permutation of matrix rows
+        is defined as:
+
+        .. math::
+            B := \begin{bmatrix}
+            a_{\sigma(0)} \\ a_{\sigma(1)} \\ \vdots \\ a_{\sigma(n-1)}
+            \end{bmatrix}
+
+        And the permutation of matrix columns is defined as:
+
+        .. math::
+            B := \begin{bmatrix}
+            \alpha_{\sigma(0)} & \alpha_{\sigma(1)} &
+            \cdots & \alpha_{\sigma(n-1)}
+            \end{bmatrix}
+        """
+        from sympy.combinatorics import Permutation
+
+        # allow british variants and `columns`
+        if direction == 'forwards':
+            direction = 'forward'
+        if direction == 'backwards':
+            direction = 'backward'
+        if orientation == 'columns':
+            orientation = 'cols'
+
+        if direction not in ('forward', 'backward'):
+            raise TypeError("direction='{}' is an invalid kwarg. "
+                            "Try 'forward' or 'backward'".format(direction))
+        if orientation not in ('rows', 'cols'):
+            raise TypeError("orientation='{}' is an invalid kwarg. "
+                            "Try 'rows' or 'cols'".format(orientation))
+
+        if not isinstance(perm, (Permutation, Iterable)):
+            raise ValueError(
+                "{} must be a list, a list of lists, "
+                "or a SymPy permutation object.".format(perm))
+
+        # ensure all swaps are in range
+        max_index = self.rows if orientation == 'rows' else self.cols
+        if not all(0 <= t <= max_index for t in flatten(list(perm))):
+            raise IndexError("`swap` indices out of range.")
+
+        if perm and not isinstance(perm, Permutation) and \
+            isinstance(perm[0], Iterable):
+            if direction == 'forward':
+                perm = list(reversed(perm))
+            perm = Permutation(perm, size=max_index+1)
+        else:
+            perm = Permutation(perm, size=max_index+1)
+
+        if orientation == 'rows':
+            return self._eval_permute_rows(perm)
+        if orientation == 'cols':
+            return self._eval_permute_cols(perm)
+
+    def permute_cols(self, swaps, direction='forward'):
+        """Alias for
+        ``self.permute(swaps, orientation='cols', direction=direction)``
+
+        See Also
+        ========
+
+        permute
+        """
+        return self.permute(swaps, orientation='cols', direction=direction)
+
+    def permute_rows(self, swaps, direction='forward'):
+        """Alias for
+        ``self.permute(swaps, orientation='rows', direction=direction)``
+
+        See Also
+        ========
+
+        permute
+        """
+        return self.permute(swaps, orientation='rows', direction=direction)
+
+    def refine(self, assumptions=True):
+        """Apply refine to each element of the matrix.
+
+        Examples
+        ========
+
+        >>> from sympy import Symbol, Matrix, Abs, sqrt, Q
+        >>> x = Symbol('x')
+        >>> Matrix([[Abs(x)**2, sqrt(x**2)],[sqrt(x**2), Abs(x)**2]])
+        Matrix([
+        [ Abs(x)**2, sqrt(x**2)],
+        [sqrt(x**2),  Abs(x)**2]])
+        >>> _.refine(Q.real(x))
+        Matrix([
+        [  x**2, Abs(x)],
+        [Abs(x),   x**2]])
+
+        """
+        return self.applyfunc(lambda x: refine(x, assumptions))
+
+    def replace(self, F, G, map=False, simultaneous=True, exact=None):
+        """Replaces Function F in Matrix entries with Function G.
+
+        Examples
+        ========
+
+        >>> from sympy import symbols, Function, Matrix
+        >>> F, G = symbols('F, G', cls=Function)
+        >>> M = Matrix(2, 2, lambda i, j: F(i+j)) ; M
+        Matrix([
+        [F(0), F(1)],
+        [F(1), F(2)]])
+        >>> N = M.replace(F,G)
+        >>> N
+        Matrix([
+        [G(0), G(1)],
+        [G(1), G(2)]])
+        """
+        return self.applyfunc(
+            lambda x: x.replace(F, G, map=map, simultaneous=simultaneous, exact=exact))
+
+    def rot90(self, k=1):
+        """Rotates Matrix by 90 degrees
+
+        Parameters
+        ==========
+
+        k : int
+            Specifies how many times the matrix is rotated by 90 degrees
+            (clockwise when positive, counter-clockwise when negative).
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix, symbols
+        >>> A = Matrix(2, 2, symbols('a:d'))
+        >>> A
+        Matrix([
+        [a, b],
+        [c, d]])
+
+        Rotating the matrix clockwise one time:
+
+        >>> A.rot90(1)
+        Matrix([
+        [c, a],
+        [d, b]])
+
+        Rotating the matrix anticlockwise two times:
+
+        >>> A.rot90(-2)
+        Matrix([
+        [d, c],
+        [b, a]])
+        """
+
+        mod = k%4
+        if mod == 0:
+            return self
+        if mod == 1:
+            return self[::-1, ::].T
+        if mod == 2:
+            return self[::-1, ::-1]
+        if mod == 3:
+            return self[::, ::-1].T
+
+    def simplify(self, **kwargs):
+        """Apply simplify to each element of the matrix.
+
+        Examples
+        ========
+
+        >>> from sympy.abc import x, y
+        >>> from sympy import SparseMatrix, sin, cos
+        >>> SparseMatrix(1, 1, [x*sin(y)**2 + x*cos(y)**2])
+        Matrix([[x*sin(y)**2 + x*cos(y)**2]])
+        >>> _.simplify()
+        Matrix([[x]])
+        """
+        return self.applyfunc(lambda x: x.simplify(**kwargs))
+
+    def subs(self, *args, **kwargs):  # should mirror core.basic.subs
+        """Return a new matrix with subs applied to each entry.
+
+        Examples
+        ========
+
+        >>> from sympy.abc import x, y
+        >>> from sympy import SparseMatrix, Matrix
+        >>> SparseMatrix(1, 1, [x])
+        Matrix([[x]])
+        >>> _.subs(x, y)
+        Matrix([[y]])
+        >>> Matrix(_).subs(y, x)
+        Matrix([[x]])
+        """
+
+        if len(args) == 1 and  not isinstance(args[0], (dict, set)) and iter(args[0]) and not is_sequence(args[0]):
+            args = (list(args[0]),)
+
+        return self.applyfunc(lambda x: x.subs(*args, **kwargs))
+
+    def trace(self):
+        """
+        Returns the trace of a square matrix i.e. the sum of the
+        diagonal elements.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> A = Matrix(2, 2, [1, 2, 3, 4])
+        >>> A.trace()
+        5
+
+        """
+        if self.rows != self.cols:
+            raise NonSquareMatrixError()
+        return self._eval_trace()
+
+    def transpose(self):
+        """
+        Returns the transpose of the matrix.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> A = Matrix(2, 2, [1, 2, 3, 4])
+        >>> A.transpose()
+        Matrix([
+        [1, 3],
+        [2, 4]])
+
+        >>> from sympy import Matrix, I
+        >>> m=Matrix(((1, 2+I), (3, 4)))
+        >>> m
+        Matrix([
+        [1, 2 + I],
+        [3,     4]])
+        >>> m.transpose()
+        Matrix([
+        [    1, 3],
+        [2 + I, 4]])
+        >>> m.T == m.transpose()
+        True
+
+        See Also
+        ========
+
+        conjugate: By-element conjugation
+
+        """
+        return self._eval_transpose()
+
+    @property
+    def T(self):
+        '''Matrix transposition'''
+        return self.transpose()
+
+    @property
+    def C(self):
+        '''By-element conjugation'''
+        return self.conjugate()
+
+    def n(self, *args, **kwargs):
+        """Apply evalf() to each element of self."""
+        return self.evalf(*args, **kwargs)
+
+    def xreplace(self, rule):  # should mirror core.basic.xreplace
+        """Return a new matrix with xreplace applied to each entry.
+
+        Examples
+        ========
+
+        >>> from sympy.abc import x, y
+        >>> from sympy import SparseMatrix, Matrix
+        >>> SparseMatrix(1, 1, [x])
+        Matrix([[x]])
+        >>> _.xreplace({x: y})
+        Matrix([[y]])
+        >>> Matrix(_).xreplace({y: x})
+        Matrix([[x]])
+        """
+        return self.applyfunc(lambda x: x.xreplace(rule))
+
+    def _eval_simplify(self, **kwargs):
+        # XXX: We can't use self.simplify here as mutable subclasses will
+        # override simplify and have it return None
+        return MatrixOperations.simplify(self, **kwargs)
+
+    def _eval_trigsimp(self, **opts):
+        from sympy.simplify.trigsimp import trigsimp
+        return self.applyfunc(lambda x: trigsimp(x, **opts))
+
+    def upper_triangular(self, k=0):
+        """Return the elements on and above the kth diagonal of a matrix.
+        If k is not specified then simply returns upper-triangular portion
+        of a matrix
+
+        Examples
+        ========
+
+        >>> from sympy import ones
+        >>> A = ones(4)
+        >>> A.upper_triangular()
+        Matrix([
+        [1, 1, 1, 1],
+        [0, 1, 1, 1],
+        [0, 0, 1, 1],
+        [0, 0, 0, 1]])
+
+        >>> A.upper_triangular(2)
+        Matrix([
+        [0, 0, 1, 1],
+        [0, 0, 0, 1],
+        [0, 0, 0, 0],
+        [0, 0, 0, 0]])
+
+        >>> A.upper_triangular(-1)
+        Matrix([
+        [1, 1, 1, 1],
+        [1, 1, 1, 1],
+        [0, 1, 1, 1],
+        [0, 0, 1, 1]])
+
+        """
+
+        def entry(i, j):
+            return self[i, j] if i + k <= j else self.zero
+
+        return self._new(self.rows, self.cols, entry)
+
+
+    def lower_triangular(self, k=0):
+        """Return the elements on and below the kth diagonal of a matrix.
+        If k is not specified then simply returns lower-triangular portion
+        of a matrix
+
+        Examples
+        ========
+
+        >>> from sympy import ones
+        >>> A = ones(4)
+        >>> A.lower_triangular()
+        Matrix([
+        [1, 0, 0, 0],
+        [1, 1, 0, 0],
+        [1, 1, 1, 0],
+        [1, 1, 1, 1]])
+
+        >>> A.lower_triangular(-2)
+        Matrix([
+        [0, 0, 0, 0],
+        [0, 0, 0, 0],
+        [1, 0, 0, 0],
+        [1, 1, 0, 0]])
+
+        >>> A.lower_triangular(1)
+        Matrix([
+        [1, 1, 0, 0],
+        [1, 1, 1, 0],
+        [1, 1, 1, 1],
+        [1, 1, 1, 1]])
+
+        """
+
+        def entry(i, j):
+            return self[i, j] if i + k >= j else self.zero
+
+        return self._new(self.rows, self.cols, entry)
+
+
+
+class MatrixArithmetic(MatrixRequired):
+    """Provides basic matrix arithmetic operations.
+    Should not be instantiated directly."""
+
+    _op_priority = 10.01
+
+    def _eval_Abs(self):
+        return self._new(self.rows, self.cols, lambda i, j: Abs(self[i, j]))
+
+    def _eval_add(self, other):
+        return self._new(self.rows, self.cols,
+                         lambda i, j: self[i, j] + other[i, j])
+
+    def _eval_matrix_mul(self, other):
+        def entry(i, j):
+            vec = [self[i,k]*other[k,j] for k in range(self.cols)]
+            try:
+                return Add(*vec)
+            except (TypeError, SympifyError):
+                # Some matrices don't work with `sum` or `Add`
+                # They don't work with `sum` because `sum` tries to add `0`
+                # Fall back to a safe way to multiply if the `Add` fails.
+                return reduce(lambda a, b: a + b, vec)
+
+        return self._new(self.rows, other.cols, entry)
+
+    def _eval_matrix_mul_elementwise(self, other):
+        return self._new(self.rows, self.cols, lambda i, j: self[i,j]*other[i,j])
+
+    def _eval_matrix_rmul(self, other):
+        def entry(i, j):
+            return sum(other[i,k]*self[k,j] for k in range(other.cols))
+        return self._new(other.rows, self.cols, entry)
+
+    def _eval_pow_by_recursion(self, num):
+        if num == 1:
+            return self
+
+        if num % 2 == 1:
+            a, b = self, self._eval_pow_by_recursion(num - 1)
+        else:
+            a = b = self._eval_pow_by_recursion(num // 2)
+
+        return a.multiply(b)
+
+    def _eval_pow_by_cayley(self, exp):
+        from sympy.discrete.recurrences import linrec_coeffs
+        row = self.shape[0]
+        p = self.charpoly()
+
+        coeffs = (-p).all_coeffs()[1:]
+        coeffs = linrec_coeffs(coeffs, exp)
+        new_mat = self.eye(row)
+        ans = self.zeros(row)
+
+        for i in range(row):
+            ans += coeffs[i]*new_mat
+            new_mat *= self
+
+        return ans
+
+    def _eval_pow_by_recursion_dotprodsimp(self, num, prevsimp=None):
+        if prevsimp is None:
+            prevsimp = [True]*len(self)
+
+        if num == 1:
+            return self
+
+        if num % 2 == 1:
+            a, b = self, self._eval_pow_by_recursion_dotprodsimp(num - 1,
+                    prevsimp=prevsimp)
+        else:
+            a = b = self._eval_pow_by_recursion_dotprodsimp(num // 2,
+                    prevsimp=prevsimp)
+
+        m     = a.multiply(b, dotprodsimp=False)
+        lenm  = len(m)
+        elems = [None]*lenm
+
+        for i in range(lenm):
+            if prevsimp[i]:
+                elems[i], prevsimp[i] = _dotprodsimp(m[i], withsimp=True)
+            else:
+                elems[i] = m[i]
+
+        return m._new(m.rows, m.cols, elems)
+
+    def _eval_scalar_mul(self, other):
+        return self._new(self.rows, self.cols, lambda i, j: self[i,j]*other)
+
+    def _eval_scalar_rmul(self, other):
+        return self._new(self.rows, self.cols, lambda i, j: other*self[i,j])
+
+    def _eval_Mod(self, other):
+        return self._new(self.rows, self.cols, lambda i, j: Mod(self[i, j], other))
+
+    # Python arithmetic functions
+    def __abs__(self):
+        """Returns a new matrix with entry-wise absolute values."""
+        return self._eval_Abs()
+
+    @call_highest_priority('__radd__')
+    def __add__(self, other):
+        """Return self + other, raising ShapeError if shapes do not match."""
+        if isinstance(other, NDimArray): # Matrix and array addition is currently not implemented
+            return NotImplemented
+        other = _matrixify(other)
+        # matrix-like objects can have shapes.  This is
+        # our first sanity check.
+        if hasattr(other, 'shape'):
+            if self.shape != other.shape:
+                raise ShapeError("Matrix size mismatch: %s + %s" % (
+                    self.shape, other.shape))
+
+        # honest SymPy matrices defer to their class's routine
+        if getattr(other, 'is_Matrix', False):
+            # call the highest-priority class's _eval_add
+            a, b = self, other
+            if a.__class__ != classof(a, b):
+                b, a = a, b
+            return a._eval_add(b)
+        # Matrix-like objects can be passed to CommonMatrix routines directly.
+        if getattr(other, 'is_MatrixLike', False):
+            return MatrixArithmetic._eval_add(self, other)
+
+        raise TypeError('cannot add %s and %s' % (type(self), type(other)))
+
+    @call_highest_priority('__rtruediv__')
+    def __truediv__(self, other):
+        return self * (self.one / other)
+
+    @call_highest_priority('__rmatmul__')
+    def __matmul__(self, other):
+        other = _matrixify(other)
+        if not getattr(other, 'is_Matrix', False) and not getattr(other, 'is_MatrixLike', False):
+            return NotImplemented
+
+        return self.__mul__(other)
+
+    def __mod__(self, other):
+        return self.applyfunc(lambda x: x % other)
+
+    @call_highest_priority('__rmul__')
+    def __mul__(self, other):
+        """Return self*other where other is either a scalar or a matrix
+        of compatible dimensions.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> A = Matrix([[1, 2, 3], [4, 5, 6]])
+        >>> 2*A == A*2 == Matrix([[2, 4, 6], [8, 10, 12]])
+        True
+        >>> B = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+        >>> A*B
+        Matrix([
+        [30, 36, 42],
+        [66, 81, 96]])
+        >>> B*A
+        Traceback (most recent call last):
+        ...
+        ShapeError: Matrices size mismatch.
+        >>>
+
+        See Also
+        ========
+
+        matrix_multiply_elementwise
+        """
+
+        return self.multiply(other)
+
+    def multiply(self, other, dotprodsimp=None):
+        """Same as __mul__() but with optional simplification.
+
+        Parameters
+        ==========
+
+        dotprodsimp : bool, optional
+            Specifies whether intermediate term algebraic simplification is used
+            during matrix multiplications to control expression blowup and thus
+            speed up calculation. Default is off.
+        """
+
+        isimpbool = _get_intermediate_simp_bool(False, dotprodsimp)
+        other = _matrixify(other)
+        # matrix-like objects can have shapes.  This is
+        # our first sanity check. Double check other is not explicitly not a Matrix.
+        if (hasattr(other, 'shape') and len(other.shape) == 2 and
+            (getattr(other, 'is_Matrix', True) or
+             getattr(other, 'is_MatrixLike', True))):
+            if self.shape[1] != other.shape[0]:
+                raise ShapeError("Matrix size mismatch: %s * %s." % (
+                    self.shape, other.shape))
+
+        # honest SymPy matrices defer to their class's routine
+        if getattr(other, 'is_Matrix', False):
+            m = self._eval_matrix_mul(other)
+            if isimpbool:
+                return m._new(m.rows, m.cols, [_dotprodsimp(e) for e in m])
+            return m
+
+        # Matrix-like objects can be passed to CommonMatrix routines directly.
+        if getattr(other, 'is_MatrixLike', False):
+            return MatrixArithmetic._eval_matrix_mul(self, other)
+
+        # if 'other' is not iterable then scalar multiplication.
+        if not isinstance(other, Iterable):
+            try:
+                return self._eval_scalar_mul(other)
+            except TypeError:
+                pass
+
+        return NotImplemented
+
+    def multiply_elementwise(self, other):
+        """Return the Hadamard product (elementwise product) of A and B
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> A = Matrix([[0, 1, 2], [3, 4, 5]])
+        >>> B = Matrix([[1, 10, 100], [100, 10, 1]])
+        >>> A.multiply_elementwise(B)
+        Matrix([
+        [  0, 10, 200],
+        [300, 40,   5]])
+
+        See Also
+        ========
+
+        sympy.matrices.matrixbase.MatrixBase.cross
+        sympy.matrices.matrixbase.MatrixBase.dot
+        multiply
+        """
+        if self.shape != other.shape:
+            raise ShapeError("Matrix shapes must agree {} != {}".format(self.shape, other.shape))
+
+        return self._eval_matrix_mul_elementwise(other)
+
+    def __neg__(self):
+        return self._eval_scalar_mul(-1)
+
+    @call_highest_priority('__rpow__')
+    def __pow__(self, exp):
+        """Return self**exp a scalar or symbol."""
+
+        return self.pow(exp)
+
+
+    def pow(self, exp, method=None):
+        r"""Return self**exp a scalar or symbol.
+
+        Parameters
+        ==========
+
+        method : multiply, mulsimp, jordan, cayley
+            If multiply then it returns exponentiation using recursion.
+            If jordan then Jordan form exponentiation will be used.
+            If cayley then the exponentiation is done using Cayley-Hamilton
+            theorem.
+            If mulsimp then the exponentiation is done using recursion
+            with dotprodsimp. This specifies whether intermediate term
+            algebraic simplification is used during naive matrix power to
+            control expression blowup and thus speed up calculation.
+            If None, then it heuristically decides which method to use.
+
+        """
+
+        if method is not None and method not in ['multiply', 'mulsimp', 'jordan', 'cayley']:
+            raise TypeError('No such method')
+        if self.rows != self.cols:
+            raise NonSquareMatrixError()
+        a = self
+        jordan_pow = getattr(a, '_matrix_pow_by_jordan_blocks', None)
+        exp = sympify(exp)
+
+        if exp.is_zero:
+            return a._new(a.rows, a.cols, lambda i, j: int(i == j))
+        if exp == 1:
+            return a
+
+        diagonal = getattr(a, 'is_diagonal', None)
+        if diagonal is not None and diagonal():
+            return a._new(a.rows, a.cols, lambda i, j: a[i,j]**exp if i == j else 0)
+
+        if exp.is_Number and exp % 1 == 0:
+            if a.rows == 1:
+                return a._new([[a[0]**exp]])
+            if exp < 0:
+                exp = -exp
+                a = a.inv()
+        # When certain conditions are met,
+        # Jordan block algorithm is faster than
+        # computation by recursion.
+        if method == 'jordan':
+            try:
+                return jordan_pow(exp)
+            except MatrixError:
+                if method == 'jordan':
+                    raise
+
+        elif method == 'cayley':
+            if not exp.is_Number or exp % 1 != 0:
+                raise ValueError("cayley method is only valid for integer powers")
+            return a._eval_pow_by_cayley(exp)
+
+        elif method == "mulsimp":
+            if not exp.is_Number or exp % 1 != 0:
+                raise ValueError("mulsimp method is only valid for integer powers")
+            return a._eval_pow_by_recursion_dotprodsimp(exp)
+
+        elif method == "multiply":
+            if not exp.is_Number or exp % 1 != 0:
+                raise ValueError("multiply method is only valid for integer powers")
+            return a._eval_pow_by_recursion(exp)
+
+        elif method is None and exp.is_Number and exp % 1 == 0:
+            if exp.is_Float:
+                exp = Integer(exp)
+            # Decide heuristically which method to apply
+            if a.rows == 2 and exp > 100000:
+                return jordan_pow(exp)
+            elif _get_intermediate_simp_bool(True, None):
+                return a._eval_pow_by_recursion_dotprodsimp(exp)
+            elif exp > 10000:
+                return a._eval_pow_by_cayley(exp)
+            else:
+                return a._eval_pow_by_recursion(exp)
+
+        if jordan_pow:
+            try:
+                return jordan_pow(exp)
+            except NonInvertibleMatrixError:
+                # Raised by jordan_pow on zero determinant matrix unless exp is
+                # definitely known to be a non-negative integer.
+                # Here we raise if n is definitely not a non-negative integer
+                # but otherwise we can leave this as an unevaluated MatPow.
+                if exp.is_integer is False or exp.is_nonnegative is False:
+                    raise
+
+        from sympy.matrices.expressions import MatPow
+        return MatPow(a, exp)
+
+    @call_highest_priority('__add__')
+    def __radd__(self, other):
+        return self + other
+
+    @call_highest_priority('__matmul__')
+    def __rmatmul__(self, other):
+        other = _matrixify(other)
+        if not getattr(other, 'is_Matrix', False) and not getattr(other, 'is_MatrixLike', False):
+            return NotImplemented
+
+        return self.__rmul__(other)
+
+    @call_highest_priority('__mul__')
+    def __rmul__(self, other):
+        return self.rmultiply(other)
+
+    def rmultiply(self, other, dotprodsimp=None):
+        """Same as __rmul__() but with optional simplification.
+
+        Parameters
+        ==========
+
+        dotprodsimp : bool, optional
+            Specifies whether intermediate term algebraic simplification is used
+            during matrix multiplications to control expression blowup and thus
+            speed up calculation. Default is off.
+        """
+        isimpbool = _get_intermediate_simp_bool(False, dotprodsimp)
+        other = _matrixify(other)
+        # matrix-like objects can have shapes.  This is
+        # our first sanity check. Double check other is not explicitly not a Matrix.
+        if (hasattr(other, 'shape') and len(other.shape) == 2 and
+            (getattr(other, 'is_Matrix', True) or
+             getattr(other, 'is_MatrixLike', True))):
+            if self.shape[0] != other.shape[1]:
+                raise ShapeError("Matrix size mismatch.")
+
+        # honest SymPy matrices defer to their class's routine
+        if getattr(other, 'is_Matrix', False):
+            m = self._eval_matrix_rmul(other)
+            if isimpbool:
+                return m._new(m.rows, m.cols, [_dotprodsimp(e) for e in m])
+            return m
+        # Matrix-like objects can be passed to CommonMatrix routines directly.
+        if getattr(other, 'is_MatrixLike', False):
+            return MatrixArithmetic._eval_matrix_rmul(self, other)
+
+        # if 'other' is not iterable then scalar multiplication.
+        if not isinstance(other, Iterable):
+            try:
+                return self._eval_scalar_rmul(other)
+            except TypeError:
+                pass
+
+        return NotImplemented
+
+    @call_highest_priority('__sub__')
+    def __rsub__(self, a):
+        return (-self) + a
+
+    @call_highest_priority('__rsub__')
+    def __sub__(self, a):
+        return self + (-a)
+
+
+class MatrixCommon(MatrixArithmetic, MatrixOperations, MatrixProperties,
+                  MatrixSpecial, MatrixShaping):
+    """All common matrix operations including basic arithmetic, shaping,
+    and special matrices like `zeros`, and `eye`."""
+    _diff_wrt = True  # type: bool
+
+
+class _MinimalMatrix:
+    """Class providing the minimum functionality
+    for a matrix-like object and implementing every method
+    required for a `MatrixRequired`.  This class does not have everything
+    needed to become a full-fledged SymPy object, but it will satisfy the
+    requirements of anything inheriting from `MatrixRequired`.  If you wish
+    to make a specialized matrix type, make sure to implement these
+    methods and properties with the exception of `__init__` and `__repr__`
+    which are included for convenience."""
+
+    is_MatrixLike = True
+    _sympify = staticmethod(sympify)
+    _class_priority = 3
+    zero = S.Zero
+    one = S.One
+
+    is_Matrix = True
+    is_MatrixExpr = False
+
+    @classmethod
+    def _new(cls, *args, **kwargs):
+        return cls(*args, **kwargs)
+
+    def __init__(self, rows, cols=None, mat=None, copy=False):
+        if isfunction(mat):
+            # if we passed in a function, use that to populate the indices
+            mat = [mat(i, j) for i in range(rows) for j in range(cols)]
+        if cols is None and mat is None:
+            mat = rows
+        rows, cols = getattr(mat, 'shape', (rows, cols))
+        try:
+            # if we passed in a list of lists, flatten it and set the size
+            if cols is None and mat is None:
+                mat = rows
+            cols = len(mat[0])
+            rows = len(mat)
+            mat = [x for l in mat for x in l]
+        except (IndexError, TypeError):
+            pass
+        self.mat = tuple(self._sympify(x) for x in mat)
+        self.rows, self.cols = rows, cols
+        if self.rows is None or self.cols is None:
+            raise NotImplementedError("Cannot initialize matrix with given parameters")
+
+    def __getitem__(self, key):
+        def _normalize_slices(row_slice, col_slice):
+            """Ensure that row_slice and col_slice do not have
+            `None` in their arguments.  Any integers are converted
+            to slices of length 1"""
+            if not isinstance(row_slice, slice):
+                row_slice = slice(row_slice, row_slice + 1, None)
+            row_slice = slice(*row_slice.indices(self.rows))
+
+            if not isinstance(col_slice, slice):
+                col_slice = slice(col_slice, col_slice + 1, None)
+            col_slice = slice(*col_slice.indices(self.cols))
+
+            return (row_slice, col_slice)
+
+        def _coord_to_index(i, j):
+            """Return the index in _mat corresponding
+            to the (i,j) position in the matrix. """
+            return i * self.cols + j
+
+        if isinstance(key, tuple):
+            i, j = key
+            if isinstance(i, slice) or isinstance(j, slice):
+                # if the coordinates are not slices, make them so
+                # and expand the slices so they don't contain `None`
+                i, j = _normalize_slices(i, j)
+
+                rowsList, colsList = list(range(self.rows))[i], \
+                                     list(range(self.cols))[j]
+                indices = (i * self.cols + j for i in rowsList for j in
+                           colsList)
+                return self._new(len(rowsList), len(colsList),
+                                 [self.mat[i] for i in indices])
+
+            # if the key is a tuple of ints, change
+            # it to an array index
+            key = _coord_to_index(i, j)
+        return self.mat[key]
+
+    def __eq__(self, other):
+        try:
+            classof(self, other)
+        except TypeError:
+            return False
+        return (
+            self.shape == other.shape and list(self) == list(other))
+
+    def __len__(self):
+        return self.rows*self.cols
+
+    def __repr__(self):
+        return "_MinimalMatrix({}, {}, {})".format(self.rows, self.cols,
+                                                   self.mat)
+
+    @property
+    def shape(self):
+        return (self.rows, self.cols)
+
+
+class _CastableMatrix: # this is needed here ONLY FOR TESTS.
+    def as_mutable(self):
+        return self
+
+    def as_immutable(self):
+        return self
+
+
+class _MatrixWrapper:
+    """Wrapper class providing the minimum functionality for a matrix-like
+    object: .rows, .cols, .shape, indexability, and iterability. CommonMatrix
+    math operations should work on matrix-like objects. This one is intended for
+    matrix-like objects which use the same indexing format as SymPy with respect
+    to returning matrix elements instead of rows for non-tuple indexes.
+    """
+
+    is_Matrix     = False # needs to be here because of __getattr__
+    is_MatrixLike = True
+
+    def __init__(self, mat, shape):
+        self.mat = mat
+        self.shape = shape
+        self.rows, self.cols = shape
+
+    def __getitem__(self, key):
+        if isinstance(key, tuple):
+            return sympify(self.mat.__getitem__(key))
+
+        return sympify(self.mat.__getitem__((key // self.rows, key % self.cols)))
+
+    def __iter__(self): # supports numpy.matrix and numpy.array
+        mat = self.mat
+        cols = self.cols
+
+        return iter(sympify(mat[r, c]) for r in range(self.rows) for c in range(cols))
+
+
+def _matrixify(mat):
+    """If `mat` is a Matrix or is matrix-like,
+    return a Matrix or MatrixWrapper object.  Otherwise
+    `mat` is passed through without modification."""
+
+    if getattr(mat, 'is_Matrix', False) or getattr(mat, 'is_MatrixLike', False):
+        return mat
+
+    if not(getattr(mat, 'is_Matrix', True) or getattr(mat, 'is_MatrixLike', True)):
+        return mat
+
+    shape = None
+
+    if hasattr(mat, 'shape'): # numpy, scipy.sparse
+        if len(mat.shape) == 2:
+            shape = mat.shape
+    elif hasattr(mat, 'rows') and hasattr(mat, 'cols'): # mpmath
+        shape = (mat.rows, mat.cols)
+
+    if shape:
+        return _MatrixWrapper(mat, shape)
+
+    return mat
+
+
+def a2idx(j, n=None):
+    """Return integer after making positive and validating against n."""
+    if not isinstance(j, int):
+        jindex = getattr(j, '__index__', None)
+        if jindex is not None:
+            j = jindex()
+        else:
+            raise IndexError("Invalid index a[%r]" % (j,))
+    if n is not None:
+        if j < 0:
+            j += n
+        if not (j >= 0 and j < n):
+            raise IndexError("Index out of range: a[%s]" % (j,))
+    return int(j)
+
+
+def classof(A, B):
+    """
+    Get the type of the result when combining matrices of different types.
+
+    Currently the strategy is that immutability is contagious.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix, ImmutableMatrix
+    >>> from sympy.matrices.matrixbase import classof
+    >>> M = Matrix([[1, 2], [3, 4]]) # a Mutable Matrix
+    >>> IM = ImmutableMatrix([[1, 2], [3, 4]])
+    >>> classof(M, IM)
+    <class 'sympy.matrices.immutable.ImmutableDenseMatrix'>
+    """
+    priority_A = getattr(A, '_class_priority', None)
+    priority_B = getattr(B, '_class_priority', None)
+    if None not in (priority_A, priority_B):
+        if A._class_priority > B._class_priority:
+            return A.__class__
+        else:
+            return B.__class__
+
+    try:
+        import numpy
+    except ImportError:
+        pass
+    else:
+        if isinstance(A, numpy.ndarray):
+            return B.__class__
+        if isinstance(B, numpy.ndarray):
+            return A.__class__
+
+    raise TypeError("Incompatible classes %s, %s" % (A.__class__, B.__class__))

.venv/lib/python3.11/site-packages/sympy/matrices/determinant.py

@@ -0,0 +1,1021 @@
+from types import FunctionType
+
+from sympy.core.cache import cacheit
+from sympy.core.numbers import Float, Integer
+from sympy.core.singleton import S
+from sympy.core.symbol import uniquely_named_symbol
+from sympy.core.mul import Mul
+from sympy.polys import PurePoly, cancel
+from sympy.functions.combinatorial.numbers import nC
+from sympy.polys.matrices.domainmatrix import DomainMatrix
+from sympy.polys.matrices.ddm import DDM
+
+from .exceptions import NonSquareMatrixError
+from .utilities import (
+    _get_intermediate_simp, _get_intermediate_simp_bool,
+    _iszero, _is_zero_after_expand_mul, _dotprodsimp, _simplify)
+
+
+def _find_reasonable_pivot(col, iszerofunc=_iszero, simpfunc=_simplify):
+    """ Find the lowest index of an item in ``col`` that is
+    suitable for a pivot.  If ``col`` consists only of
+    Floats, the pivot with the largest norm is returned.
+    Otherwise, the first element where ``iszerofunc`` returns
+    False is used.  If ``iszerofunc`` does not return false,
+    items are simplified and retested until a suitable
+    pivot is found.
+
+    Returns a 4-tuple
+        (pivot_offset, pivot_val, assumed_nonzero, newly_determined)
+    where pivot_offset is the index of the pivot, pivot_val is
+    the (possibly simplified) value of the pivot, assumed_nonzero
+    is True if an assumption that the pivot was non-zero
+    was made without being proved, and newly_determined are
+    elements that were simplified during the process of pivot
+    finding."""
+
+    newly_determined = []
+    col = list(col)
+    # a column that contains a mix of floats and integers
+    # but at least one float is considered a numerical
+    # column, and so we do partial pivoting
+    if all(isinstance(x, (Float, Integer)) for x in col) and any(
+            isinstance(x, Float) for x in col):
+        col_abs = [abs(x) for x in col]
+        max_value = max(col_abs)
+        if iszerofunc(max_value):
+            # just because iszerofunc returned True, doesn't
+            # mean the value is numerically zero.  Make sure
+            # to replace all entries with numerical zeros
+            if max_value != 0:
+                newly_determined = [(i, 0) for i, x in enumerate(col) if x != 0]
+            return (None, None, False, newly_determined)
+        index = col_abs.index(max_value)
+        return (index, col[index], False, newly_determined)
+
+    # PASS 1 (iszerofunc directly)
+    possible_zeros = []
+    for i, x in enumerate(col):
+        is_zero = iszerofunc(x)
+        # is someone wrote a custom iszerofunc, it may return
+        # BooleanFalse or BooleanTrue instead of True or False,
+        # so use == for comparison instead of `is`
+        if is_zero == False:
+            # we found something that is definitely not zero
+            return (i, x, False, newly_determined)
+        possible_zeros.append(is_zero)
+
+    # by this point, we've found no certain non-zeros
+    if all(possible_zeros):
+        # if everything is definitely zero, we have
+        # no pivot
+        return (None, None, False, newly_determined)
+
+    # PASS 2 (iszerofunc after simplify)
+    # we haven't found any for-sure non-zeros, so
+    # go through the elements iszerofunc couldn't
+    # make a determination about and opportunistically
+    # simplify to see if we find something
+    for i, x in enumerate(col):
+        if possible_zeros[i] is not None:
+            continue
+        simped = simpfunc(x)
+        is_zero = iszerofunc(simped)
+        if is_zero in (True, False):
+            newly_determined.append((i, simped))
+        if is_zero == False:
+            return (i, simped, False, newly_determined)
+        possible_zeros[i] = is_zero
+
+    # after simplifying, some things that were recognized
+    # as zeros might be zeros
+    if all(possible_zeros):
+        # if everything is definitely zero, we have
+        # no pivot
+        return (None, None, False, newly_determined)
+
+    # PASS 3 (.equals(0))
+    # some expressions fail to simplify to zero, but
+    # ``.equals(0)`` evaluates to True.  As a last-ditch
+    # attempt, apply ``.equals`` to these expressions
+    for i, x in enumerate(col):
+        if possible_zeros[i] is not None:
+            continue
+        if x.equals(S.Zero):
+            # ``.iszero`` may return False with
+            # an implicit assumption (e.g., ``x.equals(0)``
+            # when ``x`` is a symbol), so only treat it
+            # as proved when ``.equals(0)`` returns True
+            possible_zeros[i] = True
+            newly_determined.append((i, S.Zero))
+
+    if all(possible_zeros):
+        return (None, None, False, newly_determined)
+
+    # at this point there is nothing that could definitely
+    # be a pivot.  To maintain compatibility with existing
+    # behavior, we'll assume that an illdetermined thing is
+    # non-zero.  We should probably raise a warning in this case
+    i = possible_zeros.index(None)
+    return (i, col[i], True, newly_determined)
+
+
+def _find_reasonable_pivot_naive(col, iszerofunc=_iszero, simpfunc=None):
+    """
+    Helper that computes the pivot value and location from a
+    sequence of contiguous matrix column elements. As a side effect
+    of the pivot search, this function may simplify some of the elements
+    of the input column. A list of these simplified entries and their
+    indices are also returned.
+    This function mimics the behavior of _find_reasonable_pivot(),
+    but does less work trying to determine if an indeterminate candidate
+    pivot simplifies to zero. This more naive approach can be much faster,
+    with the trade-off that it may erroneously return a pivot that is zero.
+
+    ``col`` is a sequence of contiguous column entries to be searched for
+    a suitable pivot.
+    ``iszerofunc`` is a callable that returns a Boolean that indicates
+    if its input is zero, or None if no such determination can be made.
+    ``simpfunc`` is a callable that simplifies its input. It must return
+    its input if it does not simplify its input. Passing in
+    ``simpfunc=None`` indicates that the pivot search should not attempt
+    to simplify any candidate pivots.
+
+    Returns a 4-tuple:
+    (pivot_offset, pivot_val, assumed_nonzero, newly_determined)
+    ``pivot_offset`` is the sequence index of the pivot.
+    ``pivot_val`` is the value of the pivot.
+    pivot_val and col[pivot_index] are equivalent, but will be different
+    when col[pivot_index] was simplified during the pivot search.
+    ``assumed_nonzero`` is a boolean indicating if the pivot cannot be
+    guaranteed to be zero. If assumed_nonzero is true, then the pivot
+    may or may not be non-zero. If assumed_nonzero is false, then
+    the pivot is non-zero.
+    ``newly_determined`` is a list of index-value pairs of pivot candidates
+    that were simplified during the pivot search.
+    """
+
+    # indeterminates holds the index-value pairs of each pivot candidate
+    # that is neither zero or non-zero, as determined by iszerofunc().
+    # If iszerofunc() indicates that a candidate pivot is guaranteed
+    # non-zero, or that every candidate pivot is zero then the contents
+    # of indeterminates are unused.
+    # Otherwise, the only viable candidate pivots are symbolic.
+    # In this case, indeterminates will have at least one entry,
+    # and all but the first entry are ignored when simpfunc is None.
+    indeterminates = []
+    for i, col_val in enumerate(col):
+        col_val_is_zero = iszerofunc(col_val)
+        if col_val_is_zero == False:
+            # This pivot candidate is non-zero.
+            return i, col_val, False, []
+        elif col_val_is_zero is None:
+            # The candidate pivot's comparison with zero
+            # is indeterminate.
+            indeterminates.append((i, col_val))
+
+    if len(indeterminates) == 0:
+        # All candidate pivots are guaranteed to be zero, i.e. there is
+        # no pivot.
+        return None, None, False, []
+
+    if simpfunc is None:
+        # Caller did not pass in a simplification function that might
+        # determine if an indeterminate pivot candidate is guaranteed
+        # to be nonzero, so assume the first indeterminate candidate
+        # is non-zero.
+        return indeterminates[0][0], indeterminates[0][1], True, []
+
+    # newly_determined holds index-value pairs of candidate pivots
+    # that were simplified during the search for a non-zero pivot.
+    newly_determined = []
+    for i, col_val in indeterminates:
+        tmp_col_val = simpfunc(col_val)
+        if id(col_val) != id(tmp_col_val):
+            # simpfunc() simplified this candidate pivot.
+            newly_determined.append((i, tmp_col_val))
+            if iszerofunc(tmp_col_val) == False:
+                # Candidate pivot simplified to a guaranteed non-zero value.
+                return i, tmp_col_val, False, newly_determined
+
+    return indeterminates[0][0], indeterminates[0][1], True, newly_determined
+
+
+# This functions is a candidate for caching if it gets implemented for matrices.
+def _berkowitz_toeplitz_matrix(M):
+    """Return (A,T) where T the Toeplitz matrix used in the Berkowitz algorithm
+    corresponding to ``M`` and A is the first principal submatrix.
+    """
+
+    # the 0 x 0 case is trivial
+    if M.rows == 0 and M.cols == 0:
+        return M._new(1,1, [M.one])
+
+    #
+    # Partition M = [ a_11  R ]
+    #                  [ C     A ]
+    #
+
+    a, R = M[0,0],   M[0, 1:]
+    C, A = M[1:, 0], M[1:,1:]
+
+    #
+    # The Toeplitz matrix looks like
+    #
+    #  [ 1                                     ]
+    #  [ -a         1                          ]
+    #  [ -RC       -a        1                 ]
+    #  [ -RAC     -RC       -a       1         ]
+    #  [ -RA**2C -RAC      -RC      -a       1 ]
+    #  etc.
+
+    # Compute the diagonal entries.
+    # Because multiplying matrix times vector is so much
+    # more efficient than matrix times matrix, recursively
+    # compute -R * A**n * C.
+    diags = [C]
+    for i in range(M.rows - 2):
+        diags.append(A.multiply(diags[i], dotprodsimp=None))
+    diags = [(-R).multiply(d, dotprodsimp=None)[0, 0] for d in diags]
+    diags = [M.one, -a] + diags
+
+    def entry(i,j):
+        if j > i:
+            return M.zero
+        return diags[i - j]
+
+    toeplitz = M._new(M.cols + 1, M.rows, entry)
+    return (A, toeplitz)
+
+
+# This functions is a candidate for caching if it gets implemented for matrices.
+def _berkowitz_vector(M):
+    """ Run the Berkowitz algorithm and return a vector whose entries
+        are the coefficients of the characteristic polynomial of ``M``.
+
+        Given N x N matrix, efficiently compute
+        coefficients of characteristic polynomials of ``M``
+        without division in the ground domain.
+
+        This method is particularly useful for computing determinant,
+        principal minors and characteristic polynomial when ``M``
+        has complicated coefficients e.g. polynomials. Semi-direct
+        usage of this algorithm is also important in computing
+        efficiently sub-resultant PRS.
+
+        Assuming that M is a square matrix of dimension N x N and
+        I is N x N identity matrix, then the Berkowitz vector is
+        an N x 1 vector whose entries are coefficients of the
+        polynomial
+
+                        charpoly(M) = det(t*I - M)
+
+        As a consequence, all polynomials generated by Berkowitz
+        algorithm are monic.
+
+        For more information on the implemented algorithm refer to:
+
+        [1] S.J. Berkowitz, On computing the determinant in small
+            parallel time using a small number of processors, ACM,
+            Information Processing Letters 18, 1984, pp. 147-150
+
+        [2] M. Keber, Division-Free computation of sub-resultants
+            using Bezout matrices, Tech. Report MPI-I-2006-1-006,
+            Saarbrucken, 2006
+    """
+
+    # handle the trivial cases
+    if M.rows == 0 and M.cols == 0:
+        return M._new(1, 1, [M.one])
+    elif M.rows == 1 and M.cols == 1:
+        return M._new(2, 1, [M.one, -M[0,0]])
+
+    submat, toeplitz = _berkowitz_toeplitz_matrix(M)
+
+    return toeplitz.multiply(_berkowitz_vector(submat), dotprodsimp=None)
+
+
+def _adjugate(M, method="berkowitz"):
+    """Returns the adjugate, or classical adjoint, of
+    a matrix.  That is, the transpose of the matrix of cofactors.
+
+    https://en.wikipedia.org/wiki/Adjugate
+
+    Parameters
+    ==========
+
+    method : string, optional
+        Method to use to find the cofactors, can be "bareiss", "berkowitz",
+        "bird", "laplace" or "lu".
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> M = Matrix([[1, 2], [3, 4]])
+    >>> M.adjugate()
+    Matrix([
+    [ 4, -2],
+    [-3,  1]])
+
+    See Also
+    ========
+
+    cofactor_matrix
+    sympy.matrices.matrixbase.MatrixBase.transpose
+    """
+
+    return M.cofactor_matrix(method=method).transpose()
+
+
+# This functions is a candidate for caching if it gets implemented for matrices.
+def _charpoly(M, x='lambda', simplify=_simplify):
+    """Computes characteristic polynomial det(x*I - M) where I is
+    the identity matrix.
+
+    A PurePoly is returned, so using different variables for ``x`` does
+    not affect the comparison or the polynomials:
+
+    Parameters
+    ==========
+
+    x : string, optional
+        Name for the "lambda" variable, defaults to "lambda".
+
+    simplify : function, optional
+        Simplification function to use on the characteristic polynomial
+        calculated. Defaults to ``simplify``.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> from sympy.abc import x, y
+    >>> M = Matrix([[1, 3], [2, 0]])
+    >>> M.charpoly()
+    PurePoly(lambda**2 - lambda - 6, lambda, domain='ZZ')
+    >>> M.charpoly(x) == M.charpoly(y)
+    True
+    >>> M.charpoly(x) == M.charpoly(y)
+    True
+
+    Specifying ``x`` is optional; a symbol named ``lambda`` is used by
+    default (which looks good when pretty-printed in unicode):
+
+    >>> M.charpoly().as_expr()
+    lambda**2 - lambda - 6
+
+    And if ``x`` clashes with an existing symbol, underscores will
+    be prepended to the name to make it unique:
+
+    >>> M = Matrix([[1, 2], [x, 0]])
+    >>> M.charpoly(x).as_expr()
+    _x**2 - _x - 2*x
+
+    Whether you pass a symbol or not, the generator can be obtained
+    with the gen attribute since it may not be the same as the symbol
+    that was passed:
+
+    >>> M.charpoly(x).gen
+    _x
+    >>> M.charpoly(x).gen == x
+    False
+
+    Notes
+    =====
+
+    The Samuelson-Berkowitz algorithm is used to compute
+    the characteristic polynomial efficiently and without any
+    division operations.  Thus the characteristic polynomial over any
+    commutative ring without zero divisors can be computed.
+
+    If the determinant det(x*I - M) can be found out easily as
+    in the case of an upper or a lower triangular matrix, then
+    instead of Samuelson-Berkowitz algorithm, eigenvalues are computed
+    and the characteristic polynomial with their help.
+
+    See Also
+    ========
+
+    det
+    """
+
+    if not M.is_square:
+        raise NonSquareMatrixError()
+
+    # Use DomainMatrix. We are already going to convert this to a Poly so there
+    # is no need to worry about expanding powers etc. Also since this algorithm
+    # does not require division or zero detection it is fine to use EX.
+    #
+    # M.to_DM() will fall back on EXRAW rather than EX. EXRAW is a lot faster
+    # for elementary arithmetic because it does not call cancel for each
+    # operation but it generates large unsimplified results that are slow in
+    # the subsequent call to simplify. Using EX instead is faster overall
+    # but at least in some cases EXRAW+simplify gives a simpler result so we
+    # preserve that existing behaviour of charpoly for now...
+    dM = M.to_DM()
+
+    K = dM.domain
+
+    cp = dM.charpoly()
+
+    x = uniquely_named_symbol(x, [M], modify=lambda s: '_' + s)
+
+    if K.is_EXRAW or simplify is not _simplify:
+        # XXX: Converting back to Expr is expensive. We only do it if the
+        # caller supplied a custom simplify function for backwards
+        # compatibility or otherwise if the domain was EX. For any other domain
+        # there should be no benefit in simplifying at this stage because Poly
+        # will put everything into canonical form anyway.
+        berk_vector = [K.to_sympy(c) for c in cp]
+        berk_vector = [simplify(a) for a in berk_vector]
+        p = PurePoly(berk_vector, x)
+
+    else:
+        # Convert from the list of domain elements directly to Poly.
+        p = PurePoly(cp, x, domain=K)
+
+    return p
+
+
+def _cofactor(M, i, j, method="berkowitz"):
+    """Calculate the cofactor of an element.
+
+    Parameters
+    ==========
+
+    method : string, optional
+        Method to use to find the cofactors, can be "bareiss", "berkowitz",
+        "bird", "laplace" or "lu".
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> M = Matrix([[1, 2], [3, 4]])
+    >>> M.cofactor(0, 1)
+    -3
+
+    See Also
+    ========
+
+    cofactor_matrix
+    minor
+    minor_submatrix
+    """
+
+    if not M.is_square or M.rows < 1:
+        raise NonSquareMatrixError()
+
+    return S.NegativeOne**((i + j) % 2) * M.minor(i, j, method)
+
+
+def _cofactor_matrix(M, method="berkowitz"):
+    """Return a matrix containing the cofactor of each element.
+
+    Parameters
+    ==========
+
+    method : string, optional
+        Method to use to find the cofactors, can be "bareiss", "berkowitz",
+        "bird", "laplace" or "lu".
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> M = Matrix([[1, 2], [3, 4]])
+    >>> M.cofactor_matrix()
+    Matrix([
+    [ 4, -3],
+    [-2,  1]])
+
+    See Also
+    ========
+
+    cofactor
+    minor
+    minor_submatrix
+    """
+
+    if not M.is_square:
+        raise NonSquareMatrixError()
+
+    return M._new(M.rows, M.cols,
+            lambda i, j: M.cofactor(i, j, method))
+
+def _per(M):
+    """Returns the permanent of a matrix. Unlike determinant,
+    permanent is defined for both square and non-square matrices.
+
+    For an m x n matrix, with m less than or equal to n,
+    it is given as the sum over the permutations s of size
+    less than or equal to m on [1, 2, . . . n] of the product
+    from i = 1 to m of M[i, s[i]]. Taking the transpose will
+    not affect the value of the permanent.
+
+    In the case of a square matrix, this is the same as the permutation
+    definition of the determinant, but it does not take the sign of the
+    permutation into account. Computing the permanent with this definition
+    is quite inefficient, so here the Ryser formula is used.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> M = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+    >>> M.per()
+    450
+    >>> M = Matrix([1, 5, 7])
+    >>> M.per()
+    13
+
+    References
+    ==========
+
+    .. [1] Prof. Frank Ben's notes: https://math.berkeley.edu/~bernd/ban275.pdf
+    .. [2] Wikipedia article on Permanent: https://en.wikipedia.org/wiki/Permanent_%28mathematics%29
+    .. [3] https://reference.wolfram.com/language/ref/Permanent.html
+    .. [4] Permanent of a rectangular matrix : https://arxiv.org/pdf/0904.3251.pdf
+    """
+    import itertools
+
+    m, n = M.shape
+    if m > n:
+        M = M.T
+        m, n = n, m
+    s = list(range(n))
+
+    subsets = []
+    for i in range(1, m + 1):
+        subsets += list(map(list, itertools.combinations(s, i)))
+
+    perm = 0
+    for subset in subsets:
+        prod = 1
+        sub_len = len(subset)
+        for i in range(m):
+             prod *= sum(M[i, j] for j in subset)
+        perm += prod * S.NegativeOne**sub_len * nC(n - sub_len, m - sub_len)
+    perm *= S.NegativeOne**m
+    return perm.simplify()
+
+def _det_DOM(M):
+    DOM = DomainMatrix.from_Matrix(M, field=True, extension=True)
+    K = DOM.domain
+    return K.to_sympy(DOM.det())
+
+# This functions is a candidate for caching if it gets implemented for matrices.
+def _det(M, method="bareiss", iszerofunc=None):
+    """Computes the determinant of a matrix if ``M`` is a concrete matrix object
+    otherwise return an expressions ``Determinant(M)`` if ``M`` is a
+    ``MatrixSymbol`` or other expression.
+
+    Parameters
+    ==========
+
+    method : string, optional
+        Specifies the algorithm used for computing the matrix determinant.
+
+        If the matrix is at most 3x3, a hard-coded formula is used and the
+        specified method is ignored. Otherwise, it defaults to
+        ``'bareiss'``.
+
+        Also, if the matrix is an upper or a lower triangular matrix, determinant
+        is computed by simple multiplication of diagonal elements, and the
+        specified method is ignored.
+
+        If it is set to ``'domain-ge'``, then Gaussian elimination method will
+        be used via using DomainMatrix.
+
+        If it is set to ``'bareiss'``, Bareiss' fraction-free algorithm will
+        be used.
+
+        If it is set to ``'berkowitz'``, Berkowitz' algorithm will be used.
+
+        If it is set to ``'bird'``, Bird's algorithm will be used [1]_.
+
+        If it is set to ``'laplace'``, Laplace's algorithm will be used.
+
+        Otherwise, if it is set to ``'lu'``, LU decomposition will be used.
+
+        .. note::
+            For backward compatibility, legacy keys like "bareis" and
+            "det_lu" can still be used to indicate the corresponding
+            methods.
+            And the keys are also case-insensitive for now. However, it is
+            suggested to use the precise keys for specifying the method.
+
+    iszerofunc : FunctionType or None, optional
+        If it is set to ``None``, it will be defaulted to ``_iszero`` if the
+        method is set to ``'bareiss'``, and ``_is_zero_after_expand_mul`` if
+        the method is set to ``'lu'``.
+
+        It can also accept any user-specified zero testing function, if it
+        is formatted as a function which accepts a single symbolic argument
+        and returns ``True`` if it is tested as zero and ``False`` if it
+        tested as non-zero, and also ``None`` if it is undecidable.
+
+    Returns
+    =======
+
+    det : Basic
+        Result of determinant.
+
+    Raises
+    ======
+
+    ValueError
+        If unrecognized keys are given for ``method`` or ``iszerofunc``.
+
+    NonSquareMatrixError
+        If attempted to calculate determinant from a non-square matrix.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix, eye, det
+    >>> I3 = eye(3)
+    >>> det(I3)
+    1
+    >>> M = Matrix([[1, 2], [3, 4]])
+    >>> det(M)
+    -2
+    >>> det(M) == M.det()
+    True
+    >>> M.det(method="domain-ge")
+    -2
+
+    References
+    ==========
+
+    .. [1] Bird, R. S. (2011). A simple division-free algorithm for computing
+           determinants. Inf. Process. Lett., 111(21), 1072-1074. doi:
+           10.1016/j.ipl.2011.08.006
+    """
+
+    # sanitize `method`
+    method = method.lower()
+
+    if method == "bareis":
+        method = "bareiss"
+    elif method == "det_lu":
+        method = "lu"
+
+    if method not in ("bareiss", "berkowitz", "lu", "domain-ge", "bird",
+                      "laplace"):
+        raise ValueError("Determinant method '%s' unrecognized" % method)
+
+    if iszerofunc is None:
+        if method == "bareiss":
+            iszerofunc = _is_zero_after_expand_mul
+        elif method == "lu":
+            iszerofunc = _iszero
+
+    elif not isinstance(iszerofunc, FunctionType):
+        raise ValueError("Zero testing method '%s' unrecognized" % iszerofunc)
+
+    n = M.rows
+
+    if n == M.cols: # square check is done in individual method functions
+        if n == 0:
+            return M.one
+        elif n == 1:
+            return M[0, 0]
+        elif n == 2:
+            m = M[0, 0] * M[1, 1] - M[0, 1] * M[1, 0]
+            return _get_intermediate_simp(_dotprodsimp)(m)
+        elif n == 3:
+            m =  (M[0, 0] * M[1, 1] * M[2, 2]
+                + M[0, 1] * M[1, 2] * M[2, 0]
+                + M[0, 2] * M[1, 0] * M[2, 1]
+                - M[0, 2] * M[1, 1] * M[2, 0]
+                - M[0, 0] * M[1, 2] * M[2, 1]
+                - M[0, 1] * M[1, 0] * M[2, 2])
+            return _get_intermediate_simp(_dotprodsimp)(m)
+
+    dets = []
+    for b in M.strongly_connected_components():
+        if method == "domain-ge": # uses DomainMatrix to evaluate determinant
+            det = _det_DOM(M[b, b])
+        elif method == "bareiss":
+            det = M[b, b]._eval_det_bareiss(iszerofunc=iszerofunc)
+        elif method == "berkowitz":
+            det = M[b, b]._eval_det_berkowitz()
+        elif method == "lu":
+            det = M[b, b]._eval_det_lu(iszerofunc=iszerofunc)
+        elif method == "bird":
+            det = M[b, b]._eval_det_bird()
+        elif method == "laplace":
+            det = M[b, b]._eval_det_laplace()
+        dets.append(det)
+    return Mul(*dets)
+
+
+# This functions is a candidate for caching if it gets implemented for matrices.
+def _det_bareiss(M, iszerofunc=_is_zero_after_expand_mul):
+    """Compute matrix determinant using Bareiss' fraction-free
+    algorithm which is an extension of the well known Gaussian
+    elimination method. This approach is best suited for dense
+    symbolic matrices and will result in a determinant with
+    minimal number of fractions. It means that less term
+    rewriting is needed on resulting formulae.
+
+    Parameters
+    ==========
+
+    iszerofunc : function, optional
+        The function to use to determine zeros when doing an LU decomposition.
+        Defaults to ``lambda x: x.is_zero``.
+
+    TODO: Implement algorithm for sparse matrices (SFF),
+    http://www.eecis.udel.edu/~saunders/papers/sffge/it5.ps.
+    """
+
+    # Recursively implemented Bareiss' algorithm as per Deanna Richelle Leggett's
+    # thesis http://www.math.usm.edu/perry/Research/Thesis_DRL.pdf
+    def bareiss(mat, cumm=1):
+        if mat.rows == 0:
+            return mat.one
+        elif mat.rows == 1:
+            return mat[0, 0]
+
+        # find a pivot and extract the remaining matrix
+        # With the default iszerofunc, _find_reasonable_pivot slows down
+        # the computation by the factor of 2.5 in one test.
+        # Relevant issues: #10279 and #13877.
+        pivot_pos, pivot_val, _, _ = _find_reasonable_pivot(mat[:, 0], iszerofunc=iszerofunc)
+        if pivot_pos is None:
+            return mat.zero
+
+        # if we have a valid pivot, we'll do a "row swap", so keep the
+        # sign of the det
+        sign = (-1) ** (pivot_pos % 2)
+
+        # we want every row but the pivot row and every column
+        rows = [i for i in range(mat.rows) if i != pivot_pos]
+        cols = list(range(mat.cols))
+        tmp_mat = mat.extract(rows, cols)
+
+        def entry(i, j):
+            ret = (pivot_val*tmp_mat[i, j + 1] - mat[pivot_pos, j + 1]*tmp_mat[i, 0]) / cumm
+            if _get_intermediate_simp_bool(True):
+                return _dotprodsimp(ret)
+            elif not ret.is_Atom:
+                return cancel(ret)
+            return ret
+
+        return sign*bareiss(M._new(mat.rows - 1, mat.cols - 1, entry), pivot_val)
+
+    if not M.is_square:
+        raise NonSquareMatrixError()
+
+    if M.rows == 0:
+        return M.one
+        # sympy/matrices/tests/test_matrices.py contains a test that
+        # suggests that the determinant of a 0 x 0 matrix is one, by
+        # convention.
+
+    return bareiss(M)
+
+
+def _det_berkowitz(M):
+    """ Use the Berkowitz algorithm to compute the determinant."""
+
+    if not M.is_square:
+        raise NonSquareMatrixError()
+
+    if M.rows == 0:
+        return M.one
+        # sympy/matrices/tests/test_matrices.py contains a test that
+        # suggests that the determinant of a 0 x 0 matrix is one, by
+        # convention.
+
+    berk_vector = _berkowitz_vector(M)
+    return (-1)**(len(berk_vector) - 1) * berk_vector[-1]
+
+
+# This functions is a candidate for caching if it gets implemented for matrices.
+def _det_LU(M, iszerofunc=_iszero, simpfunc=None):
+    """ Computes the determinant of a matrix from its LU decomposition.
+    This function uses the LU decomposition computed by
+    LUDecomposition_Simple().
+
+    The keyword arguments iszerofunc and simpfunc are passed to
+    LUDecomposition_Simple().
+    iszerofunc is a callable that returns a boolean indicating if its
+    input is zero, or None if it cannot make the determination.
+    simpfunc is a callable that simplifies its input.
+    The default is simpfunc=None, which indicate that the pivot search
+    algorithm should not attempt to simplify any candidate pivots.
+    If simpfunc fails to simplify its input, then it must return its input
+    instead of a copy.
+
+    Parameters
+    ==========
+
+    iszerofunc : function, optional
+        The function to use to determine zeros when doing an LU decomposition.
+        Defaults to ``lambda x: x.is_zero``.
+
+    simpfunc : function, optional
+        The simplification function to use when looking for zeros for pivots.
+    """
+
+    if not M.is_square:
+        raise NonSquareMatrixError()
+
+    if M.rows == 0:
+        return M.one
+        # sympy/matrices/tests/test_matrices.py contains a test that
+        # suggests that the determinant of a 0 x 0 matrix is one, by
+        # convention.
+
+    lu, row_swaps = M.LUdecomposition_Simple(iszerofunc=iszerofunc,
+            simpfunc=simpfunc)
+    # P*A = L*U => det(A) = det(L)*det(U)/det(P) = det(P)*det(U).
+    # Lower triangular factor L encoded in lu has unit diagonal => det(L) = 1.
+    # P is a permutation matrix => det(P) in {-1, 1} => 1/det(P) = det(P).
+    # LUdecomposition_Simple() returns a list of row exchange index pairs, rather
+    # than a permutation matrix, but det(P) = (-1)**len(row_swaps).
+
+    # Avoid forming the potentially time consuming  product of U's diagonal entries
+    # if the product is zero.
+    # Bottom right entry of U is 0 => det(A) = 0.
+    # It may be impossible to determine if this entry of U is zero when it is symbolic.
+    if iszerofunc(lu[lu.rows-1, lu.rows-1]):
+        return M.zero
+
+    # Compute det(P)
+    det = -M.one if len(row_swaps)%2 else M.one
+
+    # Compute det(U) by calculating the product of U's diagonal entries.
+    # The upper triangular portion of lu is the upper triangular portion of the
+    # U factor in the LU decomposition.
+    for k in range(lu.rows):
+        det *= lu[k, k]
+
+    # return det(P)*det(U)
+    return det
+
+
+@cacheit
+def __det_laplace(M):
+    """Compute the determinant of a matrix using Laplace expansion.
+
+    This is a recursive function, and it should not be called directly.
+    Use _det_laplace() instead. The reason for splitting this function
+    into two is to allow caching of determinants of submatrices. While
+    one could also define this function inside _det_laplace(), that
+    would remove the advantage of using caching in Cramer Solve.
+    """
+    n = M.shape[0]
+    if n == 1:
+        return M[0]
+    elif n == 2:
+        return M[0, 0] * M[1, 1] - M[0, 1] * M[1, 0]
+    else:
+        return sum((-1) ** i * M[0, i] *
+                   __det_laplace(M.minor_submatrix(0, i)) for i in range(n))
+
+
+def _det_laplace(M):
+    """Compute the determinant of a matrix using Laplace expansion.
+
+    While Laplace expansion is not the most efficient method of computing
+    a determinant, it is a simple one, and it has the advantage of
+    being division free. To improve efficiency, this function uses
+    caching to avoid recomputing determinants of submatrices.
+    """
+    if not M.is_square:
+        raise NonSquareMatrixError()
+    if M.shape[0] == 0:
+        return M.one
+        # sympy/matrices/tests/test_matrices.py contains a test that
+        # suggests that the determinant of a 0 x 0 matrix is one, by
+        # convention.
+    return __det_laplace(M.as_immutable())
+
+
+def _det_bird(M):
+    r"""Compute the determinant of a matrix using Bird's algorithm.
+
+    Bird's algorithm is a simple division-free algorithm for computing, which
+    is of lower order than the Laplace's algorithm. It is described in [1]_.
+
+    References
+    ==========
+
+    .. [1] Bird, R. S. (2011). A simple division-free algorithm for computing
+           determinants. Inf. Process. Lett., 111(21), 1072-1074. doi:
+           10.1016/j.ipl.2011.08.006
+    """
+    def mu(X):
+        n = X.shape[0]
+        zero = X.domain.zero
+
+        total = zero
+        diag_sums = [zero]
+        for i in reversed(range(1, n)):
+            total -= X[i][i]
+            diag_sums.append(total)
+        diag_sums = diag_sums[::-1]
+
+        elems = [[zero] * i + [diag_sums[i]] + X_i[i + 1:] for i, X_i in
+                 enumerate(X)]
+        return DDM(elems, X.shape, X.domain)
+
+    Mddm = M._rep.to_ddm()
+    n = M.shape[0]
+    if n == 0:
+        return M.one
+        # sympy/matrices/tests/test_matrices.py contains a test that
+        # suggests that the determinant of a 0 x 0 matrix is one, by
+        # convention.
+    Fn1 = Mddm
+    for _ in range(n - 1):
+        Fn1 = mu(Fn1).matmul(Mddm)
+    detA = Fn1[0][0]
+    if n % 2 == 0:
+        detA = -detA
+
+    return Mddm.domain.to_sympy(detA)
+
+
+def _minor(M, i, j, method="berkowitz"):
+    """Return the (i,j) minor of ``M``.  That is,
+    return the determinant of the matrix obtained by deleting
+    the `i`th row and `j`th column from ``M``.
+
+    Parameters
+    ==========
+
+    i, j : int
+        The row and column to exclude to obtain the submatrix.
+
+    method : string, optional
+        Method to use to find the determinant of the submatrix, can be
+        "bareiss", "berkowitz", "bird", "laplace" or "lu".
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> M = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+    >>> M.minor(1, 1)
+    -12
+
+    See Also
+    ========
+
+    minor_submatrix
+    cofactor
+    det
+    """
+
+    if not M.is_square:
+        raise NonSquareMatrixError()
+
+    return M.minor_submatrix(i, j).det(method=method)
+
+
+def _minor_submatrix(M, i, j):
+    """Return the submatrix obtained by removing the `i`th row
+    and `j`th column from ``M`` (works with Pythonic negative indices).
+
+    Parameters
+    ==========
+
+    i, j : int
+        The row and column to exclude to obtain the submatrix.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> M = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+    >>> M.minor_submatrix(1, 1)
+    Matrix([
+    [1, 3],
+    [7, 9]])
+
+    See Also
+    ========
+
+    minor
+    cofactor
+    """
+
+    if i < 0:
+        i += M.rows
+    if j < 0:
+        j += M.cols
+
+    if not 0 <= i < M.rows or not 0 <= j < M.cols:
+        raise ValueError("`i` and `j` must satisfy 0 <= i < ``M.rows`` "
+                            "(%d)" % M.rows + "and 0 <= j < ``M.cols`` (%d)." % M.cols)
+
+    rows = [a for a in range(M.rows) if a != i]
+    cols = [a for a in range(M.cols) if a != j]
+
+    return M.extract(rows, cols)

.venv/lib/python3.11/site-packages/sympy/matrices/eigen.py

@@ -0,0 +1,1346 @@
+from types import FunctionType
+from collections import Counter
+
+from mpmath import mp, workprec
+from mpmath.libmp.libmpf import prec_to_dps
+
+from sympy.core.sorting import default_sort_key
+from sympy.core.evalf import DEFAULT_MAXPREC, PrecisionExhausted
+from sympy.core.logic import fuzzy_and, fuzzy_or
+from sympy.core.numbers import Float
+from sympy.core.sympify import _sympify
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.polys import roots, CRootOf, ZZ, QQ, EX
+from sympy.polys.matrices import DomainMatrix
+from sympy.polys.matrices.eigen import dom_eigenvects, dom_eigenvects_to_sympy
+from sympy.polys.polytools import gcd
+
+from .exceptions import MatrixError, NonSquareMatrixError
+from .determinant import _find_reasonable_pivot
+
+from .utilities import _iszero, _simplify
+
+
+__doctest_requires__ = {
+    ('_is_indefinite',
+     '_is_negative_definite',
+     '_is_negative_semidefinite',
+     '_is_positive_definite',
+     '_is_positive_semidefinite'): ['matplotlib'],
+}
+
+
+def _eigenvals_eigenvects_mpmath(M):
+    norm2 = lambda v: mp.sqrt(sum(i**2 for i in v))
+
+    v1 = None
+    prec = max(x._prec for x in M.atoms(Float))
+    eps = 2**-prec
+
+    while prec < DEFAULT_MAXPREC:
+        with workprec(prec):
+            A = mp.matrix(M.evalf(n=prec_to_dps(prec)))
+            E, ER = mp.eig(A)
+            v2 = norm2([i for e in E for i in (mp.re(e), mp.im(e))])
+            if v1 is not None and mp.fabs(v1 - v2) < eps:
+                return E, ER
+            v1 = v2
+        prec *= 2
+
+    # we get here because the next step would have taken us
+    # past MAXPREC or because we never took a step; in case
+    # of the latter, we refuse to send back a solution since
+    # it would not have been verified; we also resist taking
+    # a small step to arrive exactly at MAXPREC since then
+    # the two calculations might be artificially close.
+    raise PrecisionExhausted
+
+
+def _eigenvals_mpmath(M, multiple=False):
+    """Compute eigenvalues using mpmath"""
+    E, _ = _eigenvals_eigenvects_mpmath(M)
+    result = [_sympify(x) for x in E]
+    if multiple:
+        return result
+    return dict(Counter(result))
+
+
+def _eigenvects_mpmath(M):
+    E, ER = _eigenvals_eigenvects_mpmath(M)
+    result = []
+    for i in range(M.rows):
+        eigenval = _sympify(E[i])
+        eigenvect = _sympify(ER[:, i])
+        result.append((eigenval, 1, [eigenvect]))
+
+    return result
+
+
+# This function is a candidate for caching if it gets implemented for matrices.
+def _eigenvals(
+    M, error_when_incomplete=True, *, simplify=False, multiple=False,
+    rational=False, **flags):
+    r"""Compute eigenvalues of the matrix.
+
+    Parameters
+    ==========
+
+    error_when_incomplete : bool, optional
+        If it is set to ``True``, it will raise an error if not all
+        eigenvalues are computed. This is caused by ``roots`` not returning
+        a full list of eigenvalues.
+
+    simplify : bool or function, optional
+        If it is set to ``True``, it attempts to return the most
+        simplified form of expressions returned by applying default
+        simplification method in every routine.
+
+        If it is set to ``False``, it will skip simplification in this
+        particular routine to save computation resources.
+
+        If a function is passed to, it will attempt to apply
+        the particular function as simplification method.
+
+    rational : bool, optional
+        If it is set to ``True``, every floating point numbers would be
+        replaced with rationals before computation. It can solve some
+        issues of ``roots`` routine not working well with floats.
+
+    multiple : bool, optional
+        If it is set to ``True``, the result will be in the form of a
+        list.
+
+        If it is set to ``False``, the result will be in the form of a
+        dictionary.
+
+    Returns
+    =======
+
+    eigs : list or dict
+        Eigenvalues of a matrix. The return format would be specified by
+        the key ``multiple``.
+
+    Raises
+    ======
+
+    MatrixError
+        If not enough roots had got computed.
+
+    NonSquareMatrixError
+        If attempted to compute eigenvalues from a non-square matrix.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> M = Matrix(3, 3, [0, 1, 1, 1, 0, 0, 1, 1, 1])
+    >>> M.eigenvals()
+    {-1: 1, 0: 1, 2: 1}
+
+    See Also
+    ========
+
+    MatrixBase.charpoly
+    eigenvects
+
+    Notes
+    =====
+
+    Eigenvalues of a matrix $A$ can be computed by solving a matrix
+    equation $\det(A - \lambda I) = 0$
+
+    It's not always possible to return radical solutions for
+    eigenvalues for matrices larger than $4, 4$ shape due to
+    Abel-Ruffini theorem.
+
+    If there is no radical solution is found for the eigenvalue,
+    it may return eigenvalues in the form of
+    :class:`sympy.polys.rootoftools.ComplexRootOf`.
+    """
+    if not M:
+        if multiple:
+            return []
+        return {}
+
+    if not M.is_square:
+        raise NonSquareMatrixError("{} must be a square matrix.".format(M))
+
+    if M._rep.domain not in (ZZ, QQ):
+        # Skip this check for ZZ/QQ because it can be slow
+        if all(x.is_number for x in M) and M.has(Float):
+            return _eigenvals_mpmath(M, multiple=multiple)
+
+    if rational:
+        from sympy.simplify import nsimplify
+        M = M.applyfunc(
+            lambda x: nsimplify(x, rational=True) if x.has(Float) else x)
+
+    if multiple:
+        return _eigenvals_list(
+            M, error_when_incomplete=error_when_incomplete, simplify=simplify,
+            **flags)
+    return _eigenvals_dict(
+        M, error_when_incomplete=error_when_incomplete, simplify=simplify,
+        **flags)
+
+
+eigenvals_error_message = \
+"It is not always possible to express the eigenvalues of a matrix " + \
+"of size 5x5 or higher in radicals. " + \
+"We have CRootOf, but domains other than the rationals are not " + \
+"currently supported. " + \
+"If there are no symbols in the matrix, " + \
+"it should still be possible to compute numeric approximations " + \
+"of the eigenvalues using " + \
+"M.evalf().eigenvals() or M.charpoly().nroots()."
+
+
+def _eigenvals_list(
+    M, error_when_incomplete=True, simplify=False, **flags):
+    iblocks = M.strongly_connected_components()
+    all_eigs = []
+    is_dom = M._rep.domain in (ZZ, QQ)
+    for b in iblocks:
+
+        # Fast path for a 1x1 block:
+        if is_dom and len(b) == 1:
+            index = b[0]
+            val = M[index, index]
+            all_eigs.append(val)
+            continue
+
+        block = M[b, b]
+
+        if isinstance(simplify, FunctionType):
+            charpoly = block.charpoly(simplify=simplify)
+        else:
+            charpoly = block.charpoly()
+
+        eigs = roots(charpoly, multiple=True, **flags)
+
+        if len(eigs) != block.rows:
+            try:
+                eigs = charpoly.all_roots(multiple=True)
+            except NotImplementedError:
+                if error_when_incomplete:
+                    raise MatrixError(eigenvals_error_message)
+                else:
+                    eigs = []
+
+        all_eigs += eigs
+
+    if not simplify:
+        return all_eigs
+    if not isinstance(simplify, FunctionType):
+        simplify = _simplify
+    return [simplify(value) for value in all_eigs]
+
+
+def _eigenvals_dict(
+    M, error_when_incomplete=True, simplify=False, **flags):
+    iblocks = M.strongly_connected_components()
+    all_eigs = {}
+    is_dom = M._rep.domain in (ZZ, QQ)
+    for b in iblocks:
+
+        # Fast path for a 1x1 block:
+        if is_dom and len(b) == 1:
+            index = b[0]
+            val = M[index, index]
+            all_eigs[val] = all_eigs.get(val, 0) + 1
+            continue
+
+        block = M[b, b]
+
+        if isinstance(simplify, FunctionType):
+            charpoly = block.charpoly(simplify=simplify)
+        else:
+            charpoly = block.charpoly()
+
+        eigs = roots(charpoly, multiple=False, **flags)
+
+        if sum(eigs.values()) != block.rows:
+            try:
+                eigs = dict(charpoly.all_roots(multiple=False))
+            except NotImplementedError:
+                if error_when_incomplete:
+                    raise MatrixError(eigenvals_error_message)
+                else:
+                    eigs = {}
+
+        for k, v in eigs.items():
+            if k in all_eigs:
+                all_eigs[k] += v
+            else:
+                all_eigs[k] = v
+
+    if not simplify:
+        return all_eigs
+    if not isinstance(simplify, FunctionType):
+        simplify = _simplify
+    return {simplify(key): value for key, value in all_eigs.items()}
+
+
+def _eigenspace(M, eigenval, iszerofunc=_iszero, simplify=False):
+    """Get a basis for the eigenspace for a particular eigenvalue"""
+    m   = M - M.eye(M.rows) * eigenval
+    ret = m.nullspace(iszerofunc=iszerofunc)
+
+    # The nullspace for a real eigenvalue should be non-trivial.
+    # If we didn't find an eigenvector, try once more a little harder
+    if len(ret) == 0 and simplify:
+        ret = m.nullspace(iszerofunc=iszerofunc, simplify=True)
+    if len(ret) == 0:
+        raise NotImplementedError(
+            "Can't evaluate eigenvector for eigenvalue {}".format(eigenval))
+    return ret
+
+
+def _eigenvects_DOM(M, **kwargs):
+    DOM = DomainMatrix.from_Matrix(M, field=True, extension=True)
+    DOM = DOM.to_dense()
+
+    if DOM.domain != EX:
+        rational, algebraic = dom_eigenvects(DOM)
+        eigenvects = dom_eigenvects_to_sympy(
+            rational, algebraic, M.__class__, **kwargs)
+        eigenvects = sorted(eigenvects, key=lambda x: default_sort_key(x[0]))
+
+        return eigenvects
+    return None
+
+
+def _eigenvects_sympy(M, iszerofunc, simplify=True, **flags):
+    eigenvals = M.eigenvals(rational=False, **flags)
+
+    # Make sure that we have all roots in radical form
+    for x in eigenvals:
+        if x.has(CRootOf):
+            raise MatrixError(
+                "Eigenvector computation is not implemented if the matrix have "
+                "eigenvalues in CRootOf form")
+
+    eigenvals = sorted(eigenvals.items(), key=default_sort_key)
+    ret = []
+    for val, mult in eigenvals:
+        vects = _eigenspace(M, val, iszerofunc=iszerofunc, simplify=simplify)
+        ret.append((val, mult, vects))
+    return ret
+
+
+# This functions is a candidate for caching if it gets implemented for matrices.
+def _eigenvects(M, error_when_incomplete=True, iszerofunc=_iszero, *, chop=False, **flags):
+    """Compute eigenvectors of the matrix.
+
+    Parameters
+    ==========
+
+    error_when_incomplete : bool, optional
+        Raise an error when not all eigenvalues are computed. This is
+        caused by ``roots`` not returning a full list of eigenvalues.
+
+    iszerofunc : function, optional
+        Specifies a zero testing function to be used in ``rref``.
+
+        Default value is ``_iszero``, which uses SymPy's naive and fast
+        default assumption handler.
+
+        It can also accept any user-specified zero testing function, if it
+        is formatted as a function which accepts a single symbolic argument
+        and returns ``True`` if it is tested as zero and ``False`` if it
+        is tested as non-zero, and ``None`` if it is undecidable.
+
+    simplify : bool or function, optional
+        If ``True``, ``as_content_primitive()`` will be used to tidy up
+        normalization artifacts.
+
+        It will also be used by the ``nullspace`` routine.
+
+    chop : bool or positive number, optional
+        If the matrix contains any Floats, they will be changed to Rationals
+        for computation purposes, but the answers will be returned after
+        being evaluated with evalf. The ``chop`` flag is passed to ``evalf``.
+        When ``chop=True`` a default precision will be used; a number will
+        be interpreted as the desired level of precision.
+
+    Returns
+    =======
+
+    ret : [(eigenval, multiplicity, eigenspace), ...]
+        A ragged list containing tuples of data obtained by ``eigenvals``
+        and ``nullspace``.
+
+        ``eigenspace`` is a list containing the ``eigenvector`` for each
+        eigenvalue.
+
+        ``eigenvector`` is a vector in the form of a ``Matrix``. e.g.
+        a vector of length 3 is returned as ``Matrix([a_1, a_2, a_3])``.
+
+    Raises
+    ======
+
+    NotImplementedError
+        If failed to compute nullspace.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> M = Matrix(3, 3, [0, 1, 1, 1, 0, 0, 1, 1, 1])
+    >>> M.eigenvects()
+    [(-1, 1, [Matrix([
+    [-1],
+    [ 1],
+    [ 0]])]), (0, 1, [Matrix([
+    [ 0],
+    [-1],
+    [ 1]])]), (2, 1, [Matrix([
+    [2/3],
+    [1/3],
+    [  1]])])]
+
+    See Also
+    ========
+
+    eigenvals
+    MatrixBase.nullspace
+    """
+    simplify = flags.get('simplify', True)
+    primitive = flags.get('simplify', False)
+    flags.pop('simplify', None)  # remove this if it's there
+    flags.pop('multiple', None)  # remove this if it's there
+
+    if not isinstance(simplify, FunctionType):
+        simpfunc = _simplify if simplify else lambda x: x
+
+    has_floats = M.has(Float)
+    if has_floats:
+        if all(x.is_number for x in M):
+            return _eigenvects_mpmath(M)
+        from sympy.simplify import nsimplify
+        M = M.applyfunc(lambda x: nsimplify(x, rational=True))
+
+    ret = _eigenvects_DOM(M)
+    if ret is None:
+        ret = _eigenvects_sympy(M, iszerofunc, simplify=simplify, **flags)
+
+    if primitive:
+        # if the primitive flag is set, get rid of any common
+        # integer denominators
+        def denom_clean(l):
+            return [(v / gcd(list(v))).applyfunc(simpfunc) for v in l]
+
+        ret = [(val, mult, denom_clean(es)) for val, mult, es in ret]
+
+    if has_floats:
+        # if we had floats to start with, turn the eigenvectors to floats
+        ret = [(val.evalf(chop=chop), mult, [v.evalf(chop=chop) for v in es])
+                for val, mult, es in ret]
+
+    return ret
+
+
+def _is_diagonalizable_with_eigen(M, reals_only=False):
+    """See _is_diagonalizable. This function returns the bool along with the
+    eigenvectors to avoid calculating them again in functions like
+    ``diagonalize``."""
+
+    if not M.is_square:
+        return False, []
+
+    eigenvecs = M.eigenvects(simplify=True)
+
+    for val, mult, basis in eigenvecs:
+        if reals_only and not val.is_real: # if we have a complex eigenvalue
+            return False, eigenvecs
+
+        if mult != len(basis): # if the geometric multiplicity doesn't equal the algebraic
+            return False, eigenvecs
+
+    return True, eigenvecs
+
+def _is_diagonalizable(M, reals_only=False, **kwargs):
+    """Returns ``True`` if a matrix is diagonalizable.
+
+    Parameters
+    ==========
+
+    reals_only : bool, optional
+        If ``True``, it tests whether the matrix can be diagonalized
+        to contain only real numbers on the diagonal.
+
+
+        If ``False``, it tests whether the matrix can be diagonalized
+        at all, even with numbers that may not be real.
+
+    Examples
+    ========
+
+    Example of a diagonalizable matrix:
+
+    >>> from sympy import Matrix
+    >>> M = Matrix([[1, 2, 0], [0, 3, 0], [2, -4, 2]])
+    >>> M.is_diagonalizable()
+    True
+
+    Example of a non-diagonalizable matrix:
+
+    >>> M = Matrix([[0, 1], [0, 0]])
+    >>> M.is_diagonalizable()
+    False
+
+    Example of a matrix that is diagonalized in terms of non-real entries:
+
+    >>> M = Matrix([[0, 1], [-1, 0]])
+    >>> M.is_diagonalizable(reals_only=False)
+    True
+    >>> M.is_diagonalizable(reals_only=True)
+    False
+
+    See Also
+    ========
+
+    sympy.matrices.matrixbase.MatrixBase.is_diagonal
+    diagonalize
+    """
+    if not M.is_square:
+        return False
+
+    if all(e.is_real for e in M) and M.is_symmetric():
+        return True
+
+    if all(e.is_complex for e in M) and M.is_hermitian:
+        return True
+
+    return _is_diagonalizable_with_eigen(M, reals_only=reals_only)[0]
+
+
+#G&VL, Matrix Computations, Algo 5.4.2
+def _householder_vector(x):
+    if not x.cols == 1:
+        raise ValueError("Input must be a column matrix")
+    v = x.copy()
+    v_plus = x.copy()
+    v_minus = x.copy()
+    q = x[0, 0] / abs(x[0, 0])
+    norm_x = x.norm()
+    v_plus[0, 0] = x[0, 0] + q * norm_x
+    v_minus[0, 0] = x[0, 0] - q * norm_x
+    if x[1:, 0].norm() == 0:
+        bet = 0
+        v[0, 0] = 1
+    else:
+        if v_plus.norm() <= v_minus.norm():
+            v = v_plus
+        else:
+            v = v_minus
+        v = v / v[0]
+        bet = 2 / (v.norm() ** 2)
+    return v, bet
+
+
+def _bidiagonal_decmp_hholder(M):
+    m = M.rows
+    n = M.cols
+    A = M.as_mutable()
+    U, V = A.eye(m), A.eye(n)
+    for i in range(min(m, n)):
+        v, bet = _householder_vector(A[i:, i])
+        hh_mat = A.eye(m - i) - bet * v * v.H
+        A[i:, i:] = hh_mat * A[i:, i:]
+        temp = A.eye(m)
+        temp[i:, i:] = hh_mat
+        U = U * temp
+        if i + 1 <= n - 2:
+            v, bet = _householder_vector(A[i, i+1:].T)
+            hh_mat = A.eye(n - i - 1) - bet * v * v.H
+            A[i:, i+1:] = A[i:, i+1:] * hh_mat
+            temp = A.eye(n)
+            temp[i+1:, i+1:] = hh_mat
+            V = temp * V
+    return U, A, V
+
+
+def _eval_bidiag_hholder(M):
+    m = M.rows
+    n = M.cols
+    A = M.as_mutable()
+    for i in range(min(m, n)):
+        v, bet = _householder_vector(A[i:, i])
+        hh_mat = A.eye(m-i) - bet * v * v.H
+        A[i:, i:] = hh_mat * A[i:, i:]
+        if i + 1 <= n - 2:
+            v, bet = _householder_vector(A[i, i+1:].T)
+            hh_mat = A.eye(n - i - 1) - bet * v * v.H
+            A[i:, i+1:] = A[i:, i+1:] * hh_mat
+    return A
+
+
+def _bidiagonal_decomposition(M, upper=True):
+    """
+    Returns $(U,B,V.H)$ for
+
+    $$A = UBV^{H}$$
+
+    where $A$ is the input matrix, and $B$ is its Bidiagonalized form
+
+    Note: Bidiagonal Computation can hang for symbolic matrices.
+
+    Parameters
+    ==========
+
+    upper : bool. Whether to do upper bidiagnalization or lower.
+                True for upper and False for lower.
+
+    References
+    ==========
+
+    .. [1] Algorithm 5.4.2, Matrix computations by Golub and Van Loan, 4th edition
+    .. [2] Complex Matrix Bidiagonalization, https://github.com/vslobody/Householder-Bidiagonalization
+
+    """
+
+    if not isinstance(upper, bool):
+        raise ValueError("upper must be a boolean")
+
+    if upper:
+        return _bidiagonal_decmp_hholder(M)
+
+    X = _bidiagonal_decmp_hholder(M.H)
+    return X[2].H, X[1].H, X[0].H
+
+
+def _bidiagonalize(M, upper=True):
+    """
+    Returns $B$, the Bidiagonalized form of the input matrix.
+
+    Note: Bidiagonal Computation can hang for symbolic matrices.
+
+    Parameters
+    ==========
+
+    upper : bool. Whether to do upper bidiagnalization or lower.
+                True for upper and False for lower.
+
+    References
+    ==========
+
+    .. [1] Algorithm 5.4.2, Matrix computations by Golub and Van Loan, 4th edition
+    .. [2] Complex Matrix Bidiagonalization : https://github.com/vslobody/Householder-Bidiagonalization
+
+    """
+
+    if not isinstance(upper, bool):
+        raise ValueError("upper must be a boolean")
+
+    if upper:
+        return _eval_bidiag_hholder(M)
+    return _eval_bidiag_hholder(M.H).H
+
+
+def _diagonalize(M, reals_only=False, sort=False, normalize=False):
+    """
+    Return (P, D), where D is diagonal and
+
+        D = P^-1 * M * P
+
+    where M is current matrix.
+
+    Parameters
+    ==========
+
+    reals_only : bool. Whether to throw an error if complex numbers are need
+                    to diagonalize. (Default: False)
+
+    sort : bool. Sort the eigenvalues along the diagonal. (Default: False)
+
+    normalize : bool. If True, normalize the columns of P. (Default: False)
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> M = Matrix(3, 3, [1, 2, 0, 0, 3, 0, 2, -4, 2])
+    >>> M
+    Matrix([
+    [1,  2, 0],
+    [0,  3, 0],
+    [2, -4, 2]])
+    >>> (P, D) = M.diagonalize()
+    >>> D
+    Matrix([
+    [1, 0, 0],
+    [0, 2, 0],
+    [0, 0, 3]])
+    >>> P
+    Matrix([
+    [-1, 0, -1],
+    [ 0, 0, -1],
+    [ 2, 1,  2]])
+    >>> P.inv() * M * P
+    Matrix([
+    [1, 0, 0],
+    [0, 2, 0],
+    [0, 0, 3]])
+
+    See Also
+    ========
+
+    sympy.matrices.matrixbase.MatrixBase.is_diagonal
+    is_diagonalizable
+    """
+
+    if not M.is_square:
+        raise NonSquareMatrixError()
+
+    is_diagonalizable, eigenvecs = _is_diagonalizable_with_eigen(M,
+                reals_only=reals_only)
+
+    if not is_diagonalizable:
+        raise MatrixError("Matrix is not diagonalizable")
+
+    if sort:
+        eigenvecs = sorted(eigenvecs, key=default_sort_key)
+
+    p_cols, diag = [], []
+
+    for val, mult, basis in eigenvecs:
+        diag   += [val] * mult
+        p_cols += basis
+
+    if normalize:
+        p_cols = [v / v.norm() for v in p_cols]
+
+    return M.hstack(*p_cols), M.diag(*diag)
+
+
+def _fuzzy_positive_definite(M):
+    positive_diagonals = M._has_positive_diagonals()
+    if positive_diagonals is False:
+        return False
+
+    if positive_diagonals and M.is_strongly_diagonally_dominant:
+        return True
+
+    return None
+
+
+def _fuzzy_positive_semidefinite(M):
+    nonnegative_diagonals = M._has_nonnegative_diagonals()
+    if nonnegative_diagonals is False:
+        return False
+
+    if nonnegative_diagonals and M.is_weakly_diagonally_dominant:
+        return True
+
+    return None
+
+
+def _is_positive_definite(M):
+    if not M.is_hermitian:
+        if not M.is_square:
+            return False
+        M = M + M.H
+
+    fuzzy = _fuzzy_positive_definite(M)
+    if fuzzy is not None:
+        return fuzzy
+
+    return _is_positive_definite_GE(M)
+
+
+def _is_positive_semidefinite(M):
+    if not M.is_hermitian:
+        if not M.is_square:
+            return False
+        M = M + M.H
+
+    fuzzy = _fuzzy_positive_semidefinite(M)
+    if fuzzy is not None:
+        return fuzzy
+
+    return _is_positive_semidefinite_cholesky(M)
+
+
+def _is_negative_definite(M):
+    return _is_positive_definite(-M)
+
+
+def _is_negative_semidefinite(M):
+    return _is_positive_semidefinite(-M)
+
+
+def _is_indefinite(M):
+    if M.is_hermitian:
+        eigen = M.eigenvals()
+        args1        = [x.is_positive for x in eigen.keys()]
+        any_positive = fuzzy_or(args1)
+        args2        = [x.is_negative for x in eigen.keys()]
+        any_negative = fuzzy_or(args2)
+
+        return fuzzy_and([any_positive, any_negative])
+
+    elif M.is_square:
+        return (M + M.H).is_indefinite
+
+    return False
+
+
+def _is_positive_definite_GE(M):
+    """A division-free gaussian elimination method for testing
+    positive-definiteness."""
+    M = M.as_mutable()
+    size = M.rows
+
+    for i in range(size):
+        is_positive = M[i, i].is_positive
+        if is_positive is not True:
+            return is_positive
+        for j in range(i+1, size):
+            M[j, i+1:] = M[i, i] * M[j, i+1:] - M[j, i] * M[i, i+1:]
+    return True
+
+
+def _is_positive_semidefinite_cholesky(M):
+    """Uses Cholesky factorization with complete pivoting
+
+    References
+    ==========
+
+    .. [1] http://eprints.ma.man.ac.uk/1199/1/covered/MIMS_ep2008_116.pdf
+
+    .. [2] https://www.value-at-risk.net/cholesky-factorization/
+    """
+    M = M.as_mutable()
+    for k in range(M.rows):
+        diags = [M[i, i] for i in range(k, M.rows)]
+        pivot, pivot_val, nonzero, _ = _find_reasonable_pivot(diags)
+
+        if nonzero:
+            return None
+
+        if pivot is None:
+            for i in range(k+1, M.rows):
+                for j in range(k, M.cols):
+                    iszero = M[i, j].is_zero
+                    if iszero is None:
+                        return None
+                    elif iszero is False:
+                        return False
+            return True
+
+        if M[k, k].is_negative or pivot_val.is_negative:
+            return False
+        elif not (M[k, k].is_nonnegative and pivot_val.is_nonnegative):
+            return None
+
+        if pivot > 0:
+            M.col_swap(k, k+pivot)
+            M.row_swap(k, k+pivot)
+
+        M[k, k] = sqrt(M[k, k])
+        M[k, k+1:] /= M[k, k]
+        M[k+1:, k+1:] -= M[k, k+1:].H * M[k, k+1:]
+
+    return M[-1, -1].is_nonnegative
+
+
+_doc_positive_definite = \
+    r"""Finds out the definiteness of a matrix.
+
+    Explanation
+    ===========
+
+    A square real matrix $A$ is:
+
+    - A positive definite matrix if $x^T A x > 0$
+      for all non-zero real vectors $x$.
+    - A positive semidefinite matrix if $x^T A x \geq 0$
+      for all non-zero real vectors $x$.
+    - A negative definite matrix if $x^T A x < 0$
+      for all non-zero real vectors $x$.
+    - A negative semidefinite matrix if $x^T A x \leq 0$
+      for all non-zero real vectors $x$.
+    - An indefinite matrix if there exists non-zero real vectors
+      $x, y$ with $x^T A x > 0 > y^T A y$.
+
+    A square complex matrix $A$ is:
+
+    - A positive definite matrix if $\text{re}(x^H A x) > 0$
+      for all non-zero complex vectors $x$.
+    - A positive semidefinite matrix if $\text{re}(x^H A x) \geq 0$
+      for all non-zero complex vectors $x$.
+    - A negative definite matrix if $\text{re}(x^H A x) < 0$
+      for all non-zero complex vectors $x$.
+    - A negative semidefinite matrix if $\text{re}(x^H A x) \leq 0$
+      for all non-zero complex vectors $x$.
+    - An indefinite matrix if there exists non-zero complex vectors
+      $x, y$ with $\text{re}(x^H A x) > 0 > \text{re}(y^H A y)$.
+
+    A matrix need not be symmetric or hermitian to be positive definite.
+
+    - A real non-symmetric matrix is positive definite if and only if
+      $\frac{A + A^T}{2}$ is positive definite.
+    - A complex non-hermitian matrix is positive definite if and only if
+      $\frac{A + A^H}{2}$ is positive definite.
+
+    And this extension can apply for all the definitions above.
+
+    However, for complex cases, you can restrict the definition of
+    $\text{re}(x^H A x) > 0$ to $x^H A x > 0$ and require the matrix
+    to be hermitian.
+    But we do not present this restriction for computation because you
+    can check ``M.is_hermitian`` independently with this and use
+    the same procedure.
+
+    Examples
+    ========
+
+    An example of symmetric positive definite matrix:
+
+    .. plot::
+        :context: reset
+        :format: doctest
+        :include-source: True
+
+        >>> from sympy import Matrix, symbols
+        >>> from sympy.plotting import plot3d
+        >>> a, b = symbols('a b')
+        >>> x = Matrix([a, b])
+
+        >>> A = Matrix([[1, 0], [0, 1]])
+        >>> A.is_positive_definite
+        True
+        >>> A.is_positive_semidefinite
+        True
+
+        >>> p = plot3d((x.T*A*x)[0, 0], (a, -1, 1), (b, -1, 1))
+
+    An example of symmetric positive semidefinite matrix:
+
+    .. plot::
+        :context: close-figs
+        :format: doctest
+        :include-source: True
+
+        >>> A = Matrix([[1, -1], [-1, 1]])
+        >>> A.is_positive_definite
+        False
+        >>> A.is_positive_semidefinite
+        True
+
+        >>> p = plot3d((x.T*A*x)[0, 0], (a, -1, 1), (b, -1, 1))
+
+    An example of symmetric negative definite matrix:
+
+    .. plot::
+        :context: close-figs
+        :format: doctest
+        :include-source: True
+
+        >>> A = Matrix([[-1, 0], [0, -1]])
+        >>> A.is_negative_definite
+        True
+        >>> A.is_negative_semidefinite
+        True
+        >>> A.is_indefinite
+        False
+
+        >>> p = plot3d((x.T*A*x)[0, 0], (a, -1, 1), (b, -1, 1))
+
+    An example of symmetric indefinite matrix:
+
+    .. plot::
+        :context: close-figs
+        :format: doctest
+        :include-source: True
+
+        >>> A = Matrix([[1, 2], [2, -1]])
+        >>> A.is_indefinite
+        True
+
+        >>> p = plot3d((x.T*A*x)[0, 0], (a, -1, 1), (b, -1, 1))
+
+    An example of non-symmetric positive definite matrix.
+
+    .. plot::
+        :context: close-figs
+        :format: doctest
+        :include-source: True
+
+        >>> A = Matrix([[1, 2], [-2, 1]])
+        >>> A.is_positive_definite
+        True
+        >>> A.is_positive_semidefinite
+        True
+
+        >>> p = plot3d((x.T*A*x)[0, 0], (a, -1, 1), (b, -1, 1))
+
+    Notes
+    =====
+
+    Although some people trivialize the definition of positive definite
+    matrices only for symmetric or hermitian matrices, this restriction
+    is not correct because it does not classify all instances of
+    positive definite matrices from the definition $x^T A x > 0$ or
+    $\text{re}(x^H A x) > 0$.
+
+    For instance, ``Matrix([[1, 2], [-2, 1]])`` presented in
+    the example above is an example of real positive definite matrix
+    that is not symmetric.
+
+    However, since the following formula holds true;
+
+    .. math::
+        \text{re}(x^H A x) > 0 \iff
+        \text{re}(x^H \frac{A + A^H}{2} x) > 0
+
+    We can classify all positive definite matrices that may or may not
+    be symmetric or hermitian by transforming the matrix to
+    $\frac{A + A^T}{2}$ or $\frac{A + A^H}{2}$
+    (which is guaranteed to be always real symmetric or complex
+    hermitian) and we can defer most of the studies to symmetric or
+    hermitian positive definite matrices.
+
+    But it is a different problem for the existence of Cholesky
+    decomposition. Because even though a non symmetric or a non
+    hermitian matrix can be positive definite, Cholesky or LDL
+    decomposition does not exist because the decompositions require the
+    matrix to be symmetric or hermitian.
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Definiteness_of_a_matrix#Eigenvalues
+
+    .. [2] https://mathworld.wolfram.com/PositiveDefiniteMatrix.html
+
+    .. [3] Johnson, C. R. "Positive Definite Matrices." Amer.
+        Math. Monthly 77, 259-264 1970.
+    """
+
+_is_positive_definite.__doc__     = _doc_positive_definite
+_is_positive_semidefinite.__doc__ = _doc_positive_definite
+_is_negative_definite.__doc__     = _doc_positive_definite
+_is_negative_semidefinite.__doc__ = _doc_positive_definite
+_is_indefinite.__doc__            = _doc_positive_definite
+
+
+def _jordan_form(M, calc_transform=True, *, chop=False):
+    """Return $(P, J)$ where $J$ is a Jordan block
+    matrix and $P$ is a matrix such that $M = P J P^{-1}$
+
+    Parameters
+    ==========
+
+    calc_transform : bool
+        If ``False``, then only $J$ is returned.
+
+    chop : bool
+        All matrices are converted to exact types when computing
+        eigenvalues and eigenvectors.  As a result, there may be
+        approximation errors.  If ``chop==True``, these errors
+        will be truncated.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> M = Matrix([[ 6,  5, -2, -3], [-3, -1,  3,  3], [ 2,  1, -2, -3], [-1,  1,  5,  5]])
+    >>> P, J = M.jordan_form()
+    >>> J
+    Matrix([
+    [2, 1, 0, 0],
+    [0, 2, 0, 0],
+    [0, 0, 2, 1],
+    [0, 0, 0, 2]])
+
+    See Also
+    ========
+
+    jordan_block
+    """
+
+    if not M.is_square:
+        raise NonSquareMatrixError("Only square matrices have Jordan forms")
+
+    mat        = M
+    has_floats = M.has(Float)
+
+    if has_floats:
+        try:
+            max_prec = max(term._prec for term in M.values() if isinstance(term, Float))
+        except ValueError:
+            # if no term in the matrix is explicitly a Float calling max()
+            # will throw a error so setting max_prec to default value of 53
+            max_prec = 53
+
+        # setting minimum max_dps to 15 to prevent loss of precision in
+        # matrix containing non evaluated expressions
+        max_dps = max(prec_to_dps(max_prec), 15)
+
+    def restore_floats(*args):
+        """If ``has_floats`` is `True`, cast all ``args`` as
+        matrices of floats."""
+
+        if has_floats:
+            args = [m.evalf(n=max_dps, chop=chop) for m in args]
+        if len(args) == 1:
+            return args[0]
+
+        return args
+
+    # cache calculations for some speedup
+    mat_cache = {}
+
+    def eig_mat(val, pow):
+        """Cache computations of ``(M - val*I)**pow`` for quick
+        retrieval"""
+
+        if (val, pow) in mat_cache:
+            return mat_cache[(val, pow)]
+
+        if (val, pow - 1) in mat_cache:
+            mat_cache[(val, pow)] = mat_cache[(val, pow - 1)].multiply(
+                    mat_cache[(val, 1)], dotprodsimp=None)
+        else:
+            mat_cache[(val, pow)] = (mat - val*M.eye(M.rows)).pow(pow)
+
+        return mat_cache[(val, pow)]
+
+    # helper functions
+    def nullity_chain(val, algebraic_multiplicity):
+        """Calculate the sequence  [0, nullity(E), nullity(E**2), ...]
+        until it is constant where ``E = M - val*I``"""
+
+        # mat.rank() is faster than computing the null space,
+        # so use the rank-nullity theorem
+        cols    = M.cols
+        ret     = [0]
+        nullity = cols - eig_mat(val, 1).rank()
+        i       = 2
+
+        while nullity != ret[-1]:
+            ret.append(nullity)
+
+            if nullity == algebraic_multiplicity:
+                break
+
+            nullity  = cols - eig_mat(val, i).rank()
+            i       += 1
+
+            # Due to issues like #7146 and #15872, SymPy sometimes
+            # gives the wrong rank. In this case, raise an error
+            # instead of returning an incorrect matrix
+            if nullity < ret[-1] or nullity > algebraic_multiplicity:
+                raise MatrixError(
+                    "SymPy had encountered an inconsistent "
+                    "result while computing Jordan block: "
+                    "{}".format(M))
+
+        return ret
+
+    def blocks_from_nullity_chain(d):
+        """Return a list of the size of each Jordan block.
+        If d_n is the nullity of E**n, then the number
+        of Jordan blocks of size n is
+
+            2*d_n - d_(n-1) - d_(n+1)"""
+
+        # d[0] is always the number of columns, so skip past it
+        mid = [2*d[n] - d[n - 1] - d[n + 1] for n in range(1, len(d) - 1)]
+        # d is assumed to plateau with "d[ len(d) ] == d[-1]", so
+        # 2*d_n - d_(n-1) - d_(n+1) == d_n - d_(n-1)
+        end = [d[-1] - d[-2]] if len(d) > 1 else [d[0]]
+
+        return mid + end
+
+    def pick_vec(small_basis, big_basis):
+        """Picks a vector from big_basis that isn't in
+        the subspace spanned by small_basis"""
+
+        if len(small_basis) == 0:
+            return big_basis[0]
+
+        for v in big_basis:
+            _, pivots = M.hstack(*(small_basis + [v])).echelon_form(
+                    with_pivots=True)
+
+            if pivots[-1] == len(small_basis):
+                return v
+
+    # roots doesn't like Floats, so replace them with Rationals
+    if has_floats:
+        from sympy.simplify import nsimplify
+        mat = mat.applyfunc(lambda x: nsimplify(x, rational=True))
+
+    # first calculate the jordan block structure
+    eigs = mat.eigenvals()
+
+    # Make sure that we have all roots in radical form
+    for x in eigs:
+        if x.has(CRootOf):
+            raise MatrixError(
+                "Jordan normal form is not implemented if the matrix have "
+                "eigenvalues in CRootOf form")
+
+    # most matrices have distinct eigenvalues
+    # and so are diagonalizable.  In this case, don't
+    # do extra work!
+    if len(eigs.keys()) == mat.cols:
+        blocks     = sorted(eigs.keys(), key=default_sort_key)
+        jordan_mat = mat.diag(*blocks)
+
+        if not calc_transform:
+            return restore_floats(jordan_mat)
+
+        jordan_basis = [eig_mat(eig, 1).nullspace()[0]
+                for eig in blocks]
+        basis_mat    = mat.hstack(*jordan_basis)
+
+        return restore_floats(basis_mat, jordan_mat)
+
+    block_structure = []
+
+    for eig in sorted(eigs.keys(), key=default_sort_key):
+        algebraic_multiplicity = eigs[eig]
+        chain = nullity_chain(eig, algebraic_multiplicity)
+        block_sizes = blocks_from_nullity_chain(chain)
+
+        # if block_sizes =       = [a, b, c, ...], then the number of
+        # Jordan blocks of size 1 is a, of size 2 is b, etc.
+        # create an array that has (eig, block_size) with one
+        # entry for each block
+        size_nums = [(i+1, num) for i, num in enumerate(block_sizes)]
+
+        # we expect larger Jordan blocks to come earlier
+        size_nums.reverse()
+
+        block_structure.extend(
+            [(eig, size) for size, num in size_nums for _ in range(num)])
+
+    jordan_form_size = sum(size for eig, size in block_structure)
+
+    if jordan_form_size != M.rows:
+        raise MatrixError(
+            "SymPy had encountered an inconsistent result while "
+            "computing Jordan block. : {}".format(M))
+
+    blocks     = (mat.jordan_block(size=size, eigenvalue=eig) for eig, size in block_structure)
+    jordan_mat = mat.diag(*blocks)
+
+    if not calc_transform:
+        return restore_floats(jordan_mat)
+
+    # For each generalized eigenspace, calculate a basis.
+    # We start by looking for a vector in null( (A - eig*I)**n )
+    # which isn't in null( (A - eig*I)**(n-1) ) where n is
+    # the size of the Jordan block
+    #
+    # Ideally we'd just loop through block_structure and
+    # compute each generalized eigenspace.  However, this
+    # causes a lot of unneeded computation.  Instead, we
+    # go through the eigenvalues separately, since we know
+    # their generalized eigenspaces must have bases that
+    # are linearly independent.
+    jordan_basis = []
+
+    for eig in sorted(eigs.keys(), key=default_sort_key):
+        eig_basis = []
+
+        for block_eig, size in block_structure:
+            if block_eig != eig:
+                continue
+
+            null_big   = (eig_mat(eig, size)).nullspace()
+            null_small = (eig_mat(eig, size - 1)).nullspace()
+
+            # we want to pick something that is in the big basis
+            # and not the small, but also something that is independent
+            # of any other generalized eigenvectors from a different
+            # generalized eigenspace sharing the same eigenvalue.
+            vec      = pick_vec(null_small + eig_basis, null_big)
+            new_vecs = [eig_mat(eig, i).multiply(vec, dotprodsimp=None)
+                    for i in range(size)]
+
+            eig_basis.extend(new_vecs)
+            jordan_basis.extend(reversed(new_vecs))
+
+    basis_mat = mat.hstack(*jordan_basis)
+
+    return restore_floats(basis_mat, jordan_mat)
+
+
+def _left_eigenvects(M, **flags):
+    """Returns left eigenvectors and eigenvalues.
+
+    This function returns the list of triples (eigenval, multiplicity,
+    basis) for the left eigenvectors. Options are the same as for
+    eigenvects(), i.e. the ``**flags`` arguments gets passed directly to
+    eigenvects().
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> M = Matrix([[0, 1, 1], [1, 0, 0], [1, 1, 1]])
+    >>> M.eigenvects()
+    [(-1, 1, [Matrix([
+    [-1],
+    [ 1],
+    [ 0]])]), (0, 1, [Matrix([
+    [ 0],
+    [-1],
+    [ 1]])]), (2, 1, [Matrix([
+    [2/3],
+    [1/3],
+    [  1]])])]
+    >>> M.left_eigenvects()
+    [(-1, 1, [Matrix([[-2, 1, 1]])]), (0, 1, [Matrix([[-1, -1, 1]])]), (2,
+    1, [Matrix([[1, 1, 1]])])]
+
+    """
+
+    eigs = M.transpose().eigenvects(**flags)
+
+    return [(val, mult, [l.transpose() for l in basis]) for val, mult, basis in eigs]
+
+
+def _singular_values(M):
+    """Compute the singular values of a Matrix
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix, Symbol
+    >>> x = Symbol('x', real=True)
+    >>> M = Matrix([[0, 1, 0], [0, x, 0], [-1, 0, 0]])
+    >>> M.singular_values()
+    [sqrt(x**2 + 1), 1, 0]
+
+    See Also
+    ========
+
+    condition_number
+    """
+
+    if M.rows >= M.cols:
+        valmultpairs = M.H.multiply(M).eigenvals()
+    else:
+        valmultpairs = M.multiply(M.H).eigenvals()
+
+    # Expands result from eigenvals into a simple list
+    vals = []
+
+    for k, v in valmultpairs.items():
+        vals += [sqrt(k)] * v  # dangerous! same k in several spots!
+
+    # Pad with zeros if singular values are computed in reverse way,
+    # to give consistent format.
+    if len(vals) < M.cols:
+        vals += [M.zero] * (M.cols - len(vals))
+
+    # sort them in descending order
+    vals.sort(reverse=True, key=default_sort_key)
+
+    return vals

.venv/lib/python3.11/site-packages/sympy/matrices/expressions/__init__.py

@@ -0,0 +1,62 @@
+""" A module which handles Matrix Expressions """
+
+from .slice import MatrixSlice
+from .blockmatrix import BlockMatrix, BlockDiagMatrix, block_collapse, blockcut
+from .companion import CompanionMatrix
+from .funcmatrix import FunctionMatrix
+from .inverse import Inverse
+from .matadd import MatAdd
+from .matexpr import MatrixExpr, MatrixSymbol, matrix_symbols
+from .matmul import MatMul
+from .matpow import MatPow
+from .trace import Trace, trace
+from .determinant import Determinant, det, Permanent, per
+from .transpose import Transpose
+from .adjoint import Adjoint
+from .hadamard import hadamard_product, HadamardProduct, hadamard_power, HadamardPower
+from .diagonal import DiagonalMatrix, DiagonalOf, DiagMatrix, diagonalize_vector
+from .dotproduct import DotProduct
+from .kronecker import kronecker_product, KroneckerProduct, combine_kronecker
+from .permutation import PermutationMatrix, MatrixPermute
+from .sets import MatrixSet
+from .special import ZeroMatrix, Identity, OneMatrix
+
+__all__ = [
+    'MatrixSlice',
+
+    'BlockMatrix', 'BlockDiagMatrix', 'block_collapse', 'blockcut',
+    'FunctionMatrix',
+
+    'CompanionMatrix',
+
+    'Inverse',
+
+    'MatAdd',
+
+    'Identity', 'MatrixExpr', 'MatrixSymbol', 'ZeroMatrix', 'OneMatrix',
+    'matrix_symbols', 'MatrixSet',
+
+    'MatMul',
+
+    'MatPow',
+
+    'Trace', 'trace',
+
+    'Determinant', 'det',
+
+    'Transpose',
+
+    'Adjoint',
+
+    'hadamard_product', 'HadamardProduct', 'hadamard_power', 'HadamardPower',
+
+    'DiagonalMatrix', 'DiagonalOf', 'DiagMatrix', 'diagonalize_vector',
+
+    'DotProduct',
+
+    'kronecker_product', 'KroneckerProduct', 'combine_kronecker',
+
+    'PermutationMatrix', 'MatrixPermute',
+
+    'Permanent', 'per'
+]

.venv/lib/python3.11/site-packages/sympy/matrices/expressions/adjoint.py

@@ -0,0 +1,60 @@
+from sympy.core import Basic
+from sympy.functions import adjoint, conjugate
+from sympy.matrices.expressions.matexpr import MatrixExpr
+
+
+class Adjoint(MatrixExpr):
+    """
+    The Hermitian adjoint of a matrix expression.
+
+    This is a symbolic object that simply stores its argument without
+    evaluating it. To actually compute the adjoint, use the ``adjoint()``
+    function.
+
+    Examples
+    ========
+
+    >>> from sympy import MatrixSymbol, Adjoint, adjoint
+    >>> A = MatrixSymbol('A', 3, 5)
+    >>> B = MatrixSymbol('B', 5, 3)
+    >>> Adjoint(A*B)
+    Adjoint(A*B)
+    >>> adjoint(A*B)
+    Adjoint(B)*Adjoint(A)
+    >>> adjoint(A*B) == Adjoint(A*B)
+    False
+    >>> adjoint(A*B) == Adjoint(A*B).doit()
+    True
+    """
+    is_Adjoint = True
+
+    def doit(self, **hints):
+        arg = self.arg
+        if hints.get('deep', True) and isinstance(arg, Basic):
+            return adjoint(arg.doit(**hints))
+        else:
+            return adjoint(self.arg)
+
+    @property
+    def arg(self):
+        return self.args[0]
+
+    @property
+    def shape(self):
+        return self.arg.shape[::-1]
+
+    def _entry(self, i, j, **kwargs):
+        return conjugate(self.arg._entry(j, i, **kwargs))
+
+    def _eval_adjoint(self):
+        return self.arg
+
+    def _eval_transpose(self):
+        return self.arg.conjugate()
+
+    def _eval_conjugate(self):
+        return self.arg.transpose()
+
+    def _eval_trace(self):
+        from sympy.matrices.expressions.trace import Trace
+        return conjugate(Trace(self.arg))

.venv/lib/python3.11/site-packages/sympy/matrices/expressions/applyfunc.py

@@ -0,0 +1,204 @@
+from sympy.core.expr import ExprBuilder
+from sympy.core.function import (Function, FunctionClass, Lambda)
+from sympy.core.symbol import Dummy
+from sympy.core.sympify import sympify, _sympify
+from sympy.matrices.expressions import MatrixExpr
+from sympy.matrices.matrixbase import MatrixBase
+
+
+class ElementwiseApplyFunction(MatrixExpr):
+    r"""
+    Apply function to a matrix elementwise without evaluating.
+
+    Examples
+    ========
+
+    It can be created by calling ``.applyfunc(<function>)`` on a matrix
+    expression:
+
+    >>> from sympy import MatrixSymbol
+    >>> from sympy.matrices.expressions.applyfunc import ElementwiseApplyFunction
+    >>> from sympy import exp
+    >>> X = MatrixSymbol("X", 3, 3)
+    >>> X.applyfunc(exp)
+    Lambda(_d, exp(_d)).(X)
+
+    Otherwise using the class constructor:
+
+    >>> from sympy import eye
+    >>> expr = ElementwiseApplyFunction(exp, eye(3))
+    >>> expr
+    Lambda(_d, exp(_d)).(Matrix([
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1]]))
+    >>> expr.doit()
+    Matrix([
+    [E, 1, 1],
+    [1, E, 1],
+    [1, 1, E]])
+
+    Notice the difference with the real mathematical functions:
+
+    >>> exp(eye(3))
+    Matrix([
+    [E, 0, 0],
+    [0, E, 0],
+    [0, 0, E]])
+    """
+
+    def __new__(cls, function, expr):
+        expr = _sympify(expr)
+        if not expr.is_Matrix:
+            raise ValueError("{} must be a matrix instance.".format(expr))
+
+        if expr.shape == (1, 1):
+            # Check if the function returns a matrix, in that case, just apply
+            # the function instead of creating an ElementwiseApplyFunc object:
+            ret = function(expr)
+            if isinstance(ret, MatrixExpr):
+                return ret
+
+        if not isinstance(function, (FunctionClass, Lambda)):
+            d = Dummy('d')
+            function = Lambda(d, function(d))
+
+        function = sympify(function)
+        if not isinstance(function, (FunctionClass, Lambda)):
+            raise ValueError(
+                "{} should be compatible with SymPy function classes."
+                .format(function))
+
+        if 1 not in function.nargs:
+            raise ValueError(
+                '{} should be able to accept 1 arguments.'.format(function))
+
+        if not isinstance(function, Lambda):
+            d = Dummy('d')
+            function = Lambda(d, function(d))
+
+        obj = MatrixExpr.__new__(cls, function, expr)
+        return obj
+
+    @property
+    def function(self):
+        return self.args[0]
+
+    @property
+    def expr(self):
+        return self.args[1]
+
+    @property
+    def shape(self):
+        return self.expr.shape
+
+    def doit(self, **hints):
+        deep = hints.get("deep", True)
+        expr = self.expr
+        if deep:
+            expr = expr.doit(**hints)
+        function = self.function
+        if isinstance(function, Lambda) and function.is_identity:
+            # This is a Lambda containing the identity function.
+            return expr
+        if isinstance(expr, MatrixBase):
+            return expr.applyfunc(self.function)
+        elif isinstance(expr, ElementwiseApplyFunction):
+            return ElementwiseApplyFunction(
+                lambda x: self.function(expr.function(x)),
+                expr.expr
+            ).doit(**hints)
+        else:
+            return self
+
+    def _entry(self, i, j, **kwargs):
+        return self.function(self.expr._entry(i, j, **kwargs))
+
+    def _get_function_fdiff(self):
+        d = Dummy("d")
+        function = self.function(d)
+        fdiff = function.diff(d)
+        if isinstance(fdiff, Function):
+            fdiff = type(fdiff)
+        else:
+            fdiff = Lambda(d, fdiff)
+        return fdiff
+
+    def _eval_derivative(self, x):
+        from sympy.matrices.expressions.hadamard import hadamard_product
+        dexpr = self.expr.diff(x)
+        fdiff = self._get_function_fdiff()
+        return hadamard_product(
+            dexpr,
+            ElementwiseApplyFunction(fdiff, self.expr)
+        )
+
+    def _eval_derivative_matrix_lines(self, x):
+        from sympy.matrices.expressions.special import Identity
+        from sympy.tensor.array.expressions.array_expressions import ArrayContraction
+        from sympy.tensor.array.expressions.array_expressions import ArrayDiagonal
+        from sympy.tensor.array.expressions.array_expressions import ArrayTensorProduct
+
+        fdiff = self._get_function_fdiff()
+        lr = self.expr._eval_derivative_matrix_lines(x)
+        ewdiff = ElementwiseApplyFunction(fdiff, self.expr)
+        if 1 in x.shape:
+            # Vector:
+            iscolumn = self.shape[1] == 1
+            for i in lr:
+                if iscolumn:
+                    ptr1 = i.first_pointer
+                    ptr2 = Identity(self.shape[1])
+                else:
+                    ptr1 = Identity(self.shape[0])
+                    ptr2 = i.second_pointer
+
+                subexpr = ExprBuilder(
+                    ArrayDiagonal,
+                    [
+                        ExprBuilder(
+                            ArrayTensorProduct,
+                            [
+                                ewdiff,
+                                ptr1,
+                                ptr2,
+                            ]
+                        ),
+                        (0, 2) if iscolumn else (1, 4)
+                    ],
+                    validator=ArrayDiagonal._validate
+                )
+                i._lines = [subexpr]
+                i._first_pointer_parent = subexpr.args[0].args
+                i._first_pointer_index = 1
+                i._second_pointer_parent = subexpr.args[0].args
+                i._second_pointer_index = 2
+        else:
+            # Matrix case:
+            for i in lr:
+                ptr1 = i.first_pointer
+                ptr2 = i.second_pointer
+                newptr1 = Identity(ptr1.shape[1])
+                newptr2 = Identity(ptr2.shape[1])
+                subexpr = ExprBuilder(
+                    ArrayContraction,
+                    [
+                        ExprBuilder(
+                            ArrayTensorProduct,
+                            [ptr1, newptr1, ewdiff, ptr2, newptr2]
+                        ),
+                        (1, 2, 4),
+                        (5, 7, 8),
+                    ],
+                    validator=ArrayContraction._validate
+                )
+                i._first_pointer_parent = subexpr.args[0].args
+                i._first_pointer_index = 1
+                i._second_pointer_parent = subexpr.args[0].args
+                i._second_pointer_index = 4
+                i._lines = [subexpr]
+        return lr
+
+    def _eval_transpose(self):
+        from sympy.matrices.expressions.transpose import Transpose
+        return self.func(self.function, Transpose(self.expr).doit())

.venv/lib/python3.11/site-packages/sympy/matrices/expressions/blockmatrix.py

@@ -0,0 +1,980 @@
+from sympy.assumptions.ask import (Q, ask)
+from sympy.core import Basic, Add, Mul, S
+from sympy.core.sympify import _sympify
+from sympy.functions import adjoint
+from sympy.functions.elementary.complexes import re, im
+from sympy.strategies import typed, exhaust, condition, do_one, unpack
+from sympy.strategies.traverse import bottom_up
+from sympy.utilities.iterables import is_sequence, sift
+from sympy.utilities.misc import filldedent
+
+from sympy.matrices import Matrix, ShapeError
+from sympy.matrices.exceptions import NonInvertibleMatrixError
+from sympy.matrices.expressions.determinant import det, Determinant
+from sympy.matrices.expressions.inverse import Inverse
+from sympy.matrices.expressions.matadd import MatAdd
+from sympy.matrices.expressions.matexpr import MatrixExpr, MatrixElement
+from sympy.matrices.expressions.matmul import MatMul
+from sympy.matrices.expressions.matpow import MatPow
+from sympy.matrices.expressions.slice import MatrixSlice
+from sympy.matrices.expressions.special import ZeroMatrix, Identity
+from sympy.matrices.expressions.trace import trace
+from sympy.matrices.expressions.transpose import Transpose, transpose
+
+
+class BlockMatrix(MatrixExpr):
+    """A BlockMatrix is a Matrix comprised of other matrices.
+
+    The submatrices are stored in a SymPy Matrix object but accessed as part of
+    a Matrix Expression
+
+    >>> from sympy import (MatrixSymbol, BlockMatrix, symbols,
+    ...     Identity, ZeroMatrix, block_collapse)
+    >>> n,m,l = symbols('n m l')
+    >>> X = MatrixSymbol('X', n, n)
+    >>> Y = MatrixSymbol('Y', m, m)
+    >>> Z = MatrixSymbol('Z', n, m)
+    >>> B = BlockMatrix([[X, Z], [ZeroMatrix(m,n), Y]])
+    >>> print(B)
+    Matrix([
+    [X, Z],
+    [0, Y]])
+
+    >>> C = BlockMatrix([[Identity(n), Z]])
+    >>> print(C)
+    Matrix([[I, Z]])
+
+    >>> print(block_collapse(C*B))
+    Matrix([[X, Z + Z*Y]])
+
+    Some matrices might be comprised of rows of blocks with
+    the matrices in each row having the same height and the
+    rows all having the same total number of columns but
+    not having the same number of columns for each matrix
+    in each row. In this case, the matrix is not a block
+    matrix and should be instantiated by Matrix.
+
+    >>> from sympy import ones, Matrix
+    >>> dat = [
+    ... [ones(3,2), ones(3,3)*2],
+    ... [ones(2,3)*3, ones(2,2)*4]]
+    ...
+    >>> BlockMatrix(dat)
+    Traceback (most recent call last):
+    ...
+    ValueError:
+    Although this matrix is comprised of blocks, the blocks do not fill
+    the matrix in a size-symmetric fashion. To create a full matrix from
+    these arguments, pass them directly to Matrix.
+    >>> Matrix(dat)
+    Matrix([
+    [1, 1, 2, 2, 2],
+    [1, 1, 2, 2, 2],
+    [1, 1, 2, 2, 2],
+    [3, 3, 3, 4, 4],
+    [3, 3, 3, 4, 4]])
+
+    See Also
+    ========
+    sympy.matrices.matrixbase.MatrixBase.irregular
+    """
+    def __new__(cls, *args, **kwargs):
+        from sympy.matrices.immutable import ImmutableDenseMatrix
+        isMat = lambda i: getattr(i, 'is_Matrix', False)
+        if len(args) != 1 or \
+                not is_sequence(args[0]) or \
+                len({isMat(r) for r in args[0]}) != 1:
+            raise ValueError(filldedent('''
+                expecting a sequence of 1 or more rows
+                containing Matrices.'''))
+        rows = args[0] if args else []
+        if not isMat(rows):
+            if rows and isMat(rows[0]):
+                rows = [rows]  # rows is not list of lists or []
+            # regularity check
+            # same number of matrices in each row
+            blocky = ok = len({len(r) for r in rows}) == 1
+            if ok:
+                # same number of rows for each matrix in a row
+                for r in rows:
+                    ok = len({i.rows for i in r}) == 1
+                    if not ok:
+                        break
+                blocky = ok
+                if ok:
+                    # same number of cols for each matrix in each col
+                    for c in range(len(rows[0])):
+                        ok = len({rows[i][c].cols
+                            for i in range(len(rows))}) == 1
+                        if not ok:
+                            break
+            if not ok:
+                # same total cols in each row
+                ok = len({
+                    sum(i.cols for i in r) for r in rows}) == 1
+                if blocky and ok:
+                    raise ValueError(filldedent('''
+                        Although this matrix is comprised of blocks,
+                        the blocks do not fill the matrix in a
+                        size-symmetric fashion. To create a full matrix
+                        from these arguments, pass them directly to
+                        Matrix.'''))
+                raise ValueError(filldedent('''
+                    When there are not the same number of rows in each
+                    row's matrices or there are not the same number of
+                    total columns in each row, the matrix is not a
+                    block matrix. If this matrix is known to consist of
+                    blocks fully filling a 2-D space then see
+                    Matrix.irregular.'''))
+        mat = ImmutableDenseMatrix(rows, evaluate=False)
+        obj = Basic.__new__(cls, mat)
+        return obj
+
+    @property
+    def shape(self):
+        numrows = numcols = 0
+        M = self.blocks
+        for i in range(M.shape[0]):
+            numrows += M[i, 0].shape[0]
+        for i in range(M.shape[1]):
+            numcols += M[0, i].shape[1]
+        return (numrows, numcols)
+
+    @property
+    def blockshape(self):
+        return self.blocks.shape
+
+    @property
+    def blocks(self):
+        return self.args[0]
+
+    @property
+    def rowblocksizes(self):
+        return [self.blocks[i, 0].rows for i in range(self.blockshape[0])]
+
+    @property
+    def colblocksizes(self):
+        return [self.blocks[0, i].cols for i in range(self.blockshape[1])]
+
+    def structurally_equal(self, other):
+        return (isinstance(other, BlockMatrix)
+            and self.shape == other.shape
+            and self.blockshape == other.blockshape
+            and self.rowblocksizes == other.rowblocksizes
+            and self.colblocksizes == other.colblocksizes)
+
+    def _blockmul(self, other):
+        if (isinstance(other, BlockMatrix) and
+                self.colblocksizes == other.rowblocksizes):
+            return BlockMatrix(self.blocks*other.blocks)
+
+        return self * other
+
+    def _blockadd(self, other):
+        if (isinstance(other, BlockMatrix)
+                and self.structurally_equal(other)):
+            return BlockMatrix(self.blocks + other.blocks)
+
+        return self + other
+
+    def _eval_transpose(self):
+        # Flip all the individual matrices
+        matrices = [transpose(matrix) for matrix in self.blocks]
+        # Make a copy
+        M = Matrix(self.blockshape[0], self.blockshape[1], matrices)
+        # Transpose the block structure
+        M = M.transpose()
+        return BlockMatrix(M)
+
+    def _eval_adjoint(self):
+        # Adjoint all the individual matrices
+        matrices = [adjoint(matrix) for matrix in self.blocks]
+        # Make a copy
+        M = Matrix(self.blockshape[0], self.blockshape[1], matrices)
+        # Transpose the block structure
+        M = M.transpose()
+        return BlockMatrix(M)
+
+    def _eval_trace(self):
+        if self.rowblocksizes == self.colblocksizes:
+            blocks = [self.blocks[i, i] for i in range(self.blockshape[0])]
+            return Add(*[trace(block) for block in blocks])
+
+    def _eval_determinant(self):
+        if self.blockshape == (1, 1):
+            return det(self.blocks[0, 0])
+        if self.blockshape == (2, 2):
+            [[A, B],
+             [C, D]] = self.blocks.tolist()
+            if ask(Q.invertible(A)):
+                return det(A)*det(D - C*A.I*B)
+            elif ask(Q.invertible(D)):
+                return det(D)*det(A - B*D.I*C)
+        return Determinant(self)
+
+    def _eval_as_real_imag(self):
+        real_matrices = [re(matrix) for matrix in self.blocks]
+        real_matrices = Matrix(self.blockshape[0], self.blockshape[1], real_matrices)
+
+        im_matrices = [im(matrix) for matrix in self.blocks]
+        im_matrices = Matrix(self.blockshape[0], self.blockshape[1], im_matrices)
+
+        return (BlockMatrix(real_matrices), BlockMatrix(im_matrices))
+
+    def _eval_derivative(self, x):
+        return BlockMatrix(self.blocks.diff(x))
+
+    def transpose(self):
+        """Return transpose of matrix.
+
+        Examples
+        ========
+
+        >>> from sympy import MatrixSymbol, BlockMatrix, ZeroMatrix
+        >>> from sympy.abc import m, n
+        >>> X = MatrixSymbol('X', n, n)
+        >>> Y = MatrixSymbol('Y', m, m)
+        >>> Z = MatrixSymbol('Z', n, m)
+        >>> B = BlockMatrix([[X, Z], [ZeroMatrix(m,n), Y]])
+        >>> B.transpose()
+        Matrix([
+        [X.T,  0],
+        [Z.T, Y.T]])
+        >>> _.transpose()
+        Matrix([
+        [X, Z],
+        [0, Y]])
+        """
+        return self._eval_transpose()
+
+    def schur(self, mat = 'A', generalized = False):
+        """Return the Schur Complement of the 2x2 BlockMatrix
+
+        Parameters
+        ==========
+
+        mat : String, optional
+            The matrix with respect to which the
+            Schur Complement is calculated. 'A' is
+            used by default
+
+        generalized : bool, optional
+            If True, returns the generalized Schur
+            Component which uses Moore-Penrose Inverse
+
+        Examples
+        ========
+
+        >>> from sympy import symbols, MatrixSymbol, BlockMatrix
+        >>> m, n = symbols('m n')
+        >>> A = MatrixSymbol('A', n, n)
+        >>> B = MatrixSymbol('B', n, m)
+        >>> C = MatrixSymbol('C', m, n)
+        >>> D = MatrixSymbol('D', m, m)
+        >>> X = BlockMatrix([[A, B], [C, D]])
+
+        The default Schur Complement is evaluated with "A"
+
+        >>> X.schur()
+        -C*A**(-1)*B + D
+        >>> X.schur('D')
+        A - B*D**(-1)*C
+
+        Schur complement with non-invertible matrices is not
+        defined. Instead, the generalized Schur complement can
+        be calculated which uses the Moore-Penrose Inverse. To
+        achieve this, `generalized` must be set to `True`
+
+        >>> X.schur('B', generalized=True)
+        C - D*(B.T*B)**(-1)*B.T*A
+        >>> X.schur('C', generalized=True)
+        -A*(C.T*C)**(-1)*C.T*D + B
+
+        Returns
+        =======
+
+        M : Matrix
+            The Schur Complement Matrix
+
+        Raises
+        ======
+
+        ShapeError
+            If the block matrix is not a 2x2 matrix
+
+        NonInvertibleMatrixError
+            If given matrix is non-invertible
+
+        References
+        ==========
+
+        .. [1] Wikipedia Article on Schur Component : https://en.wikipedia.org/wiki/Schur_complement
+
+        See Also
+        ========
+
+        sympy.matrices.matrixbase.MatrixBase.pinv
+        """
+
+        if self.blockshape == (2, 2):
+            [[A, B],
+             [C, D]] = self.blocks.tolist()
+            d={'A' : A, 'B' : B, 'C' : C, 'D' : D}
+            try:
+                inv = (d[mat].T*d[mat]).inv()*d[mat].T if generalized else d[mat].inv()
+                if mat == 'A':
+                    return D - C * inv * B
+                elif mat == 'B':
+                    return C - D * inv * A
+                elif mat == 'C':
+                    return B - A * inv * D
+                elif mat == 'D':
+                    return A - B * inv * C
+                #For matrices where no sub-matrix is square
+                return self
+            except NonInvertibleMatrixError:
+                raise NonInvertibleMatrixError('The given matrix is not invertible. Please set generalized=True \
+            to compute the generalized Schur Complement which uses Moore-Penrose Inverse')
+        else:
+            raise ShapeError('Schur Complement can only be calculated for 2x2 block matrices')
+
+    def LDUdecomposition(self):
+        """Returns the Block LDU decomposition of
+        a 2x2 Block Matrix
+
+        Returns
+        =======
+
+        (L, D, U) : Matrices
+            L : Lower Diagonal Matrix
+            D : Diagonal Matrix
+            U : Upper Diagonal Matrix
+
+        Examples
+        ========
+
+        >>> from sympy import symbols, MatrixSymbol, BlockMatrix, block_collapse
+        >>> m, n = symbols('m n')
+        >>> A = MatrixSymbol('A', n, n)
+        >>> B = MatrixSymbol('B', n, m)
+        >>> C = MatrixSymbol('C', m, n)
+        >>> D = MatrixSymbol('D', m, m)
+        >>> X = BlockMatrix([[A, B], [C, D]])
+        >>> L, D, U = X.LDUdecomposition()
+        >>> block_collapse(L*D*U)
+        Matrix([
+        [A, B],
+        [C, D]])
+
+        Raises
+        ======
+
+        ShapeError
+            If the block matrix is not a 2x2 matrix
+
+        NonInvertibleMatrixError
+            If the matrix "A" is non-invertible
+
+        See Also
+        ========
+        sympy.matrices.expressions.blockmatrix.BlockMatrix.UDLdecomposition
+        sympy.matrices.expressions.blockmatrix.BlockMatrix.LUdecomposition
+        """
+        if self.blockshape == (2,2):
+            [[A, B],
+             [C, D]] = self.blocks.tolist()
+            try:
+                AI = A.I
+            except NonInvertibleMatrixError:
+                raise NonInvertibleMatrixError('Block LDU decomposition cannot be calculated when\
+                    "A" is singular')
+            Ip = Identity(B.shape[0])
+            Iq = Identity(B.shape[1])
+            Z = ZeroMatrix(*B.shape)
+            L = BlockMatrix([[Ip, Z], [C*AI, Iq]])
+            D = BlockDiagMatrix(A, self.schur())
+            U = BlockMatrix([[Ip, AI*B],[Z.T, Iq]])
+            return L, D, U
+        else:
+            raise ShapeError("Block LDU decomposition is supported only for 2x2 block matrices")
+
+    def UDLdecomposition(self):
+        """Returns the Block UDL decomposition of
+        a 2x2 Block Matrix
+
+        Returns
+        =======
+
+        (U, D, L) : Matrices
+            U : Upper Diagonal Matrix
+            D : Diagonal Matrix
+            L : Lower Diagonal Matrix
+
+        Examples
+        ========
+
+        >>> from sympy import symbols, MatrixSymbol, BlockMatrix, block_collapse
+        >>> m, n = symbols('m n')
+        >>> A = MatrixSymbol('A', n, n)
+        >>> B = MatrixSymbol('B', n, m)
+        >>> C = MatrixSymbol('C', m, n)
+        >>> D = MatrixSymbol('D', m, m)
+        >>> X = BlockMatrix([[A, B], [C, D]])
+        >>> U, D, L = X.UDLdecomposition()
+        >>> block_collapse(U*D*L)
+        Matrix([
+        [A, B],
+        [C, D]])
+
+        Raises
+        ======
+
+        ShapeError
+            If the block matrix is not a 2x2 matrix
+
+        NonInvertibleMatrixError
+            If the matrix "D" is non-invertible
+
+        See Also
+        ========
+        sympy.matrices.expressions.blockmatrix.BlockMatrix.LDUdecomposition
+        sympy.matrices.expressions.blockmatrix.BlockMatrix.LUdecomposition
+        """
+        if self.blockshape == (2,2):
+            [[A, B],
+             [C, D]] = self.blocks.tolist()
+            try:
+                DI = D.I
+            except NonInvertibleMatrixError:
+                raise NonInvertibleMatrixError('Block UDL decomposition cannot be calculated when\
+                    "D" is singular')
+            Ip = Identity(A.shape[0])
+            Iq = Identity(B.shape[1])
+            Z = ZeroMatrix(*B.shape)
+            U = BlockMatrix([[Ip, B*DI], [Z.T, Iq]])
+            D = BlockDiagMatrix(self.schur('D'), D)
+            L = BlockMatrix([[Ip, Z],[DI*C, Iq]])
+            return U, D, L
+        else:
+            raise ShapeError("Block UDL decomposition is supported only for 2x2 block matrices")
+
+    def LUdecomposition(self):
+        """Returns the Block LU decomposition of
+        a 2x2 Block Matrix
+
+        Returns
+        =======
+
+        (L, U) : Matrices
+            L : Lower Diagonal Matrix
+            U : Upper Diagonal Matrix
+
+        Examples
+        ========
+
+        >>> from sympy import symbols, MatrixSymbol, BlockMatrix, block_collapse
+        >>> m, n = symbols('m n')
+        >>> A = MatrixSymbol('A', n, n)
+        >>> B = MatrixSymbol('B', n, m)
+        >>> C = MatrixSymbol('C', m, n)
+        >>> D = MatrixSymbol('D', m, m)
+        >>> X = BlockMatrix([[A, B], [C, D]])
+        >>> L, U = X.LUdecomposition()
+        >>> block_collapse(L*U)
+        Matrix([
+        [A, B],
+        [C, D]])
+
+        Raises
+        ======
+
+        ShapeError
+            If the block matrix is not a 2x2 matrix
+
+        NonInvertibleMatrixError
+            If the matrix "A" is non-invertible
+
+        See Also
+        ========
+        sympy.matrices.expressions.blockmatrix.BlockMatrix.UDLdecomposition
+        sympy.matrices.expressions.blockmatrix.BlockMatrix.LDUdecomposition
+        """
+        if self.blockshape == (2,2):
+            [[A, B],
+             [C, D]] = self.blocks.tolist()
+            try:
+                A = A**S.Half
+                AI = A.I
+            except NonInvertibleMatrixError:
+                raise NonInvertibleMatrixError('Block LU decomposition cannot be calculated when\
+                    "A" is singular')
+            Z = ZeroMatrix(*B.shape)
+            Q = self.schur()**S.Half
+            L = BlockMatrix([[A, Z], [C*AI, Q]])
+            U = BlockMatrix([[A, AI*B],[Z.T, Q]])
+            return L, U
+        else:
+            raise ShapeError("Block LU decomposition is supported only for 2x2 block matrices")
+
+    def _entry(self, i, j, **kwargs):
+        # Find row entry
+        orig_i, orig_j = i, j
+        for row_block, numrows in enumerate(self.rowblocksizes):
+            cmp = i < numrows
+            if cmp == True:
+                break
+            elif cmp == False:
+                i -= numrows
+            elif row_block < self.blockshape[0] - 1:
+                # Can't tell which block and it's not the last one, return unevaluated
+                return MatrixElement(self, orig_i, orig_j)
+        for col_block, numcols in enumerate(self.colblocksizes):
+            cmp = j < numcols
+            if cmp == True:
+                break
+            elif cmp == False:
+                j -= numcols
+            elif col_block < self.blockshape[1] - 1:
+                return MatrixElement(self, orig_i, orig_j)
+        return self.blocks[row_block, col_block][i, j]
+
+    @property
+    def is_Identity(self):
+        if self.blockshape[0] != self.blockshape[1]:
+            return False
+        for i in range(self.blockshape[0]):
+            for j in range(self.blockshape[1]):
+                if i==j and not self.blocks[i, j].is_Identity:
+                    return False
+                if i!=j and not self.blocks[i, j].is_ZeroMatrix:
+                    return False
+        return True
+
+    @property
+    def is_structurally_symmetric(self):
+        return self.rowblocksizes == self.colblocksizes
+
+    def equals(self, other):
+        if self == other:
+            return True
+        if (isinstance(other, BlockMatrix) and self.blocks == other.blocks):
+            return True
+        return super().equals(other)
+
+
+class BlockDiagMatrix(BlockMatrix):
+    """A sparse matrix with block matrices along its diagonals
+
+    Examples
+    ========
+
+    >>> from sympy import MatrixSymbol, BlockDiagMatrix, symbols
+    >>> n, m, l = symbols('n m l')
+    >>> X = MatrixSymbol('X', n, n)
+    >>> Y = MatrixSymbol('Y', m, m)
+    >>> BlockDiagMatrix(X, Y)
+    Matrix([
+    [X, 0],
+    [0, Y]])
+
+    Notes
+    =====
+
+    If you want to get the individual diagonal blocks, use
+    :meth:`get_diag_blocks`.
+
+    See Also
+    ========
+
+    sympy.matrices.dense.diag
+    """
+    def __new__(cls, *mats):
+        return Basic.__new__(BlockDiagMatrix, *[_sympify(m) for m in mats])
+
+    @property
+    def diag(self):
+        return self.args
+
+    @property
+    def blocks(self):
+        from sympy.matrices.immutable import ImmutableDenseMatrix
+        mats = self.args
+        data = [[mats[i] if i == j else ZeroMatrix(mats[i].rows, mats[j].cols)
+                        for j in range(len(mats))]
+                        for i in range(len(mats))]
+        return ImmutableDenseMatrix(data, evaluate=False)
+
+    @property
+    def shape(self):
+        return (sum(block.rows for block in self.args),
+                sum(block.cols for block in self.args))
+
+    @property
+    def blockshape(self):
+        n = len(self.args)
+        return (n, n)
+
+    @property
+    def rowblocksizes(self):
+        return [block.rows for block in self.args]
+
+    @property
+    def colblocksizes(self):
+        return [block.cols for block in self.args]
+
+    def _all_square_blocks(self):
+        """Returns true if all blocks are square"""
+        return all(mat.is_square for mat in self.args)
+
+    def _eval_determinant(self):
+        if self._all_square_blocks():
+            return Mul(*[det(mat) for mat in self.args])
+        # At least one block is non-square.  Since the entire matrix must be square we know there must
+        # be at least two blocks in this matrix, in which case the entire matrix is necessarily rank-deficient
+        return S.Zero
+
+    def _eval_inverse(self, expand='ignored'):
+        if self._all_square_blocks():
+            return BlockDiagMatrix(*[mat.inverse() for mat in self.args])
+        # See comment in _eval_determinant()
+        raise NonInvertibleMatrixError('Matrix det == 0; not invertible.')
+
+    def _eval_transpose(self):
+        return BlockDiagMatrix(*[mat.transpose() for mat in self.args])
+
+    def _blockmul(self, other):
+        if (isinstance(other, BlockDiagMatrix) and
+                self.colblocksizes == other.rowblocksizes):
+            return BlockDiagMatrix(*[a*b for a, b in zip(self.args, other.args)])
+        else:
+            return BlockMatrix._blockmul(self, other)
+
+    def _blockadd(self, other):
+        if (isinstance(other, BlockDiagMatrix) and
+                self.blockshape == other.blockshape and
+                self.rowblocksizes == other.rowblocksizes and
+                self.colblocksizes == other.colblocksizes):
+            return BlockDiagMatrix(*[a + b for a, b in zip(self.args, other.args)])
+        else:
+            return BlockMatrix._blockadd(self, other)
+
+    def get_diag_blocks(self):
+        """Return the list of diagonal blocks of the matrix.
+
+        Examples
+        ========
+
+        >>> from sympy import BlockDiagMatrix, Matrix
+
+        >>> A = Matrix([[1, 2], [3, 4]])
+        >>> B = Matrix([[5, 6], [7, 8]])
+        >>> M = BlockDiagMatrix(A, B)
+
+        How to get diagonal blocks from the block diagonal matrix:
+
+        >>> diag_blocks = M.get_diag_blocks()
+        >>> diag_blocks[0]
+        Matrix([
+        [1, 2],
+        [3, 4]])
+        >>> diag_blocks[1]
+        Matrix([
+        [5, 6],
+        [7, 8]])
+        """
+        return self.args
+
+
+def block_collapse(expr):
+    """Evaluates a block matrix expression
+
+    >>> from sympy import MatrixSymbol, BlockMatrix, symbols, Identity, ZeroMatrix, block_collapse
+    >>> n,m,l = symbols('n m l')
+    >>> X = MatrixSymbol('X', n, n)
+    >>> Y = MatrixSymbol('Y', m, m)
+    >>> Z = MatrixSymbol('Z', n, m)
+    >>> B = BlockMatrix([[X, Z], [ZeroMatrix(m, n), Y]])
+    >>> print(B)
+    Matrix([
+    [X, Z],
+    [0, Y]])
+
+    >>> C = BlockMatrix([[Identity(n), Z]])
+    >>> print(C)
+    Matrix([[I, Z]])
+
+    >>> print(block_collapse(C*B))
+    Matrix([[X, Z + Z*Y]])
+    """
+    from sympy.strategies.util import expr_fns
+
+    hasbm = lambda expr: isinstance(expr, MatrixExpr) and expr.has(BlockMatrix)
+
+    conditioned_rl = condition(
+        hasbm,
+        typed(
+            {MatAdd: do_one(bc_matadd, bc_block_plus_ident),
+             MatMul: do_one(bc_matmul, bc_dist),
+             MatPow: bc_matmul,
+             Transpose: bc_transpose,
+             Inverse: bc_inverse,
+             BlockMatrix: do_one(bc_unpack, deblock)}
+        )
+    )
+
+    rule = exhaust(
+        bottom_up(
+            exhaust(conditioned_rl),
+            fns=expr_fns
+        )
+    )
+
+    result = rule(expr)
+    doit = getattr(result, 'doit', None)
+    if doit is not None:
+        return doit()
+    else:
+        return result
+
+def bc_unpack(expr):
+    if expr.blockshape == (1, 1):
+        return expr.blocks[0, 0]
+    return expr
+
+def bc_matadd(expr):
+    args = sift(expr.args, lambda M: isinstance(M, BlockMatrix))
+    blocks = args[True]
+    if not blocks:
+        return expr
+
+    nonblocks = args[False]
+    block = blocks[0]
+    for b in blocks[1:]:
+        block = block._blockadd(b)
+    if nonblocks:
+        return MatAdd(*nonblocks) + block
+    else:
+        return block
+
+def bc_block_plus_ident(expr):
+    idents = [arg for arg in expr.args if arg.is_Identity]
+    if not idents:
+        return expr
+
+    blocks = [arg for arg in expr.args if isinstance(arg, BlockMatrix)]
+    if (blocks and all(b.structurally_equal(blocks[0]) for b in blocks)
+               and blocks[0].is_structurally_symmetric):
+        block_id = BlockDiagMatrix(*[Identity(k)
+                                        for k in blocks[0].rowblocksizes])
+        rest = [arg for arg in expr.args if not arg.is_Identity and not isinstance(arg, BlockMatrix)]
+        return MatAdd(block_id * len(idents), *blocks, *rest).doit()
+
+    return expr
+
+def bc_dist(expr):
+    """ Turn  a*[X, Y] into [a*X, a*Y] """
+    factor, mat = expr.as_coeff_mmul()
+    if factor == 1:
+        return expr
+
+    unpacked = unpack(mat)
+
+    if isinstance(unpacked, BlockDiagMatrix):
+        B = unpacked.diag
+        new_B = [factor * mat for mat in B]
+        return BlockDiagMatrix(*new_B)
+    elif isinstance(unpacked, BlockMatrix):
+        B = unpacked.blocks
+        new_B = [
+            [factor * B[i, j] for j in range(B.cols)] for i in range(B.rows)]
+        return BlockMatrix(new_B)
+    return expr
+
+
+def bc_matmul(expr):
+    if isinstance(expr, MatPow):
+        if expr.args[1].is_Integer and expr.args[1] > 0:
+            factor, matrices = 1, [expr.args[0]]*expr.args[1]
+        else:
+            return expr
+    else:
+        factor, matrices = expr.as_coeff_matrices()
+
+    i = 0
+    while (i+1 < len(matrices)):
+        A, B = matrices[i:i+2]
+        if isinstance(A, BlockMatrix) and isinstance(B, BlockMatrix):
+            matrices[i] = A._blockmul(B)
+            matrices.pop(i+1)
+        elif isinstance(A, BlockMatrix):
+            matrices[i] = A._blockmul(BlockMatrix([[B]]))
+            matrices.pop(i+1)
+        elif isinstance(B, BlockMatrix):
+            matrices[i] = BlockMatrix([[A]])._blockmul(B)
+            matrices.pop(i+1)
+        else:
+            i+=1
+    return MatMul(factor, *matrices).doit()
+
+def bc_transpose(expr):
+    collapse = block_collapse(expr.arg)
+    return collapse._eval_transpose()
+
+
+def bc_inverse(expr):
+    if isinstance(expr.arg, BlockDiagMatrix):
+        return expr.inverse()
+
+    expr2 = blockinverse_1x1(expr)
+    if expr != expr2:
+        return expr2
+    return blockinverse_2x2(Inverse(reblock_2x2(expr.arg)))
+
+def blockinverse_1x1(expr):
+    if isinstance(expr.arg, BlockMatrix) and expr.arg.blockshape == (1, 1):
+        mat = Matrix([[expr.arg.blocks[0].inverse()]])
+        return BlockMatrix(mat)
+    return expr
+
+
+def blockinverse_2x2(expr):
+    if isinstance(expr.arg, BlockMatrix) and expr.arg.blockshape == (2, 2):
+        # See: Inverses of 2x2 Block Matrices, Tzon-Tzer Lu and Sheng-Hua Shiou
+        [[A, B],
+         [C, D]] = expr.arg.blocks.tolist()
+
+        formula = _choose_2x2_inversion_formula(A, B, C, D)
+        if formula != None:
+            MI = expr.arg.schur(formula).I
+        if formula == 'A':
+            AI = A.I
+            return BlockMatrix([[AI + AI * B * MI * C * AI, -AI * B * MI], [-MI * C * AI, MI]])
+        if formula == 'B':
+            BI = B.I
+            return BlockMatrix([[-MI * D * BI, MI], [BI + BI * A * MI * D * BI, -BI * A * MI]])
+        if formula == 'C':
+            CI = C.I
+            return BlockMatrix([[-CI * D * MI, CI + CI * D * MI * A * CI], [MI, -MI * A * CI]])
+        if formula == 'D':
+            DI = D.I
+            return BlockMatrix([[MI, -MI * B * DI], [-DI * C * MI, DI + DI * C * MI * B * DI]])
+
+    return expr
+
+
+def _choose_2x2_inversion_formula(A, B, C, D):
+    """
+    Assuming [[A, B], [C, D]] would form a valid square block matrix, find
+    which of the classical 2x2 block matrix inversion formulas would be
+    best suited.
+
+    Returns 'A', 'B', 'C', 'D' to represent the algorithm involving inversion
+    of the given argument or None if the matrix cannot be inverted using
+    any of those formulas.
+    """
+    # Try to find a known invertible matrix.  Note that the Schur complement
+    # is currently not being considered for this
+    A_inv = ask(Q.invertible(A))
+    if A_inv == True:
+        return 'A'
+    B_inv = ask(Q.invertible(B))
+    if B_inv == True:
+        return 'B'
+    C_inv = ask(Q.invertible(C))
+    if C_inv == True:
+        return 'C'
+    D_inv = ask(Q.invertible(D))
+    if D_inv == True:
+        return 'D'
+    # Otherwise try to find a matrix that isn't known to be non-invertible
+    if A_inv != False:
+        return 'A'
+    if B_inv != False:
+        return 'B'
+    if C_inv != False:
+        return 'C'
+    if D_inv != False:
+        return 'D'
+    return None
+
+
+def deblock(B):
+    """ Flatten a BlockMatrix of BlockMatrices """
+    if not isinstance(B, BlockMatrix) or not B.blocks.has(BlockMatrix):
+        return B
+    wrap = lambda x: x if isinstance(x, BlockMatrix) else BlockMatrix([[x]])
+    bb = B.blocks.applyfunc(wrap)  # everything is a block
+
+    try:
+        MM = Matrix(0, sum(bb[0, i].blocks.shape[1] for i in range(bb.shape[1])), [])
+        for row in range(0, bb.shape[0]):
+            M = Matrix(bb[row, 0].blocks)
+            for col in range(1, bb.shape[1]):
+                M = M.row_join(bb[row, col].blocks)
+            MM = MM.col_join(M)
+
+        return BlockMatrix(MM)
+    except ShapeError:
+        return B
+
+
+def reblock_2x2(expr):
+    """
+    Reblock a BlockMatrix so that it has 2x2 blocks of block matrices.  If
+    possible in such a way that the matrix continues to be invertible using the
+    classical 2x2 block inversion formulas.
+    """
+    if not isinstance(expr, BlockMatrix) or not all(d > 2 for d in expr.blockshape):
+        return expr
+
+    BM = BlockMatrix  # for brevity's sake
+    rowblocks, colblocks = expr.blockshape
+    blocks = expr.blocks
+    for i in range(1, rowblocks):
+        for j in range(1, colblocks):
+            # try to split rows at i and cols at j
+            A = bc_unpack(BM(blocks[:i, :j]))
+            B = bc_unpack(BM(blocks[:i, j:]))
+            C = bc_unpack(BM(blocks[i:, :j]))
+            D = bc_unpack(BM(blocks[i:, j:]))
+
+            formula = _choose_2x2_inversion_formula(A, B, C, D)
+            if formula is not None:
+                return BlockMatrix([[A, B], [C, D]])
+
+    # else: nothing worked, just split upper left corner
+    return BM([[blocks[0, 0], BM(blocks[0, 1:])],
+               [BM(blocks[1:, 0]), BM(blocks[1:, 1:])]])
+
+
+def bounds(sizes):
+    """ Convert sequence of numbers into pairs of low-high pairs
+
+    >>> from sympy.matrices.expressions.blockmatrix import bounds
+    >>> bounds((1, 10, 50))
+    [(0, 1), (1, 11), (11, 61)]
+    """
+    low = 0
+    rv = []
+    for size in sizes:
+        rv.append((low, low + size))
+        low += size
+    return rv
+
+def blockcut(expr, rowsizes, colsizes):
+    """ Cut a matrix expression into Blocks
+
+    >>> from sympy import ImmutableMatrix, blockcut
+    >>> M = ImmutableMatrix(4, 4, range(16))
+    >>> B = blockcut(M, (1, 3), (1, 3))
+    >>> type(B).__name__
+    'BlockMatrix'
+    >>> ImmutableMatrix(B.blocks[0, 1])
+    Matrix([[1, 2, 3]])
+    """
+
+    rowbounds = bounds(rowsizes)
+    colbounds = bounds(colsizes)
+    return BlockMatrix([[MatrixSlice(expr, rowbound, colbound)
+                         for colbound in colbounds]
+                         for rowbound in rowbounds])

.venv/lib/python3.11/site-packages/sympy/matrices/expressions/dotproduct.py

@@ -0,0 +1,55 @@
+from sympy.core import Basic, Expr
+from sympy.core.sympify import _sympify
+from sympy.matrices.expressions.transpose import transpose
+
+
+class DotProduct(Expr):
+    """
+    Dot product of vector matrices
+
+    The input should be two 1 x n or n x 1 matrices. The output represents the
+    scalar dotproduct.
+
+    This is similar to using MatrixElement and MatMul, except DotProduct does
+    not require that one vector to be a row vector and the other vector to be
+    a column vector.
+
+    >>> from sympy import MatrixSymbol, DotProduct
+    >>> A = MatrixSymbol('A', 1, 3)
+    >>> B = MatrixSymbol('B', 1, 3)
+    >>> DotProduct(A, B)
+    DotProduct(A, B)
+    >>> DotProduct(A, B).doit()
+    A[0, 0]*B[0, 0] + A[0, 1]*B[0, 1] + A[0, 2]*B[0, 2]
+    """
+
+    def __new__(cls, arg1, arg2):
+        arg1, arg2 = _sympify((arg1, arg2))
+
+        if not arg1.is_Matrix:
+            raise TypeError("Argument 1 of DotProduct is not a matrix")
+        if not arg2.is_Matrix:
+            raise TypeError("Argument 2 of DotProduct is not a matrix")
+        if not (1 in arg1.shape):
+            raise TypeError("Argument 1 of DotProduct is not a vector")
+        if not (1 in arg2.shape):
+            raise TypeError("Argument 2 of DotProduct is not a vector")
+
+        if set(arg1.shape) != set(arg2.shape):
+            raise TypeError("DotProduct arguments are not the same length")
+
+        return Basic.__new__(cls, arg1, arg2)
+
+    def doit(self, expand=False, **hints):
+        if self.args[0].shape == self.args[1].shape:
+            if self.args[0].shape[0] == 1:
+                mul = self.args[0]*transpose(self.args[1])
+            else:
+                mul = transpose(self.args[0])*self.args[1]
+        else:
+            if self.args[0].shape[0] == 1:
+                mul = self.args[0]*self.args[1]
+            else:
+                mul = transpose(self.args[0])*transpose(self.args[1])
+
+        return mul[0]

.venv/lib/python3.11/site-packages/sympy/matrices/expressions/factorizations.py

@@ -0,0 +1,62 @@
+from sympy.matrices.expressions import MatrixExpr
+from sympy.assumptions.ask import Q
+
+class Factorization(MatrixExpr):
+    arg = property(lambda self: self.args[0])
+    shape = property(lambda self: self.arg.shape)  # type: ignore
+
+class LofLU(Factorization):
+    @property
+    def predicates(self):
+        return (Q.lower_triangular,)
+class UofLU(Factorization):
+    @property
+    def predicates(self):
+        return (Q.upper_triangular,)
+
+class LofCholesky(LofLU): pass
+class UofCholesky(UofLU): pass
+
+class QofQR(Factorization):
+    @property
+    def predicates(self):
+        return (Q.orthogonal,)
+class RofQR(Factorization):
+    @property
+    def predicates(self):
+        return (Q.upper_triangular,)
+
+class EigenVectors(Factorization):
+    @property
+    def predicates(self):
+        return (Q.orthogonal,)
+class EigenValues(Factorization):
+    @property
+    def predicates(self):
+        return (Q.diagonal,)
+
+class UofSVD(Factorization):
+    @property
+    def predicates(self):
+        return (Q.orthogonal,)
+class SofSVD(Factorization):
+    @property
+    def predicates(self):
+        return (Q.diagonal,)
+class VofSVD(Factorization):
+    @property
+    def predicates(self):
+        return (Q.orthogonal,)
+
+
+def lu(expr):
+    return LofLU(expr), UofLU(expr)
+
+def qr(expr):
+    return QofQR(expr), RofQR(expr)
+
+def eig(expr):
+    return EigenValues(expr), EigenVectors(expr)
+
+def svd(expr):
+    return UofSVD(expr), SofSVD(expr), VofSVD(expr)

.venv/lib/python3.11/site-packages/sympy/matrices/expressions/funcmatrix.py

@@ -0,0 +1,118 @@
+from .matexpr import MatrixExpr
+from sympy.core.function import FunctionClass, Lambda
+from sympy.core.symbol import Dummy
+from sympy.core.sympify import _sympify, sympify
+from sympy.matrices import Matrix
+from sympy.functions.elementary.complexes import re, im
+
+
+class FunctionMatrix(MatrixExpr):
+    """Represents a matrix using a function (``Lambda``) which gives
+    outputs according to the coordinates of each matrix entries.
+
+    Parameters
+    ==========
+
+    rows : nonnegative integer. Can be symbolic.
+
+    cols : nonnegative integer. Can be symbolic.
+
+    lamda : Function, Lambda or str
+        If it is a SymPy ``Function`` or ``Lambda`` instance,
+        it should be able to accept two arguments which represents the
+        matrix coordinates.
+
+        If it is a pure string containing Python ``lambda`` semantics,
+        it is interpreted by the SymPy parser and casted into a SymPy
+        ``Lambda`` instance.
+
+    Examples
+    ========
+
+    Creating a ``FunctionMatrix`` from ``Lambda``:
+
+    >>> from sympy import FunctionMatrix, symbols, Lambda, MatPow
+    >>> i, j, n, m = symbols('i,j,n,m')
+    >>> FunctionMatrix(n, m, Lambda((i, j), i + j))
+    FunctionMatrix(n, m, Lambda((i, j), i + j))
+
+    Creating a ``FunctionMatrix`` from a SymPy function:
+
+    >>> from sympy import KroneckerDelta
+    >>> X = FunctionMatrix(3, 3, KroneckerDelta)
+    >>> X.as_explicit()
+    Matrix([
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1]])
+
+    Creating a ``FunctionMatrix`` from a SymPy undefined function:
+
+    >>> from sympy import Function
+    >>> f = Function('f')
+    >>> X = FunctionMatrix(3, 3, f)
+    >>> X.as_explicit()
+    Matrix([
+    [f(0, 0), f(0, 1), f(0, 2)],
+    [f(1, 0), f(1, 1), f(1, 2)],
+    [f(2, 0), f(2, 1), f(2, 2)]])
+
+    Creating a ``FunctionMatrix`` from Python ``lambda``:
+
+    >>> FunctionMatrix(n, m, 'lambda i, j: i + j')
+    FunctionMatrix(n, m, Lambda((i, j), i + j))
+
+    Example of lazy evaluation of matrix product:
+
+    >>> Y = FunctionMatrix(1000, 1000, Lambda((i, j), i + j))
+    >>> isinstance(Y*Y, MatPow) # this is an expression object
+    True
+    >>> (Y**2)[10,10] # So this is evaluated lazily
+    342923500
+
+    Notes
+    =====
+
+    This class provides an alternative way to represent an extremely
+    dense matrix with entries in some form of a sequence, in a most
+    sparse way.
+    """
+    def __new__(cls, rows, cols, lamda):
+        rows, cols = _sympify(rows), _sympify(cols)
+        cls._check_dim(rows)
+        cls._check_dim(cols)
+
+        lamda = sympify(lamda)
+        if not isinstance(lamda, (FunctionClass, Lambda)):
+            raise ValueError(
+                "{} should be compatible with SymPy function classes."
+                .format(lamda))
+
+        if 2 not in lamda.nargs:
+            raise ValueError(
+                '{} should be able to accept 2 arguments.'.format(lamda))
+
+        if not isinstance(lamda, Lambda):
+            i, j = Dummy('i'), Dummy('j')
+            lamda = Lambda((i, j), lamda(i, j))
+
+        return super().__new__(cls, rows, cols, lamda)
+
+    @property
+    def shape(self):
+        return self.args[0:2]
+
+    @property
+    def lamda(self):
+        return self.args[2]
+
+    def _entry(self, i, j, **kwargs):
+        return self.lamda(i, j)
+
+    def _eval_trace(self):
+        from sympy.matrices.expressions.trace import Trace
+        from sympy.concrete.summations import Sum
+        return Trace(self).rewrite(Sum).doit()
+
+    def _eval_as_real_imag(self):
+        return (re(Matrix(self)), im(Matrix(self)))

.venv/lib/python3.11/site-packages/sympy/matrices/expressions/inverse.py

@@ -0,0 +1,112 @@
+from sympy.core.sympify import _sympify
+from sympy.core import S, Basic
+
+from sympy.matrices.exceptions import NonSquareMatrixError
+from sympy.matrices.expressions.matpow import MatPow
+
+
+class Inverse(MatPow):
+    """
+    The multiplicative inverse of a matrix expression
+
+    This is a symbolic object that simply stores its argument without
+    evaluating it. To actually compute the inverse, use the ``.inverse()``
+    method of matrices.
+
+    Examples
+    ========
+
+    >>> from sympy import MatrixSymbol, Inverse
+    >>> A = MatrixSymbol('A', 3, 3)
+    >>> B = MatrixSymbol('B', 3, 3)
+    >>> Inverse(A)
+    A**(-1)
+    >>> A.inverse() == Inverse(A)
+    True
+    >>> (A*B).inverse()
+    B**(-1)*A**(-1)
+    >>> Inverse(A*B)
+    (A*B)**(-1)
+
+    """
+    is_Inverse = True
+    exp = S.NegativeOne
+
+    def __new__(cls, mat, exp=S.NegativeOne):
+        # exp is there to make it consistent with
+        # inverse.func(*inverse.args) == inverse
+        mat = _sympify(mat)
+        exp = _sympify(exp)
+        if not mat.is_Matrix:
+            raise TypeError("mat should be a matrix")
+        if mat.is_square is False:
+            raise NonSquareMatrixError("Inverse of non-square matrix %s" % mat)
+        return Basic.__new__(cls, mat, exp)
+
+    @property
+    def arg(self):
+        return self.args[0]
+
+    @property
+    def shape(self):
+        return self.arg.shape
+
+    def _eval_inverse(self):
+        return self.arg
+
+    def _eval_transpose(self):
+        return Inverse(self.arg.transpose())
+
+    def _eval_adjoint(self):
+        return Inverse(self.arg.adjoint())
+
+    def _eval_conjugate(self):
+        return Inverse(self.arg.conjugate())
+
+    def _eval_determinant(self):
+        from sympy.matrices.expressions.determinant import det
+        return 1/det(self.arg)
+
+    def doit(self, **hints):
+        if 'inv_expand' in hints and hints['inv_expand'] == False:
+            return self
+
+        arg = self.arg
+        if hints.get('deep', True):
+            arg = arg.doit(**hints)
+
+        return arg.inverse()
+
+    def _eval_derivative_matrix_lines(self, x):
+        arg = self.args[0]
+        lines = arg._eval_derivative_matrix_lines(x)
+        for line in lines:
+            line.first_pointer *= -self.T
+            line.second_pointer *= self
+        return lines
+
+
+from sympy.assumptions.ask import ask, Q
+from sympy.assumptions.refine import handlers_dict
+
+
+def refine_Inverse(expr, assumptions):
+    """
+    >>> from sympy import MatrixSymbol, Q, assuming, refine
+    >>> X = MatrixSymbol('X', 2, 2)
+    >>> X.I
+    X**(-1)
+    >>> with assuming(Q.orthogonal(X)):
+    ...     print(refine(X.I))
+    X.T
+    """
+    if ask(Q.orthogonal(expr), assumptions):
+        return expr.arg.T
+    elif ask(Q.unitary(expr), assumptions):
+        return expr.arg.conjugate()
+    elif ask(Q.singular(expr), assumptions):
+        raise ValueError("Inverse of singular matrix %s" % expr.arg)
+
+    return expr
+
+handlers_dict['Inverse'] = refine_Inverse

.venv/lib/python3.11/site-packages/sympy/matrices/expressions/kronecker.py

@@ -0,0 +1,434 @@
+"""Implementation of the Kronecker product"""
+from functools import reduce
+from math import prod
+
+from sympy.core import Mul, sympify
+from sympy.functions import adjoint
+from sympy.matrices.exceptions import ShapeError
+from sympy.matrices.expressions.matexpr import MatrixExpr
+from sympy.matrices.expressions.transpose import transpose
+from sympy.matrices.expressions.special import Identity
+from sympy.matrices.matrixbase import MatrixBase
+from sympy.strategies import (
+    canon, condition, distribute, do_one, exhaust, flatten, typed, unpack)
+from sympy.strategies.traverse import bottom_up
+from sympy.utilities import sift
+
+from .matadd import MatAdd
+from .matmul import MatMul
+from .matpow import MatPow
+
+
+def kronecker_product(*matrices):
+    """
+    The Kronecker product of two or more arguments.
+
+    This computes the explicit Kronecker product for subclasses of
+    ``MatrixBase`` i.e. explicit matrices. Otherwise, a symbolic
+    ``KroneckerProduct`` object is returned.
+
+
+    Examples
+    ========
+
+    For ``MatrixSymbol`` arguments a ``KroneckerProduct`` object is returned.
+    Elements of this matrix can be obtained by indexing, or for MatrixSymbols
+    with known dimension the explicit matrix can be obtained with
+    ``.as_explicit()``
+
+    >>> from sympy import kronecker_product, MatrixSymbol
+    >>> A = MatrixSymbol('A', 2, 2)
+    >>> B = MatrixSymbol('B', 2, 2)
+    >>> kronecker_product(A)
+    A
+    >>> kronecker_product(A, B)
+    KroneckerProduct(A, B)
+    >>> kronecker_product(A, B)[0, 1]
+    A[0, 0]*B[0, 1]
+    >>> kronecker_product(A, B).as_explicit()
+    Matrix([
+        [A[0, 0]*B[0, 0], A[0, 0]*B[0, 1], A[0, 1]*B[0, 0], A[0, 1]*B[0, 1]],
+        [A[0, 0]*B[1, 0], A[0, 0]*B[1, 1], A[0, 1]*B[1, 0], A[0, 1]*B[1, 1]],
+        [A[1, 0]*B[0, 0], A[1, 0]*B[0, 1], A[1, 1]*B[0, 0], A[1, 1]*B[0, 1]],
+        [A[1, 0]*B[1, 0], A[1, 0]*B[1, 1], A[1, 1]*B[1, 0], A[1, 1]*B[1, 1]]])
+
+    For explicit matrices the Kronecker product is returned as a Matrix
+
+    >>> from sympy import Matrix, kronecker_product
+    >>> sigma_x = Matrix([
+    ... [0, 1],
+    ... [1, 0]])
+    ...
+    >>> Isigma_y = Matrix([
+    ... [0, 1],
+    ... [-1, 0]])
+    ...
+    >>> kronecker_product(sigma_x, Isigma_y)
+    Matrix([
+    [ 0, 0,  0, 1],
+    [ 0, 0, -1, 0],
+    [ 0, 1,  0, 0],
+    [-1, 0,  0, 0]])
+
+    See Also
+    ========
+        KroneckerProduct
+
+    """
+    if not matrices:
+        raise TypeError("Empty Kronecker product is undefined")
+    if len(matrices) == 1:
+        return matrices[0]
+    else:
+        return KroneckerProduct(*matrices).doit()
+
+
+class KroneckerProduct(MatrixExpr):
+    """
+    The Kronecker product of two or more arguments.
+
+    The Kronecker product is a non-commutative product of matrices.
+    Given two matrices of dimension (m, n) and (s, t) it produces a matrix
+    of dimension (m s, n t).
+
+    This is a symbolic object that simply stores its argument without
+    evaluating it. To actually compute the product, use the function
+    ``kronecker_product()`` or call the ``.doit()`` or  ``.as_explicit()``
+    methods.
+
+    >>> from sympy import KroneckerProduct, MatrixSymbol
+    >>> A = MatrixSymbol('A', 5, 5)
+    >>> B = MatrixSymbol('B', 5, 5)
+    >>> isinstance(KroneckerProduct(A, B), KroneckerProduct)
+    True
+    """
+    is_KroneckerProduct = True
+
+    def __new__(cls, *args, check=True):
+        args = list(map(sympify, args))
+        if all(a.is_Identity for a in args):
+            ret = Identity(prod(a.rows for a in args))
+            if all(isinstance(a, MatrixBase) for a in args):
+                return ret.as_explicit()
+            else:
+                return ret
+
+        if check:
+            validate(*args)
+        return super().__new__(cls, *args)
+
+    @property
+    def shape(self):
+        rows, cols = self.args[0].shape
+        for mat in self.args[1:]:
+            rows *= mat.rows
+            cols *= mat.cols
+        return (rows, cols)
+
+    def _entry(self, i, j, **kwargs):
+        result = 1
+        for mat in reversed(self.args):
+            i, m = divmod(i, mat.rows)
+            j, n = divmod(j, mat.cols)
+            result *= mat[m, n]
+        return result
+
+    def _eval_adjoint(self):
+        return KroneckerProduct(*list(map(adjoint, self.args))).doit()
+
+    def _eval_conjugate(self):
+        return KroneckerProduct(*[a.conjugate() for a in self.args]).doit()
+
+    def _eval_transpose(self):
+        return KroneckerProduct(*list(map(transpose, self.args))).doit()
+
+    def _eval_trace(self):
+        from .trace import trace
+        return Mul(*[trace(a) for a in self.args])
+
+    def _eval_determinant(self):
+        from .determinant import det, Determinant
+        if not all(a.is_square for a in self.args):
+            return Determinant(self)
+
+        m = self.rows
+        return Mul(*[det(a)**(m/a.rows) for a in self.args])
+
+    def _eval_inverse(self):
+        try:
+            return KroneckerProduct(*[a.inverse() for a in self.args])
+        except ShapeError:
+            from sympy.matrices.expressions.inverse import Inverse
+            return Inverse(self)
+
+    def structurally_equal(self, other):
+        '''Determine whether two matrices have the same Kronecker product structure
+
+        Examples
+        ========
+
+        >>> from sympy import KroneckerProduct, MatrixSymbol, symbols
+        >>> m, n = symbols(r'm, n', integer=True)
+        >>> A = MatrixSymbol('A', m, m)
+        >>> B = MatrixSymbol('B', n, n)
+        >>> C = MatrixSymbol('C', m, m)
+        >>> D = MatrixSymbol('D', n, n)
+        >>> KroneckerProduct(A, B).structurally_equal(KroneckerProduct(C, D))
+        True
+        >>> KroneckerProduct(A, B).structurally_equal(KroneckerProduct(D, C))
+        False
+        >>> KroneckerProduct(A, B).structurally_equal(C)
+        False
+        '''
+        # Inspired by BlockMatrix
+        return (isinstance(other, KroneckerProduct)
+                and self.shape == other.shape
+                and len(self.args) == len(other.args)
+                and all(a.shape == b.shape for (a, b) in zip(self.args, other.args)))
+
+    def has_matching_shape(self, other):
+        '''Determine whether two matrices have the appropriate structure to bring matrix
+        multiplication inside the KroneckerProdut
+
+        Examples
+        ========
+        >>> from sympy import KroneckerProduct, MatrixSymbol, symbols
+        >>> m, n = symbols(r'm, n', integer=True)
+        >>> A = MatrixSymbol('A', m, n)
+        >>> B = MatrixSymbol('B', n, m)
+        >>> KroneckerProduct(A, B).has_matching_shape(KroneckerProduct(B, A))
+        True
+        >>> KroneckerProduct(A, B).has_matching_shape(KroneckerProduct(A, B))
+        False
+        >>> KroneckerProduct(A, B).has_matching_shape(A)
+        False
+        '''
+        return (isinstance(other, KroneckerProduct)
+                and self.cols == other.rows
+                and len(self.args) == len(other.args)
+                and all(a.cols == b.rows for (a, b) in zip(self.args, other.args)))
+
+    def _eval_expand_kroneckerproduct(self, **hints):
+        return flatten(canon(typed({KroneckerProduct: distribute(KroneckerProduct, MatAdd)}))(self))
+
+    def _kronecker_add(self, other):
+        if self.structurally_equal(other):
+            return self.__class__(*[a + b for (a, b) in zip(self.args, other.args)])
+        else:
+            return self + other
+
+    def _kronecker_mul(self, other):
+        if self.has_matching_shape(other):
+            return self.__class__(*[a*b for (a, b) in zip(self.args, other.args)])
+        else:
+            return self * other
+
+    def doit(self, **hints):
+        deep = hints.get('deep', True)
+        if deep:
+            args = [arg.doit(**hints) for arg in self.args]
+        else:
+            args = self.args
+        return canonicalize(KroneckerProduct(*args))
+
+
+def validate(*args):
+    if not all(arg.is_Matrix for arg in args):
+        raise TypeError("Mix of Matrix and Scalar symbols")
+
+
+# rules
+
+def extract_commutative(kron):
+    c_part = []
+    nc_part = []
+    for arg in kron.args:
+        c, nc = arg.args_cnc()
+        c_part.extend(c)
+        nc_part.append(Mul._from_args(nc))
+
+    c_part = Mul(*c_part)
+    if c_part != 1:
+        return c_part*KroneckerProduct(*nc_part)
+    return kron
+
+
+def matrix_kronecker_product(*matrices):
+    """Compute the Kronecker product of a sequence of SymPy Matrices.
+
+    This is the standard Kronecker product of matrices [1].
+
+    Parameters
+    ==========
+
+    matrices : tuple of MatrixBase instances
+        The matrices to take the Kronecker product of.
+
+    Returns
+    =======
+
+    matrix : MatrixBase
+        The Kronecker product matrix.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> from sympy.matrices.expressions.kronecker import (
+    ... matrix_kronecker_product)
+
+    >>> m1 = Matrix([[1,2],[3,4]])
+    >>> m2 = Matrix([[1,0],[0,1]])
+    >>> matrix_kronecker_product(m1, m2)
+    Matrix([
+    [1, 0, 2, 0],
+    [0, 1, 0, 2],
+    [3, 0, 4, 0],
+    [0, 3, 0, 4]])
+    >>> matrix_kronecker_product(m2, m1)
+    Matrix([
+    [1, 2, 0, 0],
+    [3, 4, 0, 0],
+    [0, 0, 1, 2],
+    [0, 0, 3, 4]])
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Kronecker_product
+    """
+    # Make sure we have a sequence of Matrices
+    if not all(isinstance(m, MatrixBase) for m in matrices):
+        raise TypeError(
+            'Sequence of Matrices expected, got: %s' % repr(matrices)
+        )
+
+    # Pull out the first element in the product.
+    matrix_expansion = matrices[-1]
+    # Do the kronecker product working from right to left.
+    for mat in reversed(matrices[:-1]):
+        rows = mat.rows
+        cols = mat.cols
+        # Go through each row appending kronecker product to.
+        # running matrix_expansion.
+        for i in range(rows):
+            start = matrix_expansion*mat[i*cols]
+            # Go through each column joining each item
+            for j in range(cols - 1):
+                start = start.row_join(
+                    matrix_expansion*mat[i*cols + j + 1]
+                )
+            # If this is the first element, make it the start of the
+            # new row.
+            if i == 0:
+                next = start
+            else:
+                next = next.col_join(start)
+        matrix_expansion = next
+
+    MatrixClass = max(matrices, key=lambda M: M._class_priority).__class__
+    if isinstance(matrix_expansion, MatrixClass):
+        return matrix_expansion
+    else:
+        return MatrixClass(matrix_expansion)
+
+
+def explicit_kronecker_product(kron):
+    # Make sure we have a sequence of Matrices
+    if not all(isinstance(m, MatrixBase) for m in kron.args):
+        return kron
+
+    return matrix_kronecker_product(*kron.args)
+
+
+rules = (unpack,
+         explicit_kronecker_product,
+         flatten,
+         extract_commutative)
+
+canonicalize = exhaust(condition(lambda x: isinstance(x, KroneckerProduct),
+                                 do_one(*rules)))
+
+
+def _kronecker_dims_key(expr):
+    if isinstance(expr, KroneckerProduct):
+        return tuple(a.shape for a in expr.args)
+    else:
+        return (0,)
+
+
+def kronecker_mat_add(expr):
+    args = sift(expr.args, _kronecker_dims_key)
+    nonkrons = args.pop((0,), None)
+    if not args:
+        return expr
+
+    krons = [reduce(lambda x, y: x._kronecker_add(y), group)
+             for group in args.values()]
+
+    if not nonkrons:
+        return MatAdd(*krons)
+    else:
+        return MatAdd(*krons) + nonkrons
+
+
+def kronecker_mat_mul(expr):
+    # modified from block matrix code
+    factor, matrices = expr.as_coeff_matrices()
+
+    i = 0
+    while i < len(matrices) - 1:
+        A, B = matrices[i:i+2]
+        if isinstance(A, KroneckerProduct) and isinstance(B, KroneckerProduct):
+            matrices[i] = A._kronecker_mul(B)
+            matrices.pop(i+1)
+        else:
+            i += 1
+
+    return factor*MatMul(*matrices)
+
+
+def kronecker_mat_pow(expr):
+    if isinstance(expr.base, KroneckerProduct) and all(a.is_square for a in expr.base.args):
+        return KroneckerProduct(*[MatPow(a, expr.exp) for a in expr.base.args])
+    else:
+        return expr
+
+
+def combine_kronecker(expr):
+    """Combine KronekeckerProduct with expression.
+
+    If possible write operations on KroneckerProducts of compatible shapes
+    as a single KroneckerProduct.
+
+    Examples
+    ========
+
+    >>> from sympy.matrices.expressions import combine_kronecker
+    >>> from sympy import MatrixSymbol, KroneckerProduct, symbols
+    >>> m, n = symbols(r'm, n', integer=True)
+    >>> A = MatrixSymbol('A', m, n)
+    >>> B = MatrixSymbol('B', n, m)
+    >>> combine_kronecker(KroneckerProduct(A, B)*KroneckerProduct(B, A))
+    KroneckerProduct(A*B, B*A)
+    >>> combine_kronecker(KroneckerProduct(A, B)+KroneckerProduct(B.T, A.T))
+    KroneckerProduct(A + B.T, B + A.T)
+    >>> C = MatrixSymbol('C', n, n)
+    >>> D = MatrixSymbol('D', m, m)
+    >>> combine_kronecker(KroneckerProduct(C, D)**m)
+    KroneckerProduct(C**m, D**m)
+    """
+    def haskron(expr):
+        return isinstance(expr, MatrixExpr) and expr.has(KroneckerProduct)
+
+    rule = exhaust(
+        bottom_up(exhaust(condition(haskron, typed(
+            {MatAdd: kronecker_mat_add,
+             MatMul: kronecker_mat_mul,
+             MatPow: kronecker_mat_pow})))))
+    result = rule(expr)
+    doit = getattr(result, 'doit', None)
+    if doit is not None:
+        return doit()
+    else:
+        return result

.venv/lib/python3.11/site-packages/sympy/matrices/expressions/matexpr.py

@@ -0,0 +1,888 @@
+from __future__ import annotations
+from functools import wraps
+
+from sympy.core import S, Integer, Basic, Mul, Add
+from sympy.core.assumptions import check_assumptions
+from sympy.core.decorators import call_highest_priority
+from sympy.core.expr import Expr, ExprBuilder
+from sympy.core.logic import FuzzyBool
+from sympy.core.symbol import Str, Dummy, symbols, Symbol
+from sympy.core.sympify import SympifyError, _sympify
+from sympy.external.gmpy import SYMPY_INTS
+from sympy.functions import conjugate, adjoint
+from sympy.functions.special.tensor_functions import KroneckerDelta
+from sympy.matrices.exceptions import NonSquareMatrixError
+from sympy.matrices.kind import MatrixKind
+from sympy.matrices.matrixbase import MatrixBase
+from sympy.multipledispatch import dispatch
+from sympy.utilities.misc import filldedent
+
+
+def _sympifyit(arg, retval=None):
+    # This version of _sympifyit sympifies MutableMatrix objects
+    def deco(func):
+        @wraps(func)
+        def __sympifyit_wrapper(a, b):
+            try:
+                b = _sympify(b)
+                return func(a, b)
+            except SympifyError:
+                return retval
+
+        return __sympifyit_wrapper
+
+    return deco
+
+
+class MatrixExpr(Expr):
+    """Superclass for Matrix Expressions
+
+    MatrixExprs represent abstract matrices, linear transformations represented
+    within a particular basis.
+
+    Examples
+    ========
+
+    >>> from sympy import MatrixSymbol
+    >>> A = MatrixSymbol('A', 3, 3)
+    >>> y = MatrixSymbol('y', 3, 1)
+    >>> x = (A.T*A).I * A * y
+
+    See Also
+    ========
+
+    MatrixSymbol, MatAdd, MatMul, Transpose, Inverse
+    """
+    __slots__: tuple[str, ...] = ()
+
+    # Should not be considered iterable by the
+    # sympy.utilities.iterables.iterable function. Subclass that actually are
+    # iterable (i.e., explicit matrices) should set this to True.
+    _iterable = False
+
+    _op_priority = 11.0
+
+    is_Matrix: bool = True
+    is_MatrixExpr: bool = True
+    is_Identity: FuzzyBool = None
+    is_Inverse = False
+    is_Transpose = False
+    is_ZeroMatrix = False
+    is_MatAdd = False
+    is_MatMul = False
+
+    is_commutative = False
+    is_number = False
+    is_symbol = False
+    is_scalar = False
+
+    kind: MatrixKind = MatrixKind()
+
+    def __new__(cls, *args, **kwargs):
+        args = map(_sympify, args)
+        return Basic.__new__(cls, *args, **kwargs)
+
+    # The following is adapted from the core Expr object
+
+    @property
+    def shape(self) -> tuple[Expr, Expr]:
+        raise NotImplementedError
+
+    @property
+    def _add_handler(self):
+        return MatAdd
+
+    @property
+    def _mul_handler(self):
+        return MatMul
+
+    def __neg__(self):
+        return MatMul(S.NegativeOne, self).doit()
+
+    def __abs__(self):
+        raise NotImplementedError
+
+    @_sympifyit('other', NotImplemented)
+    @call_highest_priority('__radd__')
+    def __add__(self, other):
+        return MatAdd(self, other).doit()
+
+    @_sympifyit('other', NotImplemented)
+    @call_highest_priority('__add__')
+    def __radd__(self, other):
+        return MatAdd(other, self).doit()
+
+    @_sympifyit('other', NotImplemented)
+    @call_highest_priority('__rsub__')
+    def __sub__(self, other):
+        return MatAdd(self, -other).doit()
+
+    @_sympifyit('other', NotImplemented)
+    @call_highest_priority('__sub__')
+    def __rsub__(self, other):
+        return MatAdd(other, -self).doit()
+
+    @_sympifyit('other', NotImplemented)
+    @call_highest_priority('__rmul__')
+    def __mul__(self, other):
+        return MatMul(self, other).doit()
+
+    @_sympifyit('other', NotImplemented)
+    @call_highest_priority('__rmul__')
+    def __matmul__(self, other):
+        return MatMul(self, other).doit()
+
+    @_sympifyit('other', NotImplemented)
+    @call_highest_priority('__mul__')
+    def __rmul__(self, other):
+        return MatMul(other, self).doit()
+
+    @_sympifyit('other', NotImplemented)
+    @call_highest_priority('__mul__')
+    def __rmatmul__(self, other):
+        return MatMul(other, self).doit()
+
+    @_sympifyit('other', NotImplemented)
+    @call_highest_priority('__rpow__')
+    def __pow__(self, other):
+        return MatPow(self, other).doit()
+
+    @_sympifyit('other', NotImplemented)
+    @call_highest_priority('__pow__')
+    def __rpow__(self, other):
+        raise NotImplementedError("Matrix Power not defined")
+
+    @_sympifyit('other', NotImplemented)
+    @call_highest_priority('__rtruediv__')
+    def __truediv__(self, other):
+        return self * other**S.NegativeOne
+
+    @_sympifyit('other', NotImplemented)
+    @call_highest_priority('__truediv__')
+    def __rtruediv__(self, other):
+        raise NotImplementedError()
+        #return MatMul(other, Pow(self, S.NegativeOne))
+
+    @property
+    def rows(self):
+        return self.shape[0]
+
+    @property
+    def cols(self):
+        return self.shape[1]
+
+    @property
+    def is_square(self) -> bool | None:
+        rows, cols = self.shape
+        if isinstance(rows, Integer) and isinstance(cols, Integer):
+            return rows == cols
+        if rows == cols:
+            return True
+        return None
+
+    def _eval_conjugate(self):
+        from sympy.matrices.expressions.adjoint import Adjoint
+        return Adjoint(Transpose(self))
+
+    def as_real_imag(self, deep=True, **hints):
+        return self._eval_as_real_imag()
+
+    def _eval_as_real_imag(self):
+        real = S.Half * (self + self._eval_conjugate())
+        im = (self - self._eval_conjugate())/(2*S.ImaginaryUnit)
+        return (real, im)
+
+    def _eval_inverse(self):
+        return Inverse(self)
+
+    def _eval_determinant(self):
+        return Determinant(self)
+
+    def _eval_transpose(self):
+        return Transpose(self)
+
+    def _eval_trace(self):
+        return None
+
+    def _eval_power(self, exp):
+        """
+        Override this in sub-classes to implement simplification of powers.  The cases where the exponent
+        is -1, 0, 1 are already covered in MatPow.doit(), so implementations can exclude these cases.
+        """
+        return MatPow(self, exp)
+
+    def _eval_simplify(self, **kwargs):
+        if self.is_Atom:
+            return self
+        else:
+            from sympy.simplify import simplify
+            return self.func(*[simplify(x, **kwargs) for x in self.args])
+
+    def _eval_adjoint(self):
+        from sympy.matrices.expressions.adjoint import Adjoint
+        return Adjoint(self)
+
+    def _eval_derivative_n_times(self, x, n):
+        return Basic._eval_derivative_n_times(self, x, n)
+
+    def _eval_derivative(self, x):
+        # `x` is a scalar:
+        if self.has(x):
+            # See if there are other methods using it:
+            return super()._eval_derivative(x)
+        else:
+            return ZeroMatrix(*self.shape)
+
+    @classmethod
+    def _check_dim(cls, dim):
+        """Helper function to check invalid matrix dimensions"""
+        ok = not dim.is_Float and check_assumptions(
+            dim, integer=True, nonnegative=True)
+        if ok is False:
+            raise ValueError(
+                "The dimension specification {} should be "
+                "a nonnegative integer.".format(dim))
+
+
+    def _entry(self, i, j, **kwargs):
+        raise NotImplementedError(
+            "Indexing not implemented for %s" % self.__class__.__name__)
+
+    def adjoint(self):
+        return adjoint(self)
+
+    def as_coeff_Mul(self, rational=False):
+        """Efficiently extract the coefficient of a product."""
+        return S.One, self
+
+    def conjugate(self):
+        return conjugate(self)
+
+    def transpose(self):
+        from sympy.matrices.expressions.transpose import transpose
+        return transpose(self)
+
+    @property
+    def T(self):
+        '''Matrix transposition'''
+        return self.transpose()
+
+    def inverse(self):
+        if self.is_square is False:
+            raise NonSquareMatrixError('Inverse of non-square matrix')
+        return self._eval_inverse()
+
+    def inv(self):
+        return self.inverse()
+
+    def det(self):
+        from sympy.matrices.expressions.determinant import det
+        return det(self)
+
+    @property
+    def I(self):
+        return self.inverse()
+
+    def valid_index(self, i, j):
+        def is_valid(idx):
+            return isinstance(idx, (int, Integer, Symbol, Expr))
+        return (is_valid(i) and is_valid(j) and
+                (self.rows is None or
+                (i >= -self.rows) != False and (i < self.rows) != False) and
+                (j >= -self.cols) != False and (j < self.cols) != False)
+
+    def __getitem__(self, key):
+        if not isinstance(key, tuple) and isinstance(key, slice):
+            from sympy.matrices.expressions.slice import MatrixSlice
+            return MatrixSlice(self, key, (0, None, 1))
+        if isinstance(key, tuple) and len(key) == 2:
+            i, j = key
+            if isinstance(i, slice) or isinstance(j, slice):
+                from sympy.matrices.expressions.slice import MatrixSlice
+                return MatrixSlice(self, i, j)
+            i, j = _sympify(i), _sympify(j)
+            if self.valid_index(i, j) != False:
+                return self._entry(i, j)
+            else:
+                raise IndexError("Invalid indices (%s, %s)" % (i, j))
+        elif isinstance(key, (SYMPY_INTS, Integer)):
+            # row-wise decomposition of matrix
+            rows, cols = self.shape
+            # allow single indexing if number of columns is known
+            if not isinstance(cols, Integer):
+                raise IndexError(filldedent('''
+                    Single indexing is only supported when the number
+                    of columns is known.'''))
+            key = _sympify(key)
+            i = key // cols
+            j = key % cols
+            if self.valid_index(i, j) != False:
+                return self._entry(i, j)
+            else:
+                raise IndexError("Invalid index %s" % key)
+        elif isinstance(key, (Symbol, Expr)):
+            raise IndexError(filldedent('''
+                Only integers may be used when addressing the matrix
+                with a single index.'''))
+        raise IndexError("Invalid index, wanted %s[i,j]" % self)
+
+    def _is_shape_symbolic(self) -> bool:
+        return (not isinstance(self.rows, (SYMPY_INTS, Integer))
+            or not isinstance(self.cols, (SYMPY_INTS, Integer)))
+
+    def as_explicit(self):
+        """
+        Returns a dense Matrix with elements represented explicitly
+
+        Returns an object of type ImmutableDenseMatrix.
+
+        Examples
+        ========
+
+        >>> from sympy import Identity
+        >>> I = Identity(3)
+        >>> I
+        I
+        >>> I.as_explicit()
+        Matrix([
+        [1, 0, 0],
+        [0, 1, 0],
+        [0, 0, 1]])
+
+        See Also
+        ========
+        as_mutable: returns mutable Matrix type
+
+        """
+        if self._is_shape_symbolic():
+            raise ValueError(
+                'Matrix with symbolic shape '
+                'cannot be represented explicitly.')
+        from sympy.matrices.immutable import ImmutableDenseMatrix
+        return ImmutableDenseMatrix([[self[i, j]
+                            for j in range(self.cols)]
+                            for i in range(self.rows)])
+
+    def as_mutable(self):
+        """
+        Returns a dense, mutable matrix with elements represented explicitly
+
+        Examples
+        ========
+
+        >>> from sympy import Identity
+        >>> I = Identity(3)
+        >>> I
+        I
+        >>> I.shape
+        (3, 3)
+        >>> I.as_mutable()
+        Matrix([
+        [1, 0, 0],
+        [0, 1, 0],
+        [0, 0, 1]])
+
+        See Also
+        ========
+        as_explicit: returns ImmutableDenseMatrix
+        """
+        return self.as_explicit().as_mutable()
+
+    def __array__(self, dtype=object, copy=None):
+        if copy is not None and not copy:
+            raise TypeError("Cannot implement copy=False when converting Matrix to ndarray")
+        from numpy import empty
+        a = empty(self.shape, dtype=object)
+        for i in range(self.rows):
+            for j in range(self.cols):
+                a[i, j] = self[i, j]
+        return a
+
+    def equals(self, other):
+        """
+        Test elementwise equality between matrices, potentially of different
+        types
+
+        >>> from sympy import Identity, eye
+        >>> Identity(3).equals(eye(3))
+        True
+        """
+        return self.as_explicit().equals(other)
+
+    def canonicalize(self):
+        return self
+
+    def as_coeff_mmul(self):
+        return S.One, MatMul(self)
+
+    @staticmethod
+    def from_index_summation(expr, first_index=None, last_index=None, dimensions=None):
+        r"""
+        Parse expression of matrices with explicitly summed indices into a
+        matrix expression without indices, if possible.
+
+        This transformation expressed in mathematical notation:
+
+        `\sum_{j=0}^{N-1} A_{i,j} B_{j,k} \Longrightarrow \mathbf{A}\cdot \mathbf{B}`
+
+        Optional parameter ``first_index``: specify which free index to use as
+        the index starting the expression.
+
+        Examples
+        ========
+
+        >>> from sympy import MatrixSymbol, MatrixExpr, Sum
+        >>> from sympy.abc import i, j, k, l, N
+        >>> A = MatrixSymbol("A", N, N)
+        >>> B = MatrixSymbol("B", N, N)
+        >>> expr = Sum(A[i, j]*B[j, k], (j, 0, N-1))
+        >>> MatrixExpr.from_index_summation(expr)
+        A*B
+
+        Transposition is detected:
+
+        >>> expr = Sum(A[j, i]*B[j, k], (j, 0, N-1))
+        >>> MatrixExpr.from_index_summation(expr)
+        A.T*B
+
+        Detect the trace:
+
+        >>> expr = Sum(A[i, i], (i, 0, N-1))
+        >>> MatrixExpr.from_index_summation(expr)
+        Trace(A)
+
+        More complicated expressions:
+
+        >>> expr = Sum(A[i, j]*B[k, j]*A[l, k], (j, 0, N-1), (k, 0, N-1))
+        >>> MatrixExpr.from_index_summation(expr)
+        A*B.T*A.T
+        """
+        from sympy.tensor.array.expressions.from_indexed_to_array import convert_indexed_to_array
+        from sympy.tensor.array.expressions.from_array_to_matrix import convert_array_to_matrix
+        first_indices = []
+        if first_index is not None:
+            first_indices.append(first_index)
+        if last_index is not None:
+            first_indices.append(last_index)
+        arr = convert_indexed_to_array(expr, first_indices=first_indices)
+        return convert_array_to_matrix(arr)
+
+    def applyfunc(self, func):
+        from .applyfunc import ElementwiseApplyFunction
+        return ElementwiseApplyFunction(func, self)
+
+
+@dispatch(MatrixExpr, Expr)
+def _eval_is_eq(lhs, rhs): # noqa:F811
+    return False
+
+@dispatch(MatrixExpr, MatrixExpr)  # type: ignore
+def _eval_is_eq(lhs, rhs): # noqa:F811
+    if lhs.shape != rhs.shape:
+        return False
+    if (lhs - rhs).is_ZeroMatrix:
+        return True
+
+def get_postprocessor(cls):
+    def _postprocessor(expr):
+        # To avoid circular imports, we can't have MatMul/MatAdd on the top level
+        mat_class = {Mul: MatMul, Add: MatAdd}[cls]
+        nonmatrices = []
+        matrices = []
+        for term in expr.args:
+            if isinstance(term, MatrixExpr):
+                matrices.append(term)
+            else:
+                nonmatrices.append(term)
+
+        if not matrices:
+            return cls._from_args(nonmatrices)
+
+        if nonmatrices:
+            if cls == Mul:
+                for i in range(len(matrices)):
+                    if not matrices[i].is_MatrixExpr:
+                        # If one of the matrices explicit, absorb the scalar into it
+                        # (doit will combine all explicit matrices into one, so it
+                        # doesn't matter which)
+                        matrices[i] = matrices[i].__mul__(cls._from_args(nonmatrices))
+                        nonmatrices = []
+                        break
+
+            else:
+                # Maintain the ability to create Add(scalar, matrix) without
+                # raising an exception. That way different algorithms can
+                # replace matrix expressions with non-commutative symbols to
+                # manipulate them like non-commutative scalars.
+                return cls._from_args(nonmatrices + [mat_class(*matrices).doit(deep=False)])
+
+        if mat_class == MatAdd:
+            return mat_class(*matrices).doit(deep=False)
+        return mat_class(cls._from_args(nonmatrices), *matrices).doit(deep=False)
+    return _postprocessor
+
+
+Basic._constructor_postprocessor_mapping[MatrixExpr] = {
+    "Mul": [get_postprocessor(Mul)],
+    "Add": [get_postprocessor(Add)],
+}
+
+
+def _matrix_derivative(expr, x, old_algorithm=False):
+
+    if isinstance(expr, MatrixBase) or isinstance(x, MatrixBase):
+        # Do not use array expressions for explicit matrices:
+        old_algorithm = True
+
+    if old_algorithm:
+        return _matrix_derivative_old_algorithm(expr, x)
+
+    from sympy.tensor.array.expressions.from_matrix_to_array import convert_matrix_to_array
+    from sympy.tensor.array.expressions.arrayexpr_derivatives import array_derive
+    from sympy.tensor.array.expressions.from_array_to_matrix import convert_array_to_matrix
+
+    array_expr = convert_matrix_to_array(expr)
+    diff_array_expr = array_derive(array_expr, x)
+    diff_matrix_expr = convert_array_to_matrix(diff_array_expr)
+    return diff_matrix_expr
+
+
+def _matrix_derivative_old_algorithm(expr, x):
+    from sympy.tensor.array.array_derivatives import ArrayDerivative
+    lines = expr._eval_derivative_matrix_lines(x)
+
+    parts = [i.build() for i in lines]
+
+    from sympy.tensor.array.expressions.from_array_to_matrix import convert_array_to_matrix
+
+    parts = [[convert_array_to_matrix(j) for j in i] for i in parts]
+
+    def _get_shape(elem):
+        if isinstance(elem, MatrixExpr):
+            return elem.shape
+        return 1, 1
+
+    def get_rank(parts):
+        return sum(j not in (1, None) for i in parts for j in _get_shape(i))
+
+    ranks = [get_rank(i) for i in parts]
+    rank = ranks[0]
+
+    def contract_one_dims(parts):
+        if len(parts) == 1:
+            return parts[0]
+        else:
+            p1, p2 = parts[:2]
+            if p2.is_Matrix:
+                p2 = p2.T
+            if p1 == Identity(1):
+                pbase = p2
+            elif p2 == Identity(1):
+                pbase = p1
+            else:
+                pbase = p1*p2
+            if len(parts) == 2:
+                return pbase
+            else:  # len(parts) > 2
+                if pbase.is_Matrix:
+                    raise ValueError("")
+                return pbase*Mul.fromiter(parts[2:])
+
+    if rank <= 2:
+        return Add.fromiter([contract_one_dims(i) for i in parts])
+
+    return ArrayDerivative(expr, x)
+
+
+class MatrixElement(Expr):
+    parent = property(lambda self: self.args[0])
+    i = property(lambda self: self.args[1])
+    j = property(lambda self: self.args[2])
+    _diff_wrt = True
+    is_symbol = True
+    is_commutative = True
+
+    def __new__(cls, name, n, m):
+        n, m = map(_sympify, (n, m))
+        if isinstance(name, str):
+            name = Symbol(name)
+        else:
+            if isinstance(name, MatrixBase):
+                if n.is_Integer and m.is_Integer:
+                    return name[n, m]
+                name = _sympify(name)  # change mutable into immutable
+            else:
+                name = _sympify(name)
+                if not isinstance(name.kind, MatrixKind):
+                    raise TypeError("First argument of MatrixElement should be a matrix")
+            if not getattr(name, 'valid_index', lambda n, m: True)(n, m):
+                raise IndexError('indices out of range')
+        obj = Expr.__new__(cls, name, n, m)
+        return obj
+
+    @property
+    def symbol(self):
+        return self.args[0]
+
+    def doit(self, **hints):
+        deep = hints.get('deep', True)
+        if deep:
+            args = [arg.doit(**hints) for arg in self.args]
+        else:
+            args = self.args
+        return args[0][args[1], args[2]]
+
+    @property
+    def indices(self):
+        return self.args[1:]
+
+    def _eval_derivative(self, v):
+
+        if not isinstance(v, MatrixElement):
+            return self.parent.diff(v)[self.i, self.j]
+
+        M = self.args[0]
+
+        m, n = self.parent.shape
+
+        if M == v.args[0]:
+            return KroneckerDelta(self.args[1], v.args[1], (0, m-1)) * \
+                   KroneckerDelta(self.args[2], v.args[2], (0, n-1))
+
+        if isinstance(M, Inverse):
+            from sympy.concrete.summations import Sum
+            i, j = self.args[1:]
+            i1, i2 = symbols("z1, z2", cls=Dummy)
+            Y = M.args[0]
+            r1, r2 = Y.shape
+            return -Sum(M[i, i1]*Y[i1, i2].diff(v)*M[i2, j], (i1, 0, r1-1), (i2, 0, r2-1))
+
+        if self.has(v.args[0]):
+            return None
+
+        return S.Zero
+
+
+class MatrixSymbol(MatrixExpr):
+    """Symbolic representation of a Matrix object
+
+    Creates a SymPy Symbol to represent a Matrix. This matrix has a shape and
+    can be included in Matrix Expressions
+
+    Examples
+    ========
+
+    >>> from sympy import MatrixSymbol, Identity
+    >>> A = MatrixSymbol('A', 3, 4) # A 3 by 4 Matrix
+    >>> B = MatrixSymbol('B', 4, 3) # A 4 by 3 Matrix
+    >>> A.shape
+    (3, 4)
+    >>> 2*A*B + Identity(3)
+    I + 2*A*B
+    """
+    is_commutative = False
+    is_symbol = True
+    _diff_wrt = True
+
+    def __new__(cls, name, n, m):
+        n, m = _sympify(n), _sympify(m)
+
+        cls._check_dim(m)
+        cls._check_dim(n)
+
+        if isinstance(name, str):
+            name = Str(name)
+        obj = Basic.__new__(cls, name, n, m)
+        return obj
+
+    @property
+    def shape(self):
+        return self.args[1], self.args[2]
+
+    @property
+    def name(self):
+        return self.args[0].name
+
+    def _entry(self, i, j, **kwargs):
+        return MatrixElement(self, i, j)
+
+    @property
+    def free_symbols(self):
+        return {self}
+
+    def _eval_simplify(self, **kwargs):
+        return self
+
+    def _eval_derivative(self, x):
+        # x is a scalar:
+        return ZeroMatrix(self.shape[0], self.shape[1])
+
+    def _eval_derivative_matrix_lines(self, x):
+        if self != x:
+            first = ZeroMatrix(x.shape[0], self.shape[0]) if self.shape[0] != 1 else S.Zero
+            second = ZeroMatrix(x.shape[1], self.shape[1]) if self.shape[1] != 1 else S.Zero
+            return [_LeftRightArgs(
+                [first, second],
+            )]
+        else:
+            first = Identity(self.shape[0]) if self.shape[0] != 1 else S.One
+            second = Identity(self.shape[1]) if self.shape[1] != 1 else S.One
+            return [_LeftRightArgs(
+                [first, second],
+            )]
+
+
+def matrix_symbols(expr):
+    return [sym for sym in expr.free_symbols if sym.is_Matrix]
+
+
+class _LeftRightArgs:
+    r"""
+    Helper class to compute matrix derivatives.
+
+    The logic: when an expression is derived by a matrix `X_{mn}`, two lines of
+    matrix multiplications are created: the one contracted to `m` (first line),
+    and the one contracted to `n` (second line).
+
+    Transposition flips the side by which new matrices are connected to the
+    lines.
+
+    The trace connects the end of the two lines.
+    """
+
+    def __init__(self, lines, higher=S.One):
+        self._lines = list(lines)
+        self._first_pointer_parent = self._lines
+        self._first_pointer_index = 0
+        self._first_line_index = 0
+        self._second_pointer_parent = self._lines
+        self._second_pointer_index = 1
+        self._second_line_index = 1
+        self.higher = higher
+
+    @property
+    def first_pointer(self):
+       return self._first_pointer_parent[self._first_pointer_index]
+
+    @first_pointer.setter
+    def first_pointer(self, value):
+        self._first_pointer_parent[self._first_pointer_index] = value
+
+    @property
+    def second_pointer(self):
+        return self._second_pointer_parent[self._second_pointer_index]
+
+    @second_pointer.setter
+    def second_pointer(self, value):
+        self._second_pointer_parent[self._second_pointer_index] = value
+
+    def __repr__(self):
+        built = [self._build(i) for i in self._lines]
+        return "_LeftRightArgs(lines=%s, higher=%s)" % (
+            built,
+            self.higher,
+        )
+
+    def transpose(self):
+        self._first_pointer_parent, self._second_pointer_parent = self._second_pointer_parent, self._first_pointer_parent
+        self._first_pointer_index, self._second_pointer_index = self._second_pointer_index, self._first_pointer_index
+        self._first_line_index, self._second_line_index = self._second_line_index, self._first_line_index
+        return self
+
+    @staticmethod
+    def _build(expr):
+        if isinstance(expr, ExprBuilder):
+            return expr.build()
+        if isinstance(expr, list):
+            if len(expr) == 1:
+                return expr[0]
+            else:
+                return expr[0](*[_LeftRightArgs._build(i) for i in expr[1]])
+        else:
+            return expr
+
+    def build(self):
+        data = [self._build(i) for i in self._lines]
+        if self.higher != 1:
+            data += [self._build(self.higher)]
+        data = list(data)
+        return data
+
+    def matrix_form(self):
+        if self.first != 1 and self.higher != 1:
+            raise ValueError("higher dimensional array cannot be represented")
+
+        def _get_shape(elem):
+            if isinstance(elem, MatrixExpr):
+                return elem.shape
+            return (None, None)
+
+        if _get_shape(self.first)[1] != _get_shape(self.second)[1]:
+            # Remove one-dimensional identity matrices:
+            # (this is needed by `a.diff(a)` where `a` is a vector)
+            if _get_shape(self.second) == (1, 1):
+                return self.first*self.second[0, 0]
+            if _get_shape(self.first) == (1, 1):
+                return self.first[1, 1]*self.second.T
+            raise ValueError("incompatible shapes")
+        if self.first != 1:
+            return self.first*self.second.T
+        else:
+            return self.higher
+
+    def rank(self):
+        """
+        Number of dimensions different from trivial (warning: not related to
+        matrix rank).
+        """
+        rank = 0
+        if self.first != 1:
+            rank += sum(i != 1 for i in self.first.shape)
+        if self.second != 1:
+            rank += sum(i != 1 for i in self.second.shape)
+        if self.higher != 1:
+            rank += 2
+        return rank
+
+    def _multiply_pointer(self, pointer, other):
+        from ...tensor.array.expressions.array_expressions import ArrayTensorProduct
+        from ...tensor.array.expressions.array_expressions import ArrayContraction
+
+        subexpr = ExprBuilder(
+            ArrayContraction,
+            [
+                ExprBuilder(
+                    ArrayTensorProduct,
+                    [
+                        pointer,
+                        other
+                    ]
+                ),
+                (1, 2)
+            ],
+            validator=ArrayContraction._validate
+        )
+
+        return subexpr
+
+    def append_first(self, other):
+        self.first_pointer *= other
+
+    def append_second(self, other):
+        self.second_pointer *= other
+
+
+def _make_matrix(x):
+    from sympy.matrices.immutable import ImmutableDenseMatrix
+    if isinstance(x, MatrixExpr):
+        return x
+    return ImmutableDenseMatrix([[x]])
+
+
+from .matmul import MatMul
+from .matadd import MatAdd
+from .matpow import MatPow
+from .transpose import Transpose
+from .inverse import Inverse
+from .special import ZeroMatrix, Identity
+from .determinant import Determinant

.venv/lib/python3.11/site-packages/sympy/matrices/expressions/matpow.py

@@ -0,0 +1,150 @@
+from .matexpr import MatrixExpr
+from .special import Identity
+from sympy.core import S
+from sympy.core.expr import ExprBuilder
+from sympy.core.cache import cacheit
+from sympy.core.power import Pow
+from sympy.core.sympify import _sympify
+from sympy.matrices import MatrixBase
+from sympy.matrices.exceptions import NonSquareMatrixError
+
+
+class MatPow(MatrixExpr):
+    def __new__(cls, base, exp, evaluate=False, **options):
+        base = _sympify(base)
+        if not base.is_Matrix:
+            raise TypeError("MatPow base should be a matrix")
+
+        if base.is_square is False:
+            raise NonSquareMatrixError("Power of non-square matrix %s" % base)
+
+        exp = _sympify(exp)
+        obj = super().__new__(cls, base, exp)
+
+        if evaluate:
+            obj = obj.doit(deep=False)
+
+        return obj
+
+    @property
+    def base(self):
+        return self.args[0]
+
+    @property
+    def exp(self):
+        return self.args[1]
+
+    @property
+    def shape(self):
+        return self.base.shape
+
+    @cacheit
+    def _get_explicit_matrix(self):
+        return self.base.as_explicit()**self.exp
+
+    def _entry(self, i, j, **kwargs):
+        from sympy.matrices.expressions import MatMul
+        A = self.doit()
+        if isinstance(A, MatPow):
+            # We still have a MatPow, make an explicit MatMul out of it.
+            if A.exp.is_Integer and A.exp.is_positive:
+                A = MatMul(*[A.base for k in range(A.exp)])
+            elif not self._is_shape_symbolic():
+                return A._get_explicit_matrix()[i, j]
+            else:
+                # Leave the expression unevaluated:
+                from sympy.matrices.expressions.matexpr import MatrixElement
+                return MatrixElement(self, i, j)
+        return A[i, j]
+
+    def doit(self, **hints):
+        if hints.get('deep', True):
+            base, exp = (arg.doit(**hints) for arg in self.args)
+        else:
+            base, exp = self.args
+
+        # combine all powers, e.g. (A ** 2) ** 3 -> A ** 6
+        while isinstance(base, MatPow):
+            exp *= base.args[1]
+            base = base.args[0]
+
+        if isinstance(base, MatrixBase):
+            # Delegate
+            return base ** exp
+
+        # Handle simple cases so that _eval_power() in MatrixExpr sub-classes can ignore them
+        if exp == S.One:
+            return base
+        if exp == S.Zero:
+            return Identity(base.rows)
+        if exp == S.NegativeOne:
+            from sympy.matrices.expressions import Inverse
+            return Inverse(base).doit(**hints)
+
+        eval_power = getattr(base, '_eval_power', None)
+        if eval_power is not None:
+            return eval_power(exp)
+
+        return MatPow(base, exp)
+
+    def _eval_transpose(self):
+        base, exp = self.args
+        return MatPow(base.transpose(), exp)
+
+    def _eval_adjoint(self):
+        base, exp = self.args
+        return MatPow(base.adjoint(), exp)
+
+    def _eval_conjugate(self):
+        base, exp = self.args
+        return MatPow(base.conjugate(), exp)
+
+    def _eval_derivative(self, x):
+        return Pow._eval_derivative(self, x)
+
+    def _eval_derivative_matrix_lines(self, x):
+        from sympy.tensor.array.expressions.array_expressions import ArrayContraction
+        from ...tensor.array.expressions.array_expressions import ArrayTensorProduct
+        from .matmul import MatMul
+        from .inverse import Inverse
+        exp = self.exp
+        if self.base.shape == (1, 1) and not exp.has(x):
+            lr = self.base._eval_derivative_matrix_lines(x)
+            for i in lr:
+                subexpr = ExprBuilder(
+                    ArrayContraction,
+                    [
+                        ExprBuilder(
+                            ArrayTensorProduct,
+                            [
+                                Identity(1),
+                                i._lines[0],
+                                exp*self.base**(exp-1),
+                                i._lines[1],
+                                Identity(1),
+                            ]
+                        ),
+                        (0, 3, 4), (5, 7, 8)
+                    ],
+                    validator=ArrayContraction._validate
+                )
+                i._first_pointer_parent = subexpr.args[0].args
+                i._first_pointer_index = 0
+                i._second_pointer_parent = subexpr.args[0].args
+                i._second_pointer_index = 4
+                i._lines = [subexpr]
+            return lr
+        if (exp > 0) == True:
+            newexpr = MatMul.fromiter([self.base for i in range(exp)])
+        elif (exp == -1) == True:
+            return Inverse(self.base)._eval_derivative_matrix_lines(x)
+        elif (exp < 0) == True:
+            newexpr = MatMul.fromiter([Inverse(self.base) for i in range(-exp)])
+        elif (exp == 0) == True:
+            return self.doit()._eval_derivative_matrix_lines(x)
+        else:
+            raise NotImplementedError("cannot evaluate %s derived by %s" % (self, x))
+        return newexpr._eval_derivative_matrix_lines(x)
+
+    def _eval_inverse(self):
+        return MatPow(self.base, -self.exp)

.venv/lib/python3.11/site-packages/sympy/matrices/expressions/slice.py

@@ -0,0 +1,114 @@
+from sympy.matrices.expressions.matexpr import MatrixExpr
+from sympy.core.basic import Basic
+from sympy.core.containers import Tuple
+from sympy.functions.elementary.integers import floor
+
+def normalize(i, parentsize):
+    if isinstance(i, slice):
+        i = (i.start, i.stop, i.step)
+    if not isinstance(i, (tuple, list, Tuple)):
+        if (i < 0) == True:
+            i += parentsize
+        i = (i, i+1, 1)
+    i = list(i)
+    if len(i) == 2:
+        i.append(1)
+    start, stop, step = i
+    start = start or 0
+    if stop is None:
+        stop = parentsize
+    if (start < 0) == True:
+        start += parentsize
+    if (stop < 0) == True:
+        stop += parentsize
+    step = step or 1
+
+    if ((stop - start) * step < 1) == True:
+        raise IndexError()
+
+    return (start, stop, step)
+
+class MatrixSlice(MatrixExpr):
+    """ A MatrixSlice of a Matrix Expression
+
+    Examples
+    ========
+
+    >>> from sympy import MatrixSlice, ImmutableMatrix
+    >>> M = ImmutableMatrix(4, 4, range(16))
+    >>> M
+    Matrix([
+    [ 0,  1,  2,  3],
+    [ 4,  5,  6,  7],
+    [ 8,  9, 10, 11],
+    [12, 13, 14, 15]])
+
+    >>> B = MatrixSlice(M, (0, 2), (2, 4))
+    >>> ImmutableMatrix(B)
+    Matrix([
+    [2, 3],
+    [6, 7]])
+    """
+    parent = property(lambda self: self.args[0])
+    rowslice = property(lambda self: self.args[1])
+    colslice = property(lambda self: self.args[2])
+
+    def __new__(cls, parent, rowslice, colslice):
+        rowslice = normalize(rowslice, parent.shape[0])
+        colslice = normalize(colslice, parent.shape[1])
+        if not (len(rowslice) == len(colslice) == 3):
+            raise IndexError()
+        if ((0 > rowslice[0]) == True or
+            (parent.shape[0] < rowslice[1]) == True or
+            (0 > colslice[0]) == True or
+            (parent.shape[1] < colslice[1]) == True):
+            raise IndexError()
+        if isinstance(parent, MatrixSlice):
+            return mat_slice_of_slice(parent, rowslice, colslice)
+        return Basic.__new__(cls, parent, Tuple(*rowslice), Tuple(*colslice))
+
+    @property
+    def shape(self):
+        rows = self.rowslice[1] - self.rowslice[0]
+        rows = rows if self.rowslice[2] == 1 else floor(rows/self.rowslice[2])
+        cols = self.colslice[1] - self.colslice[0]
+        cols = cols if self.colslice[2] == 1 else floor(cols/self.colslice[2])
+        return rows, cols
+
+    def _entry(self, i, j, **kwargs):
+        return self.parent._entry(i*self.rowslice[2] + self.rowslice[0],
+                                  j*self.colslice[2] + self.colslice[0],
+                                  **kwargs)
+
+    @property
+    def on_diag(self):
+        return self.rowslice == self.colslice
+
+
+def slice_of_slice(s, t):
+    start1, stop1, step1 = s
+    start2, stop2, step2 = t
+
+    start = start1 + start2*step1
+    step = step1 * step2
+    stop = start1 + step1*stop2
+
+    if stop > stop1:
+        raise IndexError()
+
+    return start, stop, step
+
+
+def mat_slice_of_slice(parent, rowslice, colslice):
+    """ Collapse nested matrix slices
+
+    >>> from sympy import MatrixSymbol
+    >>> X = MatrixSymbol('X', 10, 10)
+    >>> X[:, 1:5][5:8, :]
+    X[5:8, 1:5]
+    >>> X[1:9:2, 2:6][1:3, 2]
+    X[3:7:2, 4:5]
+    """
+    row = slice_of_slice(parent.rowslice, rowslice)
+    col = slice_of_slice(parent.colslice, colslice)
+    return MatrixSlice(parent.parent, row, col)