Add files using upload-large-folder tool

lib/python3.12/site-packages/sympy/matrices/__init__.py

@@ -0,0 +1,72 @@
+"""A module that handles matrices.
+
+Includes functions for fast creating matrices like zero, one/eye, random
+matrix, etc.
+"""
+from .exceptions import ShapeError, NonSquareMatrixError
+from .kind import MatrixKind
+from .dense import (
+    GramSchmidt, casoratian, diag, eye, hessian, jordan_cell,
+    list2numpy, matrix2numpy, matrix_multiply_elementwise, ones,
+    randMatrix, rot_axis1, rot_axis2, rot_axis3, rot_ccw_axis1,
+    rot_ccw_axis2, rot_ccw_axis3, rot_givens,
+    symarray, wronskian, zeros)
+from .dense import MutableDenseMatrix
+from .matrixbase import DeferredVector, MatrixBase
+
+MutableMatrix = MutableDenseMatrix
+Matrix = MutableMatrix
+
+from .sparse import MutableSparseMatrix
+from .sparsetools import banded
+from .immutable import ImmutableDenseMatrix, ImmutableSparseMatrix
+
+ImmutableMatrix = ImmutableDenseMatrix
+SparseMatrix = MutableSparseMatrix
+
+from .expressions import (
+    MatrixSlice, BlockDiagMatrix, BlockMatrix, FunctionMatrix, Identity,
+    Inverse, MatAdd, MatMul, MatPow, MatrixExpr, MatrixSymbol, Trace,
+    Transpose, ZeroMatrix, OneMatrix, blockcut, block_collapse, matrix_symbols, Adjoint,
+    hadamard_product, HadamardProduct, HadamardPower, Determinant, det,
+    diagonalize_vector, DiagMatrix, DiagonalMatrix, DiagonalOf, trace,
+    DotProduct, kronecker_product, KroneckerProduct,
+    PermutationMatrix, MatrixPermute, MatrixSet, Permanent, per)
+
+from .utilities import dotprodsimp
+
+__all__ = [
+    'ShapeError', 'NonSquareMatrixError', 'MatrixKind',
+
+    'GramSchmidt', 'casoratian', 'diag', 'eye', 'hessian', 'jordan_cell',
+    'list2numpy', 'matrix2numpy', 'matrix_multiply_elementwise', 'ones',
+    'randMatrix', 'rot_axis1', 'rot_axis2', 'rot_axis3', 'symarray',
+    'wronskian', 'zeros', 'rot_ccw_axis1', 'rot_ccw_axis2', 'rot_ccw_axis3',
+    'rot_givens',
+
+    'MutableDenseMatrix',
+
+    'DeferredVector', 'MatrixBase',
+
+    'Matrix', 'MutableMatrix',
+
+    'MutableSparseMatrix',
+
+    'banded',
+
+    'ImmutableDenseMatrix', 'ImmutableSparseMatrix',
+
+    'ImmutableMatrix', 'SparseMatrix',
+
+    'MatrixSlice', 'BlockDiagMatrix', 'BlockMatrix', 'FunctionMatrix',
+    'Identity', 'Inverse', 'MatAdd', 'MatMul', 'MatPow', 'MatrixExpr',
+    'MatrixSymbol', 'Trace', 'Transpose', 'ZeroMatrix', 'OneMatrix',
+    'blockcut', 'block_collapse', 'matrix_symbols', 'Adjoint',
+    'hadamard_product', 'HadamardProduct', 'HadamardPower', 'Determinant',
+    'det', 'diagonalize_vector', 'DiagMatrix', 'DiagonalMatrix',
+    'DiagonalOf', 'trace', 'DotProduct', 'kronecker_product',
+    'KroneckerProduct', 'PermutationMatrix', 'MatrixPermute', 'MatrixSet',
+    'Permanent', 'per',
+
+    'dotprodsimp',
+]

lib/python3.12/site-packages/sympy/matrices/decompositions.py

@@ -0,0 +1,1621 @@
+import copy
+
+from sympy.core import S
+from sympy.core.function import expand_mul
+from sympy.functions.elementary.miscellaneous import Min, sqrt
+from sympy.functions.elementary.complexes import sign
+
+from .exceptions import NonSquareMatrixError, NonPositiveDefiniteMatrixError
+from .utilities import _get_intermediate_simp, _iszero
+from .determinant import _find_reasonable_pivot_naive
+
+
+def _rank_decomposition(M, iszerofunc=_iszero, simplify=False):
+    r"""Returns a pair of matrices (`C`, `F`) with matching rank
+    such that `A = C F`.
+
+    Parameters
+    ==========
+
+    iszerofunc : Function, optional
+        A function used for detecting whether an element can
+        act as a pivot.  ``lambda x: x.is_zero`` is used by default.
+
+    simplify : Bool or Function, optional
+        A function used to simplify elements when looking for a
+        pivot. By default SymPy's ``simplify`` is used.
+
+    Returns
+    =======
+
+    (C, F) : Matrices
+        `C` and `F` are full-rank matrices with rank as same as `A`,
+        whose product gives `A`.
+
+        See Notes for additional mathematical details.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> A = Matrix([
+    ...     [1, 3, 1, 4],
+    ...     [2, 7, 3, 9],
+    ...     [1, 5, 3, 1],
+    ...     [1, 2, 0, 8]
+    ... ])
+    >>> C, F = A.rank_decomposition()
+    >>> C
+    Matrix([
+    [1, 3, 4],
+    [2, 7, 9],
+    [1, 5, 1],
+    [1, 2, 8]])
+    >>> F
+    Matrix([
+    [1, 0, -2, 0],
+    [0, 1,  1, 0],
+    [0, 0,  0, 1]])
+    >>> C * F == A
+    True
+
+    Notes
+    =====
+
+    Obtaining `F`, an RREF of `A`, is equivalent to creating a
+    product
+
+    .. math::
+        E_n E_{n-1} ... E_1 A = F
+
+    where `E_n, E_{n-1}, \dots, E_1` are the elimination matrices or
+    permutation matrices equivalent to each row-reduction step.
+
+    The inverse of the same product of elimination matrices gives
+    `C`:
+
+    .. math::
+        C = \left(E_n E_{n-1} \dots E_1\right)^{-1}
+
+    It is not necessary, however, to actually compute the inverse:
+    the columns of `C` are those from the original matrix with the
+    same column indices as the indices of the pivot columns of `F`.
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Rank_factorization
+
+    .. [2] Piziak, R.; Odell, P. L. (1 June 1999).
+        "Full Rank Factorization of Matrices".
+        Mathematics Magazine. 72 (3): 193. doi:10.2307/2690882
+
+    See Also
+    ========
+
+    sympy.matrices.matrixbase.MatrixBase.rref
+    """
+
+    F, pivot_cols = M.rref(simplify=simplify, iszerofunc=iszerofunc,
+            pivots=True)
+    rank = len(pivot_cols)
+
+    C = M.extract(range(M.rows), pivot_cols)
+    F = F[:rank, :]
+
+    return C, F
+
+
+def _liupc(M):
+    """Liu's algorithm, for pre-determination of the Elimination Tree of
+    the given matrix, used in row-based symbolic Cholesky factorization.
+
+    Examples
+    ========
+
+    >>> from sympy import SparseMatrix
+    >>> S = SparseMatrix([
+    ... [1, 0, 3, 2],
+    ... [0, 0, 1, 0],
+    ... [4, 0, 0, 5],
+    ... [0, 6, 7, 0]])
+    >>> S.liupc()
+    ([[0], [], [0], [1, 2]], [4, 3, 4, 4])
+
+    References
+    ==========
+
+    .. [1] Symbolic Sparse Cholesky Factorization using Elimination Trees,
+           Jeroen Van Grondelle (1999)
+           https://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.39.7582
+    """
+    # Algorithm 2.4, p 17 of reference
+
+    # get the indices of the elements that are non-zero on or below diag
+    R = [[] for r in range(M.rows)]
+
+    for r, c, _ in M.row_list():
+        if c <= r:
+            R[r].append(c)
+
+    inf     = len(R)  # nothing will be this large
+    parent  = [inf]*M.rows
+    virtual = [inf]*M.rows
+
+    for r in range(M.rows):
+        for c in R[r][:-1]:
+            while virtual[c] < r:
+                t          = virtual[c]
+                virtual[c] = r
+                c          = t
+
+            if virtual[c] == inf:
+                parent[c] = virtual[c] = r
+
+    return R, parent
+
+def _row_structure_symbolic_cholesky(M):
+    """Symbolic cholesky factorization, for pre-determination of the
+    non-zero structure of the Cholesky factororization.
+
+    Examples
+    ========
+
+    >>> from sympy import SparseMatrix
+    >>> S = SparseMatrix([
+    ... [1, 0, 3, 2],
+    ... [0, 0, 1, 0],
+    ... [4, 0, 0, 5],
+    ... [0, 6, 7, 0]])
+    >>> S.row_structure_symbolic_cholesky()
+    [[0], [], [0], [1, 2]]
+
+    References
+    ==========
+
+    .. [1] Symbolic Sparse Cholesky Factorization using Elimination Trees,
+           Jeroen Van Grondelle (1999)
+           https://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.39.7582
+    """
+
+    R, parent = M.liupc()
+    inf       = len(R)  # this acts as infinity
+    Lrow      = copy.deepcopy(R)
+
+    for k in range(M.rows):
+        for j in R[k]:
+            while j != inf and j != k:
+                Lrow[k].append(j)
+                j = parent[j]
+
+        Lrow[k] = sorted(set(Lrow[k]))
+
+    return Lrow
+
+
+def _cholesky(M, hermitian=True):
+    """Returns the Cholesky-type decomposition L of a matrix A
+    such that L * L.H == A if hermitian flag is True,
+    or L * L.T == A if hermitian is False.
+
+    A must be a Hermitian positive-definite matrix if hermitian is True,
+    or a symmetric matrix if it is False.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> A = Matrix(((25, 15, -5), (15, 18, 0), (-5, 0, 11)))
+    >>> A.cholesky()
+    Matrix([
+    [ 5, 0, 0],
+    [ 3, 3, 0],
+    [-1, 1, 3]])
+    >>> A.cholesky() * A.cholesky().T
+    Matrix([
+    [25, 15, -5],
+    [15, 18,  0],
+    [-5,  0, 11]])
+
+    The matrix can have complex entries:
+
+    >>> from sympy import I
+    >>> A = Matrix(((9, 3*I), (-3*I, 5)))
+    >>> A.cholesky()
+    Matrix([
+    [ 3, 0],
+    [-I, 2]])
+    >>> A.cholesky() * A.cholesky().H
+    Matrix([
+    [   9, 3*I],
+    [-3*I,   5]])
+
+    Non-hermitian Cholesky-type decomposition may be useful when the
+    matrix is not positive-definite.
+
+    >>> A = Matrix([[1, 2], [2, 1]])
+    >>> L = A.cholesky(hermitian=False)
+    >>> L
+    Matrix([
+    [1,         0],
+    [2, sqrt(3)*I]])
+    >>> L*L.T == A
+    True
+
+    See Also
+    ========
+
+    sympy.matrices.dense.DenseMatrix.LDLdecomposition
+    sympy.matrices.matrixbase.MatrixBase.LUdecomposition
+    QRdecomposition
+    """
+
+    from .dense import MutableDenseMatrix
+
+    if not M.is_square:
+        raise NonSquareMatrixError("Matrix must be square.")
+    if hermitian and not M.is_hermitian:
+        raise ValueError("Matrix must be Hermitian.")
+    if not hermitian and not M.is_symmetric():
+        raise ValueError("Matrix must be symmetric.")
+
+    L   = MutableDenseMatrix.zeros(M.rows, M.rows)
+
+    if hermitian:
+        for i in range(M.rows):
+            for j in range(i):
+                L[i, j] = ((1 / L[j, j])*(M[i, j] -
+                    sum(L[i, k]*L[j, k].conjugate() for k in range(j))))
+
+            Lii2 = (M[i, i] -
+                sum(L[i, k]*L[i, k].conjugate() for k in range(i)))
+
+            if Lii2.is_positive is False:
+                raise NonPositiveDefiniteMatrixError(
+                    "Matrix must be positive-definite")
+
+            L[i, i] = sqrt(Lii2)
+
+    else:
+        for i in range(M.rows):
+            for j in range(i):
+                L[i, j] = ((1 / L[j, j])*(M[i, j] -
+                    sum(L[i, k]*L[j, k] for k in range(j))))
+
+            L[i, i] = sqrt(M[i, i] -
+                sum(L[i, k]**2 for k in range(i)))
+
+    return M._new(L)
+
+def _cholesky_sparse(M, hermitian=True):
+    """
+    Returns the Cholesky decomposition L of a matrix A
+    such that L * L.T = A
+
+    A must be a square, symmetric, positive-definite
+    and non-singular matrix
+
+    Examples
+    ========
+
+    >>> from sympy import SparseMatrix
+    >>> A = SparseMatrix(((25,15,-5),(15,18,0),(-5,0,11)))
+    >>> A.cholesky()
+    Matrix([
+    [ 5, 0, 0],
+    [ 3, 3, 0],
+    [-1, 1, 3]])
+    >>> A.cholesky() * A.cholesky().T == A
+    True
+
+    The matrix can have complex entries:
+
+    >>> from sympy import I
+    >>> A = SparseMatrix(((9, 3*I), (-3*I, 5)))
+    >>> A.cholesky()
+    Matrix([
+    [ 3, 0],
+    [-I, 2]])
+    >>> A.cholesky() * A.cholesky().H
+    Matrix([
+    [   9, 3*I],
+    [-3*I,   5]])
+
+    Non-hermitian Cholesky-type decomposition may be useful when the
+    matrix is not positive-definite.
+
+    >>> A = SparseMatrix([[1, 2], [2, 1]])
+    >>> L = A.cholesky(hermitian=False)
+    >>> L
+    Matrix([
+    [1,         0],
+    [2, sqrt(3)*I]])
+    >>> L*L.T == A
+    True
+
+    See Also
+    ========
+
+    sympy.matrices.sparse.SparseMatrix.LDLdecomposition
+    sympy.matrices.matrixbase.MatrixBase.LUdecomposition
+    QRdecomposition
+    """
+
+    from .dense import MutableDenseMatrix
+
+    if not M.is_square:
+        raise NonSquareMatrixError("Matrix must be square.")
+    if hermitian and not M.is_hermitian:
+        raise ValueError("Matrix must be Hermitian.")
+    if not hermitian and not M.is_symmetric():
+        raise ValueError("Matrix must be symmetric.")
+
+    dps       = _get_intermediate_simp(expand_mul, expand_mul)
+    Crowstruc = M.row_structure_symbolic_cholesky()
+    C         = MutableDenseMatrix.zeros(M.rows)
+
+    for i in range(len(Crowstruc)):
+        for j in Crowstruc[i]:
+            if i != j:
+                C[i, j] = M[i, j]
+                summ    = 0
+
+                for p1 in Crowstruc[i]:
+                    if p1 < j:
+                        for p2 in Crowstruc[j]:
+                            if p2 < j:
+                                if p1 == p2:
+                                    if hermitian:
+                                        summ += C[i, p1]*C[j, p1].conjugate()
+                                    else:
+                                        summ += C[i, p1]*C[j, p1]
+                            else:
+                                break
+                        else:
+                            break
+
+                C[i, j] = dps((C[i, j] - summ) / C[j, j])
+
+            else: # i == j
+                C[j, j] = M[j, j]
+                summ    = 0
+
+                for k in Crowstruc[j]:
+                    if k < j:
+                        if hermitian:
+                            summ += C[j, k]*C[j, k].conjugate()
+                        else:
+                            summ += C[j, k]**2
+                    else:
+                        break
+
+                Cjj2 = dps(C[j, j] - summ)
+
+                if hermitian and Cjj2.is_positive is False:
+                    raise NonPositiveDefiniteMatrixError(
+                        "Matrix must be positive-definite")
+
+                C[j, j] = sqrt(Cjj2)
+
+    return M._new(C)
+
+
+def _LDLdecomposition(M, hermitian=True):
+    """Returns the LDL Decomposition (L, D) of matrix A,
+    such that L * D * L.H == A if hermitian flag is True, or
+    L * D * L.T == A if hermitian is False.
+    This method eliminates the use of square root.
+    Further this ensures that all the diagonal entries of L are 1.
+    A must be a Hermitian positive-definite matrix if hermitian is True,
+    or a symmetric matrix otherwise.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix, eye
+    >>> A = Matrix(((25, 15, -5), (15, 18, 0), (-5, 0, 11)))
+    >>> L, D = A.LDLdecomposition()
+    >>> L
+    Matrix([
+    [   1,   0, 0],
+    [ 3/5,   1, 0],
+    [-1/5, 1/3, 1]])
+    >>> D
+    Matrix([
+    [25, 0, 0],
+    [ 0, 9, 0],
+    [ 0, 0, 9]])
+    >>> L * D * L.T * A.inv() == eye(A.rows)
+    True
+
+    The matrix can have complex entries:
+
+    >>> from sympy import I
+    >>> A = Matrix(((9, 3*I), (-3*I, 5)))
+    >>> L, D = A.LDLdecomposition()
+    >>> L
+    Matrix([
+    [   1, 0],
+    [-I/3, 1]])
+    >>> D
+    Matrix([
+    [9, 0],
+    [0, 4]])
+    >>> L*D*L.H == A
+    True
+
+    See Also
+    ========
+
+    sympy.matrices.dense.DenseMatrix.cholesky
+    sympy.matrices.matrixbase.MatrixBase.LUdecomposition
+    QRdecomposition
+    """
+
+    from .dense import MutableDenseMatrix
+
+    if not M.is_square:
+        raise NonSquareMatrixError("Matrix must be square.")
+    if hermitian and not M.is_hermitian:
+        raise ValueError("Matrix must be Hermitian.")
+    if not hermitian and not M.is_symmetric():
+        raise ValueError("Matrix must be symmetric.")
+
+    D   = MutableDenseMatrix.zeros(M.rows, M.rows)
+    L   = MutableDenseMatrix.eye(M.rows)
+
+    if hermitian:
+        for i in range(M.rows):
+            for j in range(i):
+                L[i, j] = (1 / D[j, j])*(M[i, j] - sum(
+                    L[i, k]*L[j, k].conjugate()*D[k, k] for k in range(j)))
+
+            D[i, i] = (M[i, i] -
+                sum(L[i, k]*L[i, k].conjugate()*D[k, k] for k in range(i)))
+
+            if D[i, i].is_positive is False:
+                raise NonPositiveDefiniteMatrixError(
+                    "Matrix must be positive-definite")
+
+    else:
+        for i in range(M.rows):
+            for j in range(i):
+                L[i, j] = (1 / D[j, j])*(M[i, j] - sum(
+                    L[i, k]*L[j, k]*D[k, k] for k in range(j)))
+
+            D[i, i] = M[i, i] - sum(L[i, k]**2*D[k, k] for k in range(i))
+
+    return M._new(L), M._new(D)
+
+def _LDLdecomposition_sparse(M, hermitian=True):
+    """
+    Returns the LDL Decomposition (matrices ``L`` and ``D``) of matrix
+    ``A``, such that ``L * D * L.T == A``. ``A`` must be a square,
+    symmetric, positive-definite and non-singular.
+
+    This method eliminates the use of square root and ensures that all
+    the diagonal entries of L are 1.
+
+    Examples
+    ========
+
+    >>> from sympy import SparseMatrix
+    >>> A = SparseMatrix(((25, 15, -5), (15, 18, 0), (-5, 0, 11)))
+    >>> L, D = A.LDLdecomposition()
+    >>> L
+    Matrix([
+    [   1,   0, 0],
+    [ 3/5,   1, 0],
+    [-1/5, 1/3, 1]])
+    >>> D
+    Matrix([
+    [25, 0, 0],
+    [ 0, 9, 0],
+    [ 0, 0, 9]])
+    >>> L * D * L.T == A
+    True
+
+    """
+
+    from .dense import MutableDenseMatrix
+
+    if not M.is_square:
+        raise NonSquareMatrixError("Matrix must be square.")
+    if hermitian and not M.is_hermitian:
+        raise ValueError("Matrix must be Hermitian.")
+    if not hermitian and not M.is_symmetric():
+        raise ValueError("Matrix must be symmetric.")
+
+    dps       = _get_intermediate_simp(expand_mul, expand_mul)
+    Lrowstruc = M.row_structure_symbolic_cholesky()
+    L         = MutableDenseMatrix.eye(M.rows)
+    D         = MutableDenseMatrix.zeros(M.rows, M.cols)
+
+    for i in range(len(Lrowstruc)):
+        for j in Lrowstruc[i]:
+            if i != j:
+                L[i, j] = M[i, j]
+                summ    = 0
+
+                for p1 in Lrowstruc[i]:
+                    if p1 < j:
+                        for p2 in Lrowstruc[j]:
+                            if p2 < j:
+                                if p1 == p2:
+                                    if hermitian:
+                                        summ += L[i, p1]*L[j, p1].conjugate()*D[p1, p1]
+                                    else:
+                                        summ += L[i, p1]*L[j, p1]*D[p1, p1]
+                            else:
+                                break
+                    else:
+                        break
+
+                L[i, j] = dps((L[i, j] - summ) / D[j, j])
+
+            else: # i == j
+                D[i, i] = M[i, i]
+                summ    = 0
+
+                for k in Lrowstruc[i]:
+                    if k < i:
+                        if hermitian:
+                            summ += L[i, k]*L[i, k].conjugate()*D[k, k]
+                        else:
+                            summ += L[i, k]**2*D[k, k]
+                    else:
+                        break
+
+                D[i, i] = dps(D[i, i] - summ)
+
+                if hermitian and D[i, i].is_positive is False:
+                    raise NonPositiveDefiniteMatrixError(
+                        "Matrix must be positive-definite")
+
+    return M._new(L), M._new(D)
+
+
+def _LUdecomposition(M, iszerofunc=_iszero, simpfunc=None, rankcheck=False):
+    """Returns (L, U, perm) where L is a lower triangular matrix with unit
+    diagonal, U is an upper triangular matrix, and perm is a list of row
+    swap index pairs. If A is the original matrix, then
+    ``A = (L*U).permuteBkwd(perm)``, and the row permutation matrix P such
+    that $P A = L U$ can be computed by ``P = eye(A.rows).permuteFwd(perm)``.
+
+    See documentation for LUCombined for details about the keyword argument
+    rankcheck, iszerofunc, and simpfunc.
+
+    Parameters
+    ==========
+
+    rankcheck : bool, optional
+        Determines if this function should detect the rank
+        deficiency of the matrixis and should raise a
+        ``ValueError``.
+
+    iszerofunc : function, optional
+        A function which determines if a given expression is zero.
+
+        The function should be a callable that takes a single
+        SymPy expression and returns a 3-valued boolean value
+        ``True``, ``False``, or ``None``.
+
+        It is internally used by the pivot searching algorithm.
+        See the notes section for a more information about the
+        pivot searching algorithm.
+
+    simpfunc : function or None, optional
+        A function that simplifies the input.
+
+        If this is specified as a function, this function should be
+        a callable that takes a single SymPy expression and returns
+        an another SymPy expression that is algebraically
+        equivalent.
+
+        If ``None``, it indicates that the pivot search algorithm
+        should not attempt to simplify any candidate pivots.
+
+        It is internally used by the pivot searching algorithm.
+        See the notes section for a more information about the
+        pivot searching algorithm.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> a = Matrix([[4, 3], [6, 3]])
+    >>> L, U, _ = a.LUdecomposition()
+    >>> L
+    Matrix([
+    [  1, 0],
+    [3/2, 1]])
+    >>> U
+    Matrix([
+    [4,    3],
+    [0, -3/2]])
+
+    See Also
+    ========
+
+    sympy.matrices.dense.DenseMatrix.cholesky
+    sympy.matrices.dense.DenseMatrix.LDLdecomposition
+    QRdecomposition
+    LUdecomposition_Simple
+    LUdecompositionFF
+    LUsolve
+    """
+
+    combined, p = M.LUdecomposition_Simple(iszerofunc=iszerofunc,
+        simpfunc=simpfunc, rankcheck=rankcheck)
+
+    # L is lower triangular ``M.rows x M.rows``
+    # U is upper triangular ``M.rows x M.cols``
+    # L has unit diagonal. For each column in combined, the subcolumn
+    # below the diagonal of combined is shared by L.
+    # If L has more columns than combined, then the remaining subcolumns
+    # below the diagonal of L are zero.
+    # The upper triangular portion of L and combined are equal.
+    def entry_L(i, j):
+        if i < j:
+            # Super diagonal entry
+            return M.zero
+        elif i == j:
+            return M.one
+        elif j < combined.cols:
+            return combined[i, j]
+
+        # Subdiagonal entry of L with no corresponding
+        # entry in combined
+        return M.zero
+
+    def entry_U(i, j):
+        return M.zero if i > j else combined[i, j]
+
+    L = M._new(combined.rows, combined.rows, entry_L)
+    U = M._new(combined.rows, combined.cols, entry_U)
+
+    return L, U, p
+
+def _LUdecomposition_Simple(M, iszerofunc=_iszero, simpfunc=None,
+        rankcheck=False):
+    r"""Compute the PLU decomposition of the matrix.
+
+    Parameters
+    ==========
+
+    rankcheck : bool, optional
+        Determines if this function should detect the rank
+        deficiency of the matrixis and should raise a
+        ``ValueError``.
+
+    iszerofunc : function, optional
+        A function which determines if a given expression is zero.
+
+        The function should be a callable that takes a single
+        SymPy expression and returns a 3-valued boolean value
+        ``True``, ``False``, or ``None``.
+
+        It is internally used by the pivot searching algorithm.
+        See the notes section for a more information about the
+        pivot searching algorithm.
+
+    simpfunc : function or None, optional
+        A function that simplifies the input.
+
+        If this is specified as a function, this function should be
+        a callable that takes a single SymPy expression and returns
+        an another SymPy expression that is algebraically
+        equivalent.
+
+        If ``None``, it indicates that the pivot search algorithm
+        should not attempt to simplify any candidate pivots.
+
+        It is internally used by the pivot searching algorithm.
+        See the notes section for a more information about the
+        pivot searching algorithm.
+
+    Returns
+    =======
+
+    (lu, row_swaps) : (Matrix, list)
+        If the original matrix is a $m, n$ matrix:
+
+        *lu* is a $m, n$ matrix, which contains result of the
+        decomposition in a compressed form. See the notes section
+        to see how the matrix is compressed.
+
+        *row_swaps* is a $m$-element list where each element is a
+        pair of row exchange indices.
+
+        ``A = (L*U).permute_backward(perm)``, and the row
+        permutation matrix $P$ from the formula $P A = L U$ can be
+        computed by ``P=eye(A.row).permute_forward(perm)``.
+
+    Raises
+    ======
+
+    ValueError
+        Raised if ``rankcheck=True`` and the matrix is found to
+        be rank deficient during the computation.
+
+    Notes
+    =====
+
+    About the PLU decomposition:
+
+    PLU decomposition is a generalization of a LU decomposition
+    which can be extended for rank-deficient matrices.
+
+    It can further be generalized for non-square matrices, and this
+    is the notation that SymPy is using.
+
+    PLU decomposition is a decomposition of a $m, n$ matrix $A$ in
+    the form of $P A = L U$ where
+
+    * $L$ is a $m, m$ lower triangular matrix with unit diagonal
+        entries.
+    * $U$ is a $m, n$ upper triangular matrix.
+    * $P$ is a $m, m$ permutation matrix.
+
+    So, for a square matrix, the decomposition would look like:
+
+    .. math::
+        L = \begin{bmatrix}
+        1 & 0 & 0 & \cdots & 0 \\
+        L_{1, 0} & 1 & 0 & \cdots & 0 \\
+        L_{2, 0} & L_{2, 1} & 1 & \cdots & 0 \\
+        \vdots & \vdots & \vdots & \ddots & \vdots \\
+        L_{n-1, 0} & L_{n-1, 1} & L_{n-1, 2} & \cdots & 1
+        \end{bmatrix}
+
+    .. math::
+        U = \begin{bmatrix}
+        U_{0, 0} & U_{0, 1} & U_{0, 2} & \cdots & U_{0, n-1} \\
+        0 & U_{1, 1} & U_{1, 2} & \cdots & U_{1, n-1} \\
+        0 & 0 & U_{2, 2} & \cdots & U_{2, n-1} \\
+        \vdots & \vdots & \vdots & \ddots & \vdots \\
+        0 & 0 & 0 & \cdots & U_{n-1, n-1}
+        \end{bmatrix}
+
+    And for a matrix with more rows than the columns,
+    the decomposition would look like:
+
+    .. math::
+        L = \begin{bmatrix}
+        1 & 0 & 0 & \cdots & 0 & 0 & \cdots & 0 \\
+        L_{1, 0} & 1 & 0 & \cdots & 0 & 0 & \cdots & 0 \\
+        L_{2, 0} & L_{2, 1} & 1 & \cdots & 0 & 0 & \cdots & 0 \\
+        \vdots & \vdots & \vdots & \ddots & \vdots & \vdots & \ddots
+        & \vdots \\
+        L_{n-1, 0} & L_{n-1, 1} & L_{n-1, 2} & \cdots & 1 & 0
+        & \cdots & 0 \\
+        L_{n, 0} & L_{n, 1} & L_{n, 2} & \cdots & L_{n, n-1} & 1
+        & \cdots & 0 \\
+        \vdots & \vdots & \vdots & \ddots & \vdots & \vdots
+        & \ddots & \vdots \\
+        L_{m-1, 0} & L_{m-1, 1} & L_{m-1, 2} & \cdots & L_{m-1, n-1}
+        & 0 & \cdots & 1 \\
+        \end{bmatrix}
+
+    .. math::
+        U = \begin{bmatrix}
+        U_{0, 0} & U_{0, 1} & U_{0, 2} & \cdots & U_{0, n-1} \\
+        0 & U_{1, 1} & U_{1, 2} & \cdots & U_{1, n-1} \\
+        0 & 0 & U_{2, 2} & \cdots & U_{2, n-1} \\
+        \vdots & \vdots & \vdots & \ddots & \vdots \\
+        0 & 0 & 0 & \cdots & U_{n-1, n-1} \\
+        0 & 0 & 0 & \cdots & 0 \\
+        \vdots & \vdots & \vdots & \ddots & \vdots \\
+        0 & 0 & 0 & \cdots & 0
+        \end{bmatrix}
+
+    Finally, for a matrix with more columns than the rows, the
+    decomposition would look like:
+
+    .. math::
+        L = \begin{bmatrix}
+        1 & 0 & 0 & \cdots & 0 \\
+        L_{1, 0} & 1 & 0 & \cdots & 0 \\
+        L_{2, 0} & L_{2, 1} & 1 & \cdots & 0 \\
+        \vdots & \vdots & \vdots & \ddots & \vdots \\
+        L_{m-1, 0} & L_{m-1, 1} & L_{m-1, 2} & \cdots & 1
+        \end{bmatrix}
+
+    .. math::
+        U = \begin{bmatrix}
+        U_{0, 0} & U_{0, 1} & U_{0, 2} & \cdots & U_{0, m-1}
+        & \cdots & U_{0, n-1} \\
+        0 & U_{1, 1} & U_{1, 2} & \cdots & U_{1, m-1}
+        & \cdots & U_{1, n-1} \\
+        0 & 0 & U_{2, 2} & \cdots & U_{2, m-1}
+        & \cdots & U_{2, n-1} \\
+        \vdots & \vdots & \vdots & \ddots & \vdots
+        & \cdots & \vdots \\
+        0 & 0 & 0 & \cdots & U_{m-1, m-1}
+        & \cdots & U_{m-1, n-1} \\
+        \end{bmatrix}
+
+    About the compressed LU storage:
+
+    The results of the decomposition are often stored in compressed
+    forms rather than returning $L$ and $U$ matrices individually.
+
+    It may be less intiuitive, but it is commonly used for a lot of
+    numeric libraries because of the efficiency.
+
+    The storage matrix is defined as following for this specific
+    method:
+
+    * The subdiagonal elements of $L$ are stored in the subdiagonal
+        portion of $LU$, that is $LU_{i, j} = L_{i, j}$ whenever
+        $i > j$.
+    * The elements on the diagonal of $L$ are all 1, and are not
+        explicitly stored.
+    * $U$ is stored in the upper triangular portion of $LU$, that is
+        $LU_{i, j} = U_{i, j}$ whenever $i <= j$.
+    * For a case of $m > n$, the right side of the $L$ matrix is
+        trivial to store.
+    * For a case of $m < n$, the below side of the $U$ matrix is
+        trivial to store.
+
+    So, for a square matrix, the compressed output matrix would be:
+
+    .. math::
+        LU = \begin{bmatrix}
+        U_{0, 0} & U_{0, 1} & U_{0, 2} & \cdots & U_{0, n-1} \\
+        L_{1, 0} & U_{1, 1} & U_{1, 2} & \cdots & U_{1, n-1} \\
+        L_{2, 0} & L_{2, 1} & U_{2, 2} & \cdots & U_{2, n-1} \\
+        \vdots & \vdots & \vdots & \ddots & \vdots \\
+        L_{n-1, 0} & L_{n-1, 1} & L_{n-1, 2} & \cdots & U_{n-1, n-1}
+        \end{bmatrix}
+
+    For a matrix with more rows than the columns, the compressed
+    output matrix would be:
+
+    .. math::
+        LU = \begin{bmatrix}
+        U_{0, 0} & U_{0, 1} & U_{0, 2} & \cdots & U_{0, n-1} \\
+        L_{1, 0} & U_{1, 1} & U_{1, 2} & \cdots & U_{1, n-1} \\
+        L_{2, 0} & L_{2, 1} & U_{2, 2} & \cdots & U_{2, n-1} \\
+        \vdots & \vdots & \vdots & \ddots & \vdots \\
+        L_{n-1, 0} & L_{n-1, 1} & L_{n-1, 2} & \cdots
+        & U_{n-1, n-1} \\
+        \vdots & \vdots & \vdots & \ddots & \vdots \\
+        L_{m-1, 0} & L_{m-1, 1} & L_{m-1, 2} & \cdots
+        & L_{m-1, n-1} \\
+        \end{bmatrix}
+
+    For a matrix with more columns than the rows, the compressed
+    output matrix would be:
+
+    .. math::
+        LU = \begin{bmatrix}
+        U_{0, 0} & U_{0, 1} & U_{0, 2} & \cdots & U_{0, m-1}
+        & \cdots & U_{0, n-1} \\
+        L_{1, 0} & U_{1, 1} & U_{1, 2} & \cdots & U_{1, m-1}
+        & \cdots & U_{1, n-1} \\
+        L_{2, 0} & L_{2, 1} & U_{2, 2} & \cdots & U_{2, m-1}
+        & \cdots & U_{2, n-1} \\
+        \vdots & \vdots & \vdots & \ddots & \vdots
+        & \cdots & \vdots \\
+        L_{m-1, 0} & L_{m-1, 1} & L_{m-1, 2} & \cdots & U_{m-1, m-1}
+        & \cdots & U_{m-1, n-1} \\
+        \end{bmatrix}
+
+    About the pivot searching algorithm:
+
+    When a matrix contains symbolic entries, the pivot search algorithm
+    differs from the case where every entry can be categorized as zero or
+    nonzero.
+    The algorithm searches column by column through the submatrix whose
+    top left entry coincides with the pivot position.
+    If it exists, the pivot is the first entry in the current search
+    column that iszerofunc guarantees is nonzero.
+    If no such candidate exists, then each candidate pivot is simplified
+    if simpfunc is not None.
+    The search is repeated, with the difference that a candidate may be
+    the pivot if ``iszerofunc()`` cannot guarantee that it is nonzero.
+    In the second search the pivot is the first candidate that
+    iszerofunc can guarantee is nonzero.
+    If no such candidate exists, then the pivot is the first candidate
+    for which iszerofunc returns None.
+    If no such candidate exists, then the search is repeated in the next
+    column to the right.
+    The pivot search algorithm differs from the one in ``rref()``, which
+    relies on ``_find_reasonable_pivot()``.
+    Future versions of ``LUdecomposition_simple()`` may use
+    ``_find_reasonable_pivot()``.
+
+    See Also
+    ========
+
+    sympy.matrices.matrixbase.MatrixBase.LUdecomposition
+    LUdecompositionFF
+    LUsolve
+    """
+
+    if rankcheck:
+        # https://github.com/sympy/sympy/issues/9796
+        pass
+
+    if S.Zero in M.shape:
+        # Define LU decomposition of a matrix with no entries as a matrix
+        # of the same dimensions with all zero entries.
+        return M.zeros(M.rows, M.cols), []
+
+    dps       = _get_intermediate_simp()
+    lu        = M.as_mutable()
+    row_swaps = []
+
+    pivot_col = 0
+
+    for pivot_row in range(0, lu.rows - 1):
+        # Search for pivot. Prefer entry that iszeropivot determines
+        # is nonzero, over entry that iszeropivot cannot guarantee
+        # is  zero.
+        # XXX ``_find_reasonable_pivot`` uses slow zero testing. Blocked by bug #10279
+        # Future versions of LUdecomposition_simple can pass iszerofunc and simpfunc
+        # to _find_reasonable_pivot().
+        # In pass 3 of _find_reasonable_pivot(), the predicate in ``if x.equals(S.Zero):``
+        # calls sympy.simplify(), and not the simplification function passed in via
+        # the keyword argument simpfunc.
+        iszeropivot = True
+
+        while pivot_col != M.cols and iszeropivot:
+            sub_col = (lu[r, pivot_col] for r in range(pivot_row, M.rows))
+
+            pivot_row_offset, pivot_value, is_assumed_non_zero, ind_simplified_pairs =\
+                _find_reasonable_pivot_naive(sub_col, iszerofunc, simpfunc)
+
+            iszeropivot = pivot_value is None
+
+            if iszeropivot:
+                # All candidate pivots in this column are zero.
+                # Proceed to next column.
+                pivot_col += 1
+
+        if rankcheck and pivot_col != pivot_row:
+            # All entries including and below the pivot position are
+            # zero, which indicates that the rank of the matrix is
+            # strictly less than min(num rows, num cols)
+            # Mimic behavior of previous implementation, by throwing a
+            # ValueError.
+            raise ValueError("Rank of matrix is strictly less than"
+                                " number of rows or columns."
+                                " Pass keyword argument"
+                                " rankcheck=False to compute"
+                                " the LU decomposition of this matrix.")
+
+        candidate_pivot_row = None if pivot_row_offset is None else pivot_row + pivot_row_offset
+
+        if candidate_pivot_row is None and iszeropivot:
+            # If candidate_pivot_row is None and iszeropivot is True
+            # after pivot search has completed, then the submatrix
+            # below and to the right of (pivot_row, pivot_col) is
+            # all zeros, indicating that Gaussian elimination is
+            # complete.
+            return lu, row_swaps
+
+        # Update entries simplified during pivot search.
+        for offset, val in ind_simplified_pairs:
+            lu[pivot_row + offset, pivot_col] = val
+
+        if pivot_row != candidate_pivot_row:
+            # Row swap book keeping:
+            # Record which rows were swapped.
+            # Update stored portion of L factor by multiplying L on the
+            # left and right with the current permutation.
+            # Swap rows of U.
+            row_swaps.append([pivot_row, candidate_pivot_row])
+
+            # Update L.
+            lu[pivot_row, 0:pivot_row], lu[candidate_pivot_row, 0:pivot_row] = \
+                lu[candidate_pivot_row, 0:pivot_row], lu[pivot_row, 0:pivot_row]
+
+            # Swap pivot row of U with candidate pivot row.
+            lu[pivot_row, pivot_col:lu.cols], lu[candidate_pivot_row, pivot_col:lu.cols] = \
+                lu[candidate_pivot_row, pivot_col:lu.cols], lu[pivot_row, pivot_col:lu.cols]
+
+        # Introduce zeros below the pivot by adding a multiple of the
+        # pivot row to a row under it, and store the result in the
+        # row under it.
+        # Only entries in the target row whose index is greater than
+        # start_col may be nonzero.
+        start_col = pivot_col + 1
+
+        for row in range(pivot_row + 1, lu.rows):
+            # Store factors of L in the subcolumn below
+            # (pivot_row, pivot_row).
+            lu[row, pivot_row] = \
+                dps(lu[row, pivot_col]/lu[pivot_row, pivot_col])
+
+            # Form the linear combination of the pivot row and the current
+            # row below the pivot row that zeros the entries below the pivot.
+            # Employing slicing instead of a loop here raises
+            # NotImplementedError: Cannot add Zero to MutableSparseMatrix
+            # in sympy/matrices/tests/test_sparse.py.
+            # c = pivot_row + 1 if pivot_row == pivot_col else pivot_col
+            for c in range(start_col, lu.cols):
+                lu[row, c] = dps(lu[row, c] - lu[row, pivot_row]*lu[pivot_row, c])
+
+        if pivot_row != pivot_col:
+            # matrix rank < min(num rows, num cols),
+            # so factors of L are not stored directly below the pivot.
+            # These entries are zero by construction, so don't bother
+            # computing them.
+            for row in range(pivot_row + 1, lu.rows):
+                lu[row, pivot_col] = M.zero
+
+        pivot_col += 1
+
+        if pivot_col == lu.cols:
+            # All candidate pivots are zero implies that Gaussian
+            # elimination is complete.
+            return lu, row_swaps
+
+    if rankcheck:
+        if iszerofunc(
+                lu[Min(lu.rows, lu.cols) - 1, Min(lu.rows, lu.cols) - 1]):
+            raise ValueError("Rank of matrix is strictly less than"
+                                " number of rows or columns."
+                                " Pass keyword argument"
+                                " rankcheck=False to compute"
+                                " the LU decomposition of this matrix.")
+
+    return lu, row_swaps
+
+def _LUdecompositionFF(M):
+    """Compute a fraction-free LU decomposition.
+
+    Returns 4 matrices P, L, D, U such that PA = L D**-1 U.
+    If the elements of the matrix belong to some integral domain I, then all
+    elements of L, D and U are guaranteed to belong to I.
+
+    See Also
+    ========
+
+    sympy.matrices.matrixbase.MatrixBase.LUdecomposition
+    LUdecomposition_Simple
+    LUsolve
+
+    References
+    ==========
+
+    .. [1] W. Zhou & D.J. Jeffrey, "Fraction-free matrix factors: new forms
+        for LU and QR factors". Frontiers in Computer Science in China,
+        Vol 2, no. 1, pp. 67-80, 2008.
+    """
+
+    from sympy.matrices import SparseMatrix
+
+    zeros    = SparseMatrix.zeros
+    eye      = SparseMatrix.eye
+    n, m     = M.rows, M.cols
+    U, L, P  = M.as_mutable(), eye(n), eye(n)
+    DD       = zeros(n, n)
+    oldpivot = 1
+
+    for k in range(n - 1):
+        if U[k, k] == 0:
+            for kpivot in range(k + 1, n):
+                if U[kpivot, k]:
+                    break
+            else:
+                raise ValueError("Matrix is not full rank")
+
+            U[k, k:], U[kpivot, k:] = U[kpivot, k:], U[k, k:]
+            L[k, :k], L[kpivot, :k] = L[kpivot, :k], L[k, :k]
+            P[k, :], P[kpivot, :]   = P[kpivot, :], P[k, :]
+
+        L [k, k] = Ukk = U[k, k]
+        DD[k, k] = oldpivot * Ukk
+
+        for i in range(k + 1, n):
+            L[i, k] = Uik = U[i, k]
+
+            for j in range(k + 1, m):
+                U[i, j] = (Ukk * U[i, j] - U[k, j] * Uik) / oldpivot
+
+            U[i, k] = 0
+
+        oldpivot = Ukk
+
+    DD[n - 1, n - 1] = oldpivot
+
+    return P, L, DD, U
+
+def _singular_value_decomposition(A):
+    r"""Returns a Condensed Singular Value decomposition.
+
+    Explanation
+    ===========
+
+    A Singular Value decomposition is a decomposition in the form $A = U \Sigma V^H$
+    where
+
+    - $U, V$ are column orthogonal matrix.
+    - $\Sigma$ is a diagonal matrix, where the main diagonal contains singular
+      values of matrix A.
+
+    A column orthogonal matrix satisfies
+    $\mathbb{I} = U^H U$ while a full orthogonal matrix satisfies
+    relation $\mathbb{I} = U U^H = U^H U$ where $\mathbb{I}$ is an identity
+    matrix with matching dimensions.
+
+    For matrices which are not square or are rank-deficient, it is
+    sufficient to return a column orthogonal matrix because augmenting
+    them may introduce redundant computations.
+    In condensed Singular Value Decomposition we only return column orthogonal
+    matrices because of this reason
+
+    If you want to augment the results to return a full orthogonal
+    decomposition, you should use the following procedures.
+
+    - Augment the $U, V$ matrices with columns that are orthogonal to every
+      other columns and make it square.
+    - Augment the $\Sigma$ matrix with zero rows to make it have the same
+      shape as the original matrix.
+
+    The procedure will be illustrated in the examples section.
+
+    Examples
+    ========
+
+    we take a full rank matrix first:
+
+    >>> from sympy import Matrix
+    >>> A = Matrix([[1, 2],[2,1]])
+    >>> U, S, V = A.singular_value_decomposition()
+    >>> U
+    Matrix([
+    [ sqrt(2)/2, sqrt(2)/2],
+    [-sqrt(2)/2, sqrt(2)/2]])
+    >>> S
+    Matrix([
+    [1, 0],
+    [0, 3]])
+    >>> V
+    Matrix([
+    [-sqrt(2)/2, sqrt(2)/2],
+    [ sqrt(2)/2, sqrt(2)/2]])
+
+    If a matrix if square and full rank both U, V
+    are orthogonal in both directions
+
+    >>> U * U.H
+    Matrix([
+    [1, 0],
+    [0, 1]])
+    >>> U.H * U
+    Matrix([
+    [1, 0],
+    [0, 1]])
+
+    >>> V * V.H
+    Matrix([
+    [1, 0],
+    [0, 1]])
+    >>> V.H * V
+    Matrix([
+    [1, 0],
+    [0, 1]])
+    >>> A == U * S * V.H
+    True
+
+    >>> C = Matrix([
+    ...         [1, 0, 0, 0, 2],
+    ...         [0, 0, 3, 0, 0],
+    ...         [0, 0, 0, 0, 0],
+    ...         [0, 2, 0, 0, 0],
+    ...     ])
+    >>> U, S, V = C.singular_value_decomposition()
+
+    >>> V.H * V
+    Matrix([
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1]])
+    >>> V * V.H
+    Matrix([
+    [1/5, 0, 0, 0, 2/5],
+    [  0, 1, 0, 0,   0],
+    [  0, 0, 1, 0,   0],
+    [  0, 0, 0, 0,   0],
+    [2/5, 0, 0, 0, 4/5]])
+
+    If you want to augment the results to be a full orthogonal
+    decomposition, you should augment $V$ with an another orthogonal
+    column.
+
+    You are able to append an arbitrary standard basis that are linearly
+    independent to every other columns and you can run the Gram-Schmidt
+    process to make them augmented as orthogonal basis.
+
+    >>> V_aug = V.row_join(Matrix([[0,0,0,0,1],
+    ... [0,0,0,1,0]]).H)
+    >>> V_aug = V_aug.QRdecomposition()[0]
+    >>> V_aug
+    Matrix([
+    [0,   sqrt(5)/5, 0, -2*sqrt(5)/5, 0],
+    [1,           0, 0,            0, 0],
+    [0,           0, 1,            0, 0],
+    [0,           0, 0,            0, 1],
+    [0, 2*sqrt(5)/5, 0,    sqrt(5)/5, 0]])
+    >>> V_aug.H * V_aug
+    Matrix([
+    [1, 0, 0, 0, 0],
+    [0, 1, 0, 0, 0],
+    [0, 0, 1, 0, 0],
+    [0, 0, 0, 1, 0],
+    [0, 0, 0, 0, 1]])
+    >>> V_aug * V_aug.H
+    Matrix([
+    [1, 0, 0, 0, 0],
+    [0, 1, 0, 0, 0],
+    [0, 0, 1, 0, 0],
+    [0, 0, 0, 1, 0],
+    [0, 0, 0, 0, 1]])
+
+    Similarly we augment U
+
+    >>> U_aug = U.row_join(Matrix([0,0,1,0]))
+    >>> U_aug = U_aug.QRdecomposition()[0]
+    >>> U_aug
+    Matrix([
+    [0, 1, 0, 0],
+    [0, 0, 1, 0],
+    [0, 0, 0, 1],
+    [1, 0, 0, 0]])
+
+    >>> U_aug.H * U_aug
+    Matrix([
+    [1, 0, 0, 0],
+    [0, 1, 0, 0],
+    [0, 0, 1, 0],
+    [0, 0, 0, 1]])
+    >>> U_aug * U_aug.H
+    Matrix([
+    [1, 0, 0, 0],
+    [0, 1, 0, 0],
+    [0, 0, 1, 0],
+    [0, 0, 0, 1]])
+
+    We add 2 zero columns and one row to S
+
+    >>> S_aug = S.col_join(Matrix([[0,0,0]]))
+    >>> S_aug = S_aug.row_join(Matrix([[0,0,0,0],
+    ... [0,0,0,0]]).H)
+    >>> S_aug
+    Matrix([
+    [2,       0, 0, 0, 0],
+    [0, sqrt(5), 0, 0, 0],
+    [0,       0, 3, 0, 0],
+    [0,       0, 0, 0, 0]])
+
+
+
+    >>> U_aug * S_aug * V_aug.H == C
+    True
+
+    """
+
+    AH = A.H
+    m, n = A.shape
+    if m >= n:
+        V, S = (AH * A).diagonalize()
+
+        ranked = []
+        for i, x in enumerate(S.diagonal()):
+            if not x.is_zero:
+                ranked.append(i)
+
+        V = V[:, ranked]
+
+        Singular_vals = [sqrt(S[i, i]) for i in range(S.rows) if i in ranked]
+
+        S = S.diag(*Singular_vals)
+        V, _ = V.QRdecomposition()
+        U = A * V * S.inv()
+    else:
+        U, S = (A * AH).diagonalize()
+
+        ranked = []
+        for i, x in enumerate(S.diagonal()):
+            if not x.is_zero:
+                ranked.append(i)
+
+        U = U[:, ranked]
+        Singular_vals = [sqrt(S[i, i]) for i in range(S.rows) if i in ranked]
+
+        S = S.diag(*Singular_vals)
+        U, _ = U.QRdecomposition()
+        V = AH * U * S.inv()
+
+    return U, S, V
+
+def _QRdecomposition_optional(M, normalize=True):
+    def dot(u, v):
+        return u.dot(v, hermitian=True)
+
+    dps = _get_intermediate_simp(expand_mul, expand_mul)
+
+    A = M.as_mutable()
+    ranked = []
+
+    Q = A
+    R = A.zeros(A.cols)
+
+    for j in range(A.cols):
+        for i in range(j):
+            if Q[:, i].is_zero_matrix:
+                continue
+
+            R[i, j] = dot(Q[:, i], Q[:, j]) / dot(Q[:, i], Q[:, i])
+            R[i, j] = dps(R[i, j])
+            Q[:, j] -= Q[:, i] * R[i, j]
+
+        Q[:, j] = dps(Q[:, j])
+        if Q[:, j].is_zero_matrix is not True:
+            ranked.append(j)
+            R[j, j] = M.one
+
+    Q = Q.extract(range(Q.rows), ranked)
+    R = R.extract(ranked, range(R.cols))
+
+    if normalize:
+        # Normalization
+        for i in range(Q.cols):
+            norm = Q[:, i].norm()
+            Q[:, i] /= norm
+            R[i, :] *= norm
+
+    return M.__class__(Q), M.__class__(R)
+
+
+def _QRdecomposition(M):
+    r"""Returns a QR decomposition.
+
+    Explanation
+    ===========
+
+    A QR decomposition is a decomposition in the form $A = Q R$
+    where
+
+    - $Q$ is a column orthogonal matrix.
+    - $R$ is a upper triangular (trapezoidal) matrix.
+
+    A column orthogonal matrix satisfies
+    $\mathbb{I} = Q^H Q$ while a full orthogonal matrix satisfies
+    relation $\mathbb{I} = Q Q^H = Q^H Q$ where $I$ is an identity
+    matrix with matching dimensions.
+
+    For matrices which are not square or are rank-deficient, it is
+    sufficient to return a column orthogonal matrix because augmenting
+    them may introduce redundant computations.
+    And an another advantage of this is that you can easily inspect the
+    matrix rank by counting the number of columns of $Q$.
+
+    If you want to augment the results to return a full orthogonal
+    decomposition, you should use the following procedures.
+
+    - Augment the $Q$ matrix with columns that are orthogonal to every
+      other columns and make it square.
+    - Augment the $R$ matrix with zero rows to make it have the same
+      shape as the original matrix.
+
+    The procedure will be illustrated in the examples section.
+
+    Examples
+    ========
+
+    A full rank matrix example:
+
+    >>> from sympy import Matrix
+    >>> A = Matrix([[12, -51, 4], [6, 167, -68], [-4, 24, -41]])
+    >>> Q, R = A.QRdecomposition()
+    >>> Q
+    Matrix([
+    [ 6/7, -69/175, -58/175],
+    [ 3/7, 158/175,   6/175],
+    [-2/7,    6/35,  -33/35]])
+    >>> R
+    Matrix([
+    [14,  21, -14],
+    [ 0, 175, -70],
+    [ 0,   0,  35]])
+
+    If the matrix is square and full rank, the $Q$ matrix becomes
+    orthogonal in both directions, and needs no augmentation.
+
+    >>> Q * Q.H
+    Matrix([
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1]])
+    >>> Q.H * Q
+    Matrix([
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1]])
+
+    >>> A == Q*R
+    True
+
+    A rank deficient matrix example:
+
+    >>> A = Matrix([[12, -51, 0], [6, 167, 0], [-4, 24, 0]])
+    >>> Q, R = A.QRdecomposition()
+    >>> Q
+    Matrix([
+    [ 6/7, -69/175],
+    [ 3/7, 158/175],
+    [-2/7,    6/35]])
+    >>> R
+    Matrix([
+    [14,  21, 0],
+    [ 0, 175, 0]])
+
+    QRdecomposition might return a matrix Q that is rectangular.
+    In this case the orthogonality condition might be satisfied as
+    $\mathbb{I} = Q.H*Q$ but not in the reversed product
+    $\mathbb{I} = Q * Q.H$.
+
+    >>> Q.H * Q
+    Matrix([
+    [1, 0],
+    [0, 1]])
+    >>> Q * Q.H
+    Matrix([
+    [27261/30625,   348/30625, -1914/6125],
+    [  348/30625, 30589/30625,   198/6125],
+    [ -1914/6125,    198/6125,   136/1225]])
+
+    If you want to augment the results to be a full orthogonal
+    decomposition, you should augment $Q$ with an another orthogonal
+    column.
+
+    You are able to append an identity matrix,
+    and you can run the Gram-Schmidt
+    process to make them augmented as orthogonal basis.
+
+    >>> Q_aug = Q.row_join(Matrix.eye(3))
+    >>> Q_aug = Q_aug.QRdecomposition()[0]
+    >>> Q_aug
+    Matrix([
+    [ 6/7, -69/175, 58/175],
+    [ 3/7, 158/175, -6/175],
+    [-2/7,    6/35,  33/35]])
+    >>> Q_aug.H * Q_aug
+    Matrix([
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1]])
+    >>> Q_aug * Q_aug.H
+    Matrix([
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1]])
+
+    Augmenting the $R$ matrix with zero row is straightforward.
+
+    >>> R_aug = R.col_join(Matrix([[0, 0, 0]]))
+    >>> R_aug
+    Matrix([
+    [14,  21, 0],
+    [ 0, 175, 0],
+    [ 0,   0, 0]])
+    >>> Q_aug * R_aug == A
+    True
+
+    A zero matrix example:
+
+    >>> from sympy import Matrix
+    >>> A = Matrix.zeros(3, 4)
+    >>> Q, R = A.QRdecomposition()
+
+    They may return matrices with zero rows and columns.
+
+    >>> Q
+    Matrix(3, 0, [])
+    >>> R
+    Matrix(0, 4, [])
+    >>> Q*R
+    Matrix([
+    [0, 0, 0, 0],
+    [0, 0, 0, 0],
+    [0, 0, 0, 0]])
+
+    As the same augmentation rule described above, $Q$ can be augmented
+    with columns of an identity matrix and $R$ can be augmented with
+    rows of a zero matrix.
+
+    >>> Q_aug = Q.row_join(Matrix.eye(3))
+    >>> R_aug = R.col_join(Matrix.zeros(3, 4))
+    >>> Q_aug * Q_aug.T
+    Matrix([
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1]])
+    >>> R_aug
+    Matrix([
+    [0, 0, 0, 0],
+    [0, 0, 0, 0],
+    [0, 0, 0, 0]])
+    >>> Q_aug * R_aug == A
+    True
+
+    See Also
+    ========
+
+    sympy.matrices.dense.DenseMatrix.cholesky
+    sympy.matrices.dense.DenseMatrix.LDLdecomposition
+    sympy.matrices.matrixbase.MatrixBase.LUdecomposition
+    QRsolve
+    """
+    return _QRdecomposition_optional(M, normalize=True)
+
+def _upper_hessenberg_decomposition(A):
+    """Converts a matrix into Hessenberg matrix H.
+
+    Returns 2 matrices H, P s.t.
+    $P H P^{T} = A$, where H is an upper hessenberg matrix
+    and P is an orthogonal matrix
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> A = Matrix([
+    ...     [1,2,3],
+    ...     [-3,5,6],
+    ...     [4,-8,9],
+    ... ])
+    >>> H, P = A.upper_hessenberg_decomposition()
+    >>> H
+    Matrix([
+    [1,    6/5,    17/5],
+    [5, 213/25, -134/25],
+    [0, 216/25,  137/25]])
+    >>> P
+    Matrix([
+    [1,    0,   0],
+    [0, -3/5, 4/5],
+    [0,  4/5, 3/5]])
+    >>> P * H * P.H == A
+    True
+
+
+    References
+    ==========
+
+    .. [#] https://mathworld.wolfram.com/HessenbergDecomposition.html
+    """
+
+    M = A.as_mutable()
+
+    if not M.is_square:
+        raise NonSquareMatrixError("Matrix must be square.")
+
+    n = M.cols
+    P = M.eye(n)
+    H = M
+
+    for j in range(n - 2):
+
+        u = H[j + 1:, j]
+
+        if u[1:, :].is_zero_matrix:
+            continue
+
+        if sign(u[0]) != 0:
+            u[0] = u[0] + sign(u[0]) * u.norm()
+        else:
+            u[0] = u[0] + u.norm()
+
+        v = u / u.norm()
+
+        H[j + 1:, :] = H[j + 1:, :] - 2 * v * (v.H * H[j + 1:, :])
+        H[:, j + 1:] = H[:, j + 1:] - (H[:, j + 1:] * (2 * v)) * v.H
+        P[:, j + 1:] = P[:, j + 1:] - (P[:, j + 1:] * (2 * v)) * v.H
+
+    return H, P

lib/python3.12/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

lib/python3.12/site-packages/sympy/matrices/graph.py

@@ -0,0 +1,279 @@
+from sympy.utilities.iterables import \
+    flatten, connected_components, strongly_connected_components
+from .exceptions import NonSquareMatrixError
+
+
+def _connected_components(M):
+    """Returns the list of connected vertices of the graph when
+    a square matrix is viewed as a weighted graph.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> A = Matrix([
+    ...     [66, 0, 0, 68, 0, 0, 0, 0, 67],
+    ...     [0, 55, 0, 0, 0, 0, 54, 53, 0],
+    ...     [0, 0, 0, 0, 1, 2, 0, 0, 0],
+    ...     [86, 0, 0, 88, 0, 0, 0, 0, 87],
+    ...     [0, 0, 10, 0, 11, 12, 0, 0, 0],
+    ...     [0, 0, 20, 0, 21, 22, 0, 0, 0],
+    ...     [0, 45, 0, 0, 0, 0, 44, 43, 0],
+    ...     [0, 35, 0, 0, 0, 0, 34, 33, 0],
+    ...     [76, 0, 0, 78, 0, 0, 0, 0, 77]])
+    >>> A.connected_components()
+    [[0, 3, 8], [1, 6, 7], [2, 4, 5]]
+
+    Notes
+    =====
+
+    Even if any symbolic elements of the matrix can be indeterminate
+    to be zero mathematically, this only takes the account of the
+    structural aspect of the matrix, so they will considered to be
+    nonzero.
+    """
+    if not M.is_square:
+        raise NonSquareMatrixError
+
+    V = range(M.rows)
+    E = sorted(M.todok().keys())
+    return connected_components((V, E))
+
+
+def _strongly_connected_components(M):
+    """Returns the list of strongly connected vertices of the graph when
+    a square matrix is viewed as a weighted graph.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> A = Matrix([
+    ...     [44, 0, 0, 0, 43, 0, 45, 0, 0],
+    ...     [0, 66, 62, 61, 0, 68, 0, 60, 67],
+    ...     [0, 0, 22, 21, 0, 0, 0, 20, 0],
+    ...     [0, 0, 12, 11, 0, 0, 0, 10, 0],
+    ...     [34, 0, 0, 0, 33, 0, 35, 0, 0],
+    ...     [0, 86, 82, 81, 0, 88, 0, 80, 87],
+    ...     [54, 0, 0, 0, 53, 0, 55, 0, 0],
+    ...     [0, 0, 2, 1, 0, 0, 0, 0, 0],
+    ...     [0, 76, 72, 71, 0, 78, 0, 70, 77]])
+    >>> A.strongly_connected_components()
+    [[0, 4, 6], [2, 3, 7], [1, 5, 8]]
+    """
+    if not M.is_square:
+        raise NonSquareMatrixError
+
+    # RepMatrix uses the more efficient DomainMatrix.scc() method
+    rep = getattr(M, '_rep', None)
+    if rep is not None:
+        return rep.scc()
+
+    V = range(M.rows)
+    E = sorted(M.todok().keys())
+    return strongly_connected_components((V, E))
+
+
+def _connected_components_decomposition(M):
+    """Decomposes a square matrix into block diagonal form only
+    using the permutations.
+
+    Explanation
+    ===========
+
+    The decomposition is in a form of $A = P^{-1} B P$ where $P$ is a
+    permutation matrix and $B$ is a block diagonal matrix.
+
+    Returns
+    =======
+
+    P, B : PermutationMatrix, BlockDiagMatrix
+        *P* is a permutation matrix for the similarity transform
+        as in the explanation. And *B* is the block diagonal matrix of
+        the result of the permutation.
+
+        If you would like to get the diagonal blocks from the
+        BlockDiagMatrix, see
+        :meth:`~sympy.matrices.expressions.blockmatrix.BlockDiagMatrix.get_diag_blocks`.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix, pprint
+    >>> A = Matrix([
+    ...     [66, 0, 0, 68, 0, 0, 0, 0, 67],
+    ...     [0, 55, 0, 0, 0, 0, 54, 53, 0],
+    ...     [0, 0, 0, 0, 1, 2, 0, 0, 0],
+    ...     [86, 0, 0, 88, 0, 0, 0, 0, 87],
+    ...     [0, 0, 10, 0, 11, 12, 0, 0, 0],
+    ...     [0, 0, 20, 0, 21, 22, 0, 0, 0],
+    ...     [0, 45, 0, 0, 0, 0, 44, 43, 0],
+    ...     [0, 35, 0, 0, 0, 0, 34, 33, 0],
+    ...     [76, 0, 0, 78, 0, 0, 0, 0, 77]])
+
+    >>> P, B = A.connected_components_decomposition()
+    >>> pprint(P)
+    PermutationMatrix((1 3)(2 8 5 7 4 6))
+    >>> pprint(B)
+    [[66  68  67]                            ]
+    [[          ]                            ]
+    [[86  88  87]       0             0      ]
+    [[          ]                            ]
+    [[76  78  77]                            ]
+    [                                        ]
+    [              [55  54  53]              ]
+    [              [          ]              ]
+    [     0        [45  44  43]       0      ]
+    [              [          ]              ]
+    [              [35  34  33]              ]
+    [                                        ]
+    [                            [0   1   2 ]]
+    [                            [          ]]
+    [     0             0        [10  11  12]]
+    [                            [          ]]
+    [                            [20  21  22]]
+
+    >>> P = P.as_explicit()
+    >>> B = B.as_explicit()
+    >>> P.T*B*P == A
+    True
+
+    Notes
+    =====
+
+    This problem corresponds to the finding of the connected components
+    of a graph, when a matrix is viewed as a weighted graph.
+    """
+    from sympy.combinatorics.permutations import Permutation
+    from sympy.matrices.expressions.blockmatrix import BlockDiagMatrix
+    from sympy.matrices.expressions.permutation import PermutationMatrix
+
+    iblocks = M.connected_components()
+
+    p = Permutation(flatten(iblocks))
+    P = PermutationMatrix(p)
+
+    blocks = []
+    for b in iblocks:
+        blocks.append(M[b, b])
+    B = BlockDiagMatrix(*blocks)
+    return P, B
+
+
+def _strongly_connected_components_decomposition(M, lower=True):
+    """Decomposes a square matrix into block triangular form only
+    using the permutations.
+
+    Explanation
+    ===========
+
+    The decomposition is in a form of $A = P^{-1} B P$ where $P$ is a
+    permutation matrix and $B$ is a block diagonal matrix.
+
+    Parameters
+    ==========
+
+    lower : bool
+        Makes $B$ lower block triangular when ``True``.
+        Otherwise, makes $B$ upper block triangular.
+
+    Returns
+    =======
+
+    P, B : PermutationMatrix, BlockMatrix
+        *P* is a permutation matrix for the similarity transform
+        as in the explanation. And *B* is the block triangular matrix of
+        the result of the permutation.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix, pprint
+    >>> A = Matrix([
+    ...     [44, 0, 0, 0, 43, 0, 45, 0, 0],
+    ...     [0, 66, 62, 61, 0, 68, 0, 60, 67],
+    ...     [0, 0, 22, 21, 0, 0, 0, 20, 0],
+    ...     [0, 0, 12, 11, 0, 0, 0, 10, 0],
+    ...     [34, 0, 0, 0, 33, 0, 35, 0, 0],
+    ...     [0, 86, 82, 81, 0, 88, 0, 80, 87],
+    ...     [54, 0, 0, 0, 53, 0, 55, 0, 0],
+    ...     [0, 0, 2, 1, 0, 0, 0, 0, 0],
+    ...     [0, 76, 72, 71, 0, 78, 0, 70, 77]])
+
+    A lower block triangular decomposition:
+
+    >>> P, B = A.strongly_connected_components_decomposition()
+    >>> pprint(P)
+    PermutationMatrix((8)(1 4 3 2 6)(5 7))
+    >>> pprint(B)
+    [[44  43  45]   [0  0  0]     [0  0  0]  ]
+    [[          ]   [       ]     [       ]  ]
+    [[34  33  35]   [0  0  0]     [0  0  0]  ]
+    [[          ]   [       ]     [       ]  ]
+    [[54  53  55]   [0  0  0]     [0  0  0]  ]
+    [                                        ]
+    [ [0  0  0]    [22  21  20]   [0  0  0]  ]
+    [ [       ]    [          ]   [       ]  ]
+    [ [0  0  0]    [12  11  10]   [0  0  0]  ]
+    [ [       ]    [          ]   [       ]  ]
+    [ [0  0  0]    [2   1   0 ]   [0  0  0]  ]
+    [                                        ]
+    [ [0  0  0]    [62  61  60]  [66  68  67]]
+    [ [       ]    [          ]  [          ]]
+    [ [0  0  0]    [82  81  80]  [86  88  87]]
+    [ [       ]    [          ]  [          ]]
+    [ [0  0  0]    [72  71  70]  [76  78  77]]
+
+    >>> P = P.as_explicit()
+    >>> B = B.as_explicit()
+    >>> P.T * B * P == A
+    True
+
+    An upper block triangular decomposition:
+
+    >>> P, B = A.strongly_connected_components_decomposition(lower=False)
+    >>> pprint(P)
+    PermutationMatrix((0 1 5 7 4 3 2 8 6))
+    >>> pprint(B)
+    [[66  68  67]  [62  61  60]   [0  0  0]  ]
+    [[          ]  [          ]   [       ]  ]
+    [[86  88  87]  [82  81  80]   [0  0  0]  ]
+    [[          ]  [          ]   [       ]  ]
+    [[76  78  77]  [72  71  70]   [0  0  0]  ]
+    [                                        ]
+    [ [0  0  0]    [22  21  20]   [0  0  0]  ]
+    [ [       ]    [          ]   [       ]  ]
+    [ [0  0  0]    [12  11  10]   [0  0  0]  ]
+    [ [       ]    [          ]   [       ]  ]
+    [ [0  0  0]    [2   1   0 ]   [0  0  0]  ]
+    [                                        ]
+    [ [0  0  0]     [0  0  0]    [44  43  45]]
+    [ [       ]     [       ]    [          ]]
+    [ [0  0  0]     [0  0  0]    [34  33  35]]
+    [ [       ]     [       ]    [          ]]
+    [ [0  0  0]     [0  0  0]    [54  53  55]]
+
+    >>> P = P.as_explicit()
+    >>> B = B.as_explicit()
+    >>> P.T * B * P == A
+    True
+    """
+    from sympy.combinatorics.permutations import Permutation
+    from sympy.matrices.expressions.blockmatrix import BlockMatrix
+    from sympy.matrices.expressions.permutation import PermutationMatrix
+
+    iblocks = M.strongly_connected_components()
+    if not lower:
+        iblocks = list(reversed(iblocks))
+
+    p = Permutation(flatten(iblocks))
+    P = PermutationMatrix(p)
+
+    rows = []
+    for a in iblocks:
+        cols = []
+        for b in iblocks:
+            cols.append(M[a, b])
+        rows.append(cols)
+    B = BlockMatrix(rows)
+    return P, B

lib/python3.12/site-packages/sympy/matrices/immutable.py

@@ -0,0 +1,196 @@
+from mpmath.matrices.matrices import _matrix
+
+from sympy.core import Basic, Dict, Tuple
+from sympy.core.numbers import Integer
+from sympy.core.cache import cacheit
+from sympy.core.sympify import _sympy_converter as sympify_converter, _sympify
+from sympy.matrices.dense import DenseMatrix
+from sympy.matrices.expressions import MatrixExpr
+from sympy.matrices.matrixbase import MatrixBase
+from sympy.matrices.repmatrix import RepMatrix
+from sympy.matrices.sparse import SparseRepMatrix
+from sympy.multipledispatch import dispatch
+
+
+def sympify_matrix(arg):
+    return arg.as_immutable()
+
+
+sympify_converter[MatrixBase] = sympify_matrix
+
+
+def sympify_mpmath_matrix(arg):
+    mat = [_sympify(x) for x in arg]
+    return ImmutableDenseMatrix(arg.rows, arg.cols, mat)
+
+
+sympify_converter[_matrix] = sympify_mpmath_matrix
+
+
+class ImmutableRepMatrix(RepMatrix, MatrixExpr): # type: ignore
+    """Immutable matrix based on RepMatrix
+
+    Uses DomainMAtrix as the internal representation.
+    """
+
+    #
+    # This is a subclass of RepMatrix that adds/overrides some methods to make
+    # the instances Basic and immutable. ImmutableRepMatrix is a superclass for
+    # both ImmutableDenseMatrix and ImmutableSparseMatrix.
+    #
+
+    def __new__(cls, *args, **kwargs):
+        return cls._new(*args, **kwargs)
+
+    __hash__ = MatrixExpr.__hash__
+
+    def copy(self):
+        return self
+
+    @property
+    def cols(self):
+        return self._cols
+
+    @property
+    def rows(self):
+        return self._rows
+
+    @property
+    def shape(self):
+        return self._rows, self._cols
+
+    def as_immutable(self):
+        return self
+
+    def _entry(self, i, j, **kwargs):
+        return self[i, j]
+
+    def __setitem__(self, *args):
+        raise TypeError("Cannot set values of {}".format(self.__class__))
+
+    def is_diagonalizable(self, reals_only=False, **kwargs):
+        return super().is_diagonalizable(
+            reals_only=reals_only, **kwargs)
+
+    is_diagonalizable.__doc__ = SparseRepMatrix.is_diagonalizable.__doc__
+    is_diagonalizable = cacheit(is_diagonalizable)
+
+    def analytic_func(self, f, x):
+        return self.as_mutable().analytic_func(f, x).as_immutable()
+
+
+class ImmutableDenseMatrix(DenseMatrix, ImmutableRepMatrix):  # type: ignore
+    """Create an immutable version of a matrix.
+
+    Examples
+    ========
+
+    >>> from sympy import eye, ImmutableMatrix
+    >>> ImmutableMatrix(eye(3))
+    Matrix([
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1]])
+    >>> _[0, 0] = 42
+    Traceback (most recent call last):
+    ...
+    TypeError: Cannot set values of ImmutableDenseMatrix
+    """
+
+    # MatrixExpr is set as NotIterable, but we want explicit matrices to be
+    # iterable
+    _iterable = True
+    _class_priority = 8
+    _op_priority = 10.001
+
+    @classmethod
+    def _new(cls, *args, **kwargs):
+        if len(args) == 1 and isinstance(args[0], ImmutableDenseMatrix):
+            return args[0]
+        if kwargs.get('copy', True) is False:
+            if len(args) != 3:
+                raise TypeError("'copy=False' requires a matrix be initialized as rows,cols,[list]")
+            rows, cols, flat_list = args
+        else:
+            rows, cols, flat_list = cls._handle_creation_inputs(*args, **kwargs)
+            flat_list = list(flat_list) # create a shallow copy
+
+        rep = cls._flat_list_to_DomainMatrix(rows, cols, flat_list)
+
+        return cls._fromrep(rep)
+
+    @classmethod
+    def _fromrep(cls, rep):
+        rows, cols = rep.shape
+        flat_list = rep.to_sympy().to_list_flat()
+        obj = Basic.__new__(cls,
+            Integer(rows),
+            Integer(cols),
+            Tuple(*flat_list, sympify=False))
+        obj._rows = rows
+        obj._cols = cols
+        obj._rep = rep
+        return obj
+
+
+# make sure ImmutableDenseMatrix is aliased as ImmutableMatrix
+ImmutableMatrix = ImmutableDenseMatrix
+
+
+class ImmutableSparseMatrix(SparseRepMatrix, ImmutableRepMatrix):  # type:ignore
+    """Create an immutable version of a sparse matrix.
+
+    Examples
+    ========
+
+    >>> from sympy import eye, ImmutableSparseMatrix
+    >>> ImmutableSparseMatrix(1, 1, {})
+    Matrix([[0]])
+    >>> ImmutableSparseMatrix(eye(3))
+    Matrix([
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 0, 1]])
+    >>> _[0, 0] = 42
+    Traceback (most recent call last):
+    ...
+    TypeError: Cannot set values of ImmutableSparseMatrix
+    >>> _.shape
+    (3, 3)
+    """
+    is_Matrix = True
+    _class_priority = 9
+
+    @classmethod
+    def _new(cls, *args, **kwargs):
+        rows, cols, smat = cls._handle_creation_inputs(*args, **kwargs)
+
+        rep = cls._smat_to_DomainMatrix(rows, cols, smat)
+
+        return cls._fromrep(rep)
+
+    @classmethod
+    def _fromrep(cls, rep):
+        rows, cols = rep.shape
+        smat = rep.to_sympy().to_dok()
+        obj = Basic.__new__(cls, Integer(rows), Integer(cols), Dict(smat))
+        obj._rows = rows
+        obj._cols = cols
+        obj._rep = rep
+        return obj
+
+
+@dispatch(ImmutableDenseMatrix, ImmutableDenseMatrix)
+def _eval_is_eq(lhs, rhs): # noqa:F811
+    """Helper method for Equality with matrices.sympy.
+
+    Relational automatically converts matrices to ImmutableDenseMatrix
+    instances, so this method only applies here.  Returns True if the
+    matrices are definitively the same, False if they are definitively
+    different, and None if undetermined (e.g. if they contain Symbols).
+    Returning None triggers default handling of Equalities.
+
+    """
+    if lhs.shape != rhs.shape:
+        return False
+    return (lhs - rhs).is_zero_matrix

lib/python3.12/site-packages/sympy/matrices/matrices.py

@@ -0,0 +1,687 @@
+#
+# A module consisting of deprecated matrix classes. New code should not be
+# added here.
+#
+from sympy.core.basic import Basic
+from sympy.core.symbol import Dummy
+
+from .common import MatrixCommon
+
+from .exceptions import NonSquareMatrixError
+
+from .utilities import _iszero, _is_zero_after_expand_mul, _simplify
+
+from .determinant import (
+    _find_reasonable_pivot, _find_reasonable_pivot_naive,
+    _adjugate, _charpoly, _cofactor, _cofactor_matrix, _per,
+    _det, _det_bareiss, _det_berkowitz, _det_bird, _det_laplace, _det_LU,
+    _minor, _minor_submatrix)
+
+from .reductions import _is_echelon, _echelon_form, _rank, _rref
+from .subspaces import _columnspace, _nullspace, _rowspace, _orthogonalize
+
+from .eigen import (
+    _eigenvals, _eigenvects,
+    _bidiagonalize, _bidiagonal_decomposition,
+    _is_diagonalizable, _diagonalize,
+    _is_positive_definite, _is_positive_semidefinite,
+    _is_negative_definite, _is_negative_semidefinite, _is_indefinite,
+    _jordan_form, _left_eigenvects, _singular_values)
+
+
+# This class was previously defined in this module, but was moved to
+# sympy.matrices.matrixbase. We import it here for backwards compatibility in
+# case someone was importing it from here.
+from .matrixbase import MatrixBase
+
+
+__doctest_requires__ = {
+    ('MatrixEigen.is_indefinite',
+     'MatrixEigen.is_negative_definite',
+     'MatrixEigen.is_negative_semidefinite',
+     'MatrixEigen.is_positive_definite',
+     'MatrixEigen.is_positive_semidefinite'): ['matplotlib'],
+}
+
+
+class MatrixDeterminant(MatrixCommon):
+    """Provides basic matrix determinant operations. Should not be instantiated
+    directly. See ``determinant.py`` for their implementations."""
+
+    def _eval_det_bareiss(self, iszerofunc=_is_zero_after_expand_mul):
+        return _det_bareiss(self, iszerofunc=iszerofunc)
+
+    def _eval_det_berkowitz(self):
+        return _det_berkowitz(self)
+
+    def _eval_det_lu(self, iszerofunc=_iszero, simpfunc=None):
+        return _det_LU(self, iszerofunc=iszerofunc, simpfunc=simpfunc)
+
+    def _eval_det_bird(self):
+        return _det_bird(self)
+
+    def _eval_det_laplace(self):
+        return _det_laplace(self)
+
+    def _eval_determinant(self): # for expressions.determinant.Determinant
+        return _det(self)
+
+    def adjugate(self, method="berkowitz"):
+        return _adjugate(self, method=method)
+
+    def charpoly(self, x='lambda', simplify=_simplify):
+        return _charpoly(self, x=x, simplify=simplify)
+
+    def cofactor(self, i, j, method="berkowitz"):
+        return _cofactor(self, i, j, method=method)
+
+    def cofactor_matrix(self, method="berkowitz"):
+        return _cofactor_matrix(self, method=method)
+
+    def det(self, method="bareiss", iszerofunc=None):
+        return _det(self, method=method, iszerofunc=iszerofunc)
+
+    def per(self):
+        return _per(self)
+
+    def minor(self, i, j, method="berkowitz"):
+        return _minor(self, i, j, method=method)
+
+    def minor_submatrix(self, i, j):
+        return _minor_submatrix(self, i, j)
+
+    _find_reasonable_pivot.__doc__       = _find_reasonable_pivot.__doc__
+    _find_reasonable_pivot_naive.__doc__ = _find_reasonable_pivot_naive.__doc__
+    _eval_det_bareiss.__doc__            = _det_bareiss.__doc__
+    _eval_det_berkowitz.__doc__          = _det_berkowitz.__doc__
+    _eval_det_bird.__doc__            = _det_bird.__doc__
+    _eval_det_laplace.__doc__            = _det_laplace.__doc__
+    _eval_det_lu.__doc__                 = _det_LU.__doc__
+    _eval_determinant.__doc__            = _det.__doc__
+    adjugate.__doc__                     = _adjugate.__doc__
+    charpoly.__doc__                     = _charpoly.__doc__
+    cofactor.__doc__                     = _cofactor.__doc__
+    cofactor_matrix.__doc__              = _cofactor_matrix.__doc__
+    det.__doc__                          = _det.__doc__
+    per.__doc__                          = _per.__doc__
+    minor.__doc__                        = _minor.__doc__
+    minor_submatrix.__doc__              = _minor_submatrix.__doc__
+
+
+class MatrixReductions(MatrixDeterminant):
+    """Provides basic matrix row/column operations. Should not be instantiated
+    directly. See ``reductions.py`` for some of their implementations."""
+
+    def echelon_form(self, iszerofunc=_iszero, simplify=False, with_pivots=False):
+        return _echelon_form(self, iszerofunc=iszerofunc, simplify=simplify,
+                with_pivots=with_pivots)
+
+    @property
+    def is_echelon(self):
+        return _is_echelon(self)
+
+    def rank(self, iszerofunc=_iszero, simplify=False):
+        return _rank(self, iszerofunc=iszerofunc, simplify=simplify)
+
+    def rref_rhs(self, rhs):
+        """Return reduced row-echelon form of matrix, matrix showing
+        rhs after reduction steps. ``rhs`` must have the same number
+        of rows as ``self``.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix, symbols
+        >>> r1, r2 = symbols('r1 r2')
+        >>> Matrix([[1, 1], [2, 1]]).rref_rhs(Matrix([r1, r2]))
+        (Matrix([
+        [1, 0],
+        [0, 1]]), Matrix([
+        [ -r1 + r2],
+        [2*r1 - r2]]))
+        """
+        r, _ = _rref(self.hstack(self, self.eye(self.rows), rhs))
+        return r[:, :self.cols], r[:, -rhs.cols:]
+
+    def rref(self, iszerofunc=_iszero, simplify=False, pivots=True,
+            normalize_last=True):
+        return _rref(self, iszerofunc=iszerofunc, simplify=simplify,
+            pivots=pivots, normalize_last=normalize_last)
+
+    echelon_form.__doc__ = _echelon_form.__doc__
+    is_echelon.__doc__   = _is_echelon.__doc__
+    rank.__doc__         = _rank.__doc__
+    rref.__doc__         = _rref.__doc__
+
+    def _normalize_op_args(self, op, col, k, col1, col2, error_str="col"):
+        """Validate the arguments for a row/column operation.  ``error_str``
+        can be one of "row" or "col" depending on the arguments being parsed."""
+        if op not in ["n->kn", "n<->m", "n->n+km"]:
+            raise ValueError("Unknown {} operation '{}'. Valid col operations "
+                             "are 'n->kn', 'n<->m', 'n->n+km'".format(error_str, op))
+
+        # define self_col according to error_str
+        self_cols = self.cols if error_str == 'col' else self.rows
+
+        # normalize and validate the arguments
+        if op == "n->kn":
+            col = col if col is not None else col1
+            if col is None or k is None:
+                raise ValueError("For a {0} operation 'n->kn' you must provide the "
+                                 "kwargs `{0}` and `k`".format(error_str))
+            if not 0 <= col < self_cols:
+                raise ValueError("This matrix does not have a {} '{}'".format(error_str, col))
+
+        elif op == "n<->m":
+            # we need two cols to swap. It does not matter
+            # how they were specified, so gather them together and
+            # remove `None`
+            cols = {col, k, col1, col2}.difference([None])
+            if len(cols) > 2:
+                # maybe the user left `k` by mistake?
+                cols = {col, col1, col2}.difference([None])
+            if len(cols) != 2:
+                raise ValueError("For a {0} operation 'n<->m' you must provide the "
+                                 "kwargs `{0}1` and `{0}2`".format(error_str))
+            col1, col2 = cols
+            if not 0 <= col1 < self_cols:
+                raise ValueError("This matrix does not have a {} '{}'".format(error_str, col1))
+            if not 0 <= col2 < self_cols:
+                raise ValueError("This matrix does not have a {} '{}'".format(error_str, col2))
+
+        elif op == "n->n+km":
+            col = col1 if col is None else col
+            col2 = col1 if col2 is None else col2
+            if col is None or col2 is None or k is None:
+                raise ValueError("For a {0} operation 'n->n+km' you must provide the "
+                                 "kwargs `{0}`, `k`, and `{0}2`".format(error_str))
+            if col == col2:
+                raise ValueError("For a {0} operation 'n->n+km' `{0}` and `{0}2` must "
+                                 "be different.".format(error_str))
+            if not 0 <= col < self_cols:
+                raise ValueError("This matrix does not have a {} '{}'".format(error_str, col))
+            if not 0 <= col2 < self_cols:
+                raise ValueError("This matrix does not have a {} '{}'".format(error_str, col2))
+
+        else:
+            raise ValueError('invalid operation %s' % repr(op))
+
+        return op, col, k, col1, col2
+
+    def _eval_col_op_multiply_col_by_const(self, col, k):
+        def entry(i, j):
+            if j == col:
+                return k * self[i, j]
+            return self[i, j]
+        return self._new(self.rows, self.cols, entry)
+
+    def _eval_col_op_swap(self, col1, col2):
+        def entry(i, j):
+            if j == col1:
+                return self[i, col2]
+            elif j == col2:
+                return self[i, col1]
+            return self[i, j]
+        return self._new(self.rows, self.cols, entry)
+
+    def _eval_col_op_add_multiple_to_other_col(self, col, k, col2):
+        def entry(i, j):
+            if j == col:
+                return self[i, j] + k * self[i, col2]
+            return self[i, j]
+        return self._new(self.rows, self.cols, entry)
+
+    def _eval_row_op_swap(self, row1, row2):
+        def entry(i, j):
+            if i == row1:
+                return self[row2, j]
+            elif i == row2:
+                return self[row1, j]
+            return self[i, j]
+        return self._new(self.rows, self.cols, entry)
+
+    def _eval_row_op_multiply_row_by_const(self, row, k):
+        def entry(i, j):
+            if i == row:
+                return k * self[i, j]
+            return self[i, j]
+        return self._new(self.rows, self.cols, entry)
+
+    def _eval_row_op_add_multiple_to_other_row(self, row, k, row2):
+        def entry(i, j):
+            if i == row:
+                return self[i, j] + k * self[row2, j]
+            return self[i, j]
+        return self._new(self.rows, self.cols, entry)
+
+    def elementary_col_op(self, op="n->kn", col=None, k=None, col1=None, col2=None):
+        """Performs the elementary column operation `op`.
+
+        `op` may be one of
+
+            * ``"n->kn"`` (column n goes to k*n)
+            * ``"n<->m"`` (swap column n and column m)
+            * ``"n->n+km"`` (column n goes to column n + k*column m)
+
+        Parameters
+        ==========
+
+        op : string; the elementary row operation
+        col : the column to apply the column operation
+        k : the multiple to apply in the column operation
+        col1 : one column of a column swap
+        col2 : second column of a column swap or column "m" in the column operation
+               "n->n+km"
+        """
+
+        op, col, k, col1, col2 = self._normalize_op_args(op, col, k, col1, col2, "col")
+
+        # now that we've validated, we're all good to dispatch
+        if op == "n->kn":
+            return self._eval_col_op_multiply_col_by_const(col, k)
+        if op == "n<->m":
+            return self._eval_col_op_swap(col1, col2)
+        if op == "n->n+km":
+            return self._eval_col_op_add_multiple_to_other_col(col, k, col2)
+
+    def elementary_row_op(self, op="n->kn", row=None, k=None, row1=None, row2=None):
+        """Performs the elementary row operation `op`.
+
+        `op` may be one of
+
+            * ``"n->kn"`` (row n goes to k*n)
+            * ``"n<->m"`` (swap row n and row m)
+            * ``"n->n+km"`` (row n goes to row n + k*row m)
+
+        Parameters
+        ==========
+
+        op : string; the elementary row operation
+        row : the row to apply the row operation
+        k : the multiple to apply in the row operation
+        row1 : one row of a row swap
+        row2 : second row of a row swap or row "m" in the row operation
+               "n->n+km"
+        """
+
+        op, row, k, row1, row2 = self._normalize_op_args(op, row, k, row1, row2, "row")
+
+        # now that we've validated, we're all good to dispatch
+        if op == "n->kn":
+            return self._eval_row_op_multiply_row_by_const(row, k)
+        if op == "n<->m":
+            return self._eval_row_op_swap(row1, row2)
+        if op == "n->n+km":
+            return self._eval_row_op_add_multiple_to_other_row(row, k, row2)
+
+
+class MatrixSubspaces(MatrixReductions):
+    """Provides methods relating to the fundamental subspaces of a matrix.
+    Should not be instantiated directly. See ``subspaces.py`` for their
+    implementations."""
+
+    def columnspace(self, simplify=False):
+        return _columnspace(self, simplify=simplify)
+
+    def nullspace(self, simplify=False, iszerofunc=_iszero):
+        return _nullspace(self, simplify=simplify, iszerofunc=iszerofunc)
+
+    def rowspace(self, simplify=False):
+        return _rowspace(self, simplify=simplify)
+
+    # This is a classmethod but is converted to such later in order to allow
+    # assignment of __doc__ since that does not work for already wrapped
+    # classmethods in Python 3.6.
+    def orthogonalize(cls, *vecs, **kwargs):
+        return _orthogonalize(cls, *vecs, **kwargs)
+
+    columnspace.__doc__   = _columnspace.__doc__
+    nullspace.__doc__     = _nullspace.__doc__
+    rowspace.__doc__      = _rowspace.__doc__
+    orthogonalize.__doc__ = _orthogonalize.__doc__
+
+    orthogonalize         = classmethod(orthogonalize)  # type:ignore
+
+
+class MatrixEigen(MatrixSubspaces):
+    """Provides basic matrix eigenvalue/vector operations.
+    Should not be instantiated directly. See ``eigen.py`` for their
+    implementations."""
+
+    def eigenvals(self, error_when_incomplete=True, **flags):
+        return _eigenvals(self, error_when_incomplete=error_when_incomplete, **flags)
+
+    def eigenvects(self, error_when_incomplete=True, iszerofunc=_iszero, **flags):
+        return _eigenvects(self, error_when_incomplete=error_when_incomplete,
+                iszerofunc=iszerofunc, **flags)
+
+    def is_diagonalizable(self, reals_only=False, **kwargs):
+        return _is_diagonalizable(self, reals_only=reals_only, **kwargs)
+
+    def diagonalize(self, reals_only=False, sort=False, normalize=False):
+        return _diagonalize(self, reals_only=reals_only, sort=sort,
+                normalize=normalize)
+
+    def bidiagonalize(self, upper=True):
+        return _bidiagonalize(self, upper=upper)
+
+    def bidiagonal_decomposition(self, upper=True):
+        return _bidiagonal_decomposition(self, upper=upper)
+
+    @property
+    def is_positive_definite(self):
+        return _is_positive_definite(self)
+
+    @property
+    def is_positive_semidefinite(self):
+        return _is_positive_semidefinite(self)
+
+    @property
+    def is_negative_definite(self):
+        return _is_negative_definite(self)
+
+    @property
+    def is_negative_semidefinite(self):
+        return _is_negative_semidefinite(self)
+
+    @property
+    def is_indefinite(self):
+        return _is_indefinite(self)
+
+    def jordan_form(self, calc_transform=True, **kwargs):
+        return _jordan_form(self, calc_transform=calc_transform, **kwargs)
+
+    def left_eigenvects(self, **flags):
+        return _left_eigenvects(self, **flags)
+
+    def singular_values(self):
+        return _singular_values(self)
+
+    eigenvals.__doc__                  = _eigenvals.__doc__
+    eigenvects.__doc__                 = _eigenvects.__doc__
+    is_diagonalizable.__doc__          = _is_diagonalizable.__doc__
+    diagonalize.__doc__                = _diagonalize.__doc__
+    is_positive_definite.__doc__       = _is_positive_definite.__doc__
+    is_positive_semidefinite.__doc__   = _is_positive_semidefinite.__doc__
+    is_negative_definite.__doc__       = _is_negative_definite.__doc__
+    is_negative_semidefinite.__doc__   = _is_negative_semidefinite.__doc__
+    is_indefinite.__doc__              = _is_indefinite.__doc__
+    jordan_form.__doc__                = _jordan_form.__doc__
+    left_eigenvects.__doc__            = _left_eigenvects.__doc__
+    singular_values.__doc__            = _singular_values.__doc__
+    bidiagonalize.__doc__              = _bidiagonalize.__doc__
+    bidiagonal_decomposition.__doc__   = _bidiagonal_decomposition.__doc__
+
+
+class MatrixCalculus(MatrixCommon):
+    """Provides calculus-related matrix operations."""
+
+    def diff(self, *args, evaluate=True, **kwargs):
+        """Calculate the derivative of each element in the matrix.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> from sympy.abc import x, y
+        >>> M = Matrix([[x, y], [1, 0]])
+        >>> M.diff(x)
+        Matrix([
+        [1, 0],
+        [0, 0]])
+
+        See Also
+        ========
+
+        integrate
+        limit
+        """
+        # XXX this should be handled here rather than in Derivative
+        from sympy.tensor.array.array_derivatives import ArrayDerivative
+        deriv = ArrayDerivative(self, *args, evaluate=evaluate)
+        # XXX This can rather changed to always return immutable matrix
+        if not isinstance(self, Basic) and evaluate:
+            return deriv.as_mutable()
+        return deriv
+
+    def _eval_derivative(self, arg):
+        return self.applyfunc(lambda x: x.diff(arg))
+
+    def integrate(self, *args, **kwargs):
+        """Integrate each element of the matrix.  ``args`` will
+        be passed to the ``integrate`` function.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> from sympy.abc import x, y
+        >>> M = Matrix([[x, y], [1, 0]])
+        >>> M.integrate((x, ))
+        Matrix([
+        [x**2/2, x*y],
+        [     x,   0]])
+        >>> M.integrate((x, 0, 2))
+        Matrix([
+        [2, 2*y],
+        [2,   0]])
+
+        See Also
+        ========
+
+        limit
+        diff
+        """
+        return self.applyfunc(lambda x: x.integrate(*args, **kwargs))
+
+    def jacobian(self, X):
+        """Calculates the Jacobian matrix (derivative of a vector-valued function).
+
+        Parameters
+        ==========
+
+        ``self`` : vector of expressions representing functions f_i(x_1, ..., x_n).
+        X : set of x_i's in order, it can be a list or a Matrix
+
+        Both ``self`` and X can be a row or a column matrix in any order
+        (i.e., jacobian() should always work).
+
+        Examples
+        ========
+
+        >>> from sympy import sin, cos, Matrix
+        >>> from sympy.abc import rho, phi
+        >>> X = Matrix([rho*cos(phi), rho*sin(phi), rho**2])
+        >>> Y = Matrix([rho, phi])
+        >>> X.jacobian(Y)
+        Matrix([
+        [cos(phi), -rho*sin(phi)],
+        [sin(phi),  rho*cos(phi)],
+        [   2*rho,             0]])
+        >>> X = Matrix([rho*cos(phi), rho*sin(phi)])
+        >>> X.jacobian(Y)
+        Matrix([
+        [cos(phi), -rho*sin(phi)],
+        [sin(phi),  rho*cos(phi)]])
+
+        See Also
+        ========
+
+        hessian
+        wronskian
+        """
+        if not isinstance(X, MatrixBase):
+            X = self._new(X)
+        # Both X and ``self`` can be a row or a column matrix, so we need to make
+        # sure all valid combinations work, but everything else fails:
+        if self.shape[0] == 1:
+            m = self.shape[1]
+        elif self.shape[1] == 1:
+            m = self.shape[0]
+        else:
+            raise TypeError("``self`` must be a row or a column matrix")
+        if X.shape[0] == 1:
+            n = X.shape[1]
+        elif X.shape[1] == 1:
+            n = X.shape[0]
+        else:
+            raise TypeError("X must be a row or a column matrix")
+
+        # m is the number of functions and n is the number of variables
+        # computing the Jacobian is now easy:
+        return self._new(m, n, lambda j, i: self[j].diff(X[i]))
+
+    def limit(self, *args):
+        """Calculate the limit of each element in the matrix.
+        ``args`` will be passed to the ``limit`` function.
+
+        Examples
+        ========
+
+        >>> from sympy import Matrix
+        >>> from sympy.abc import x, y
+        >>> M = Matrix([[x, y], [1, 0]])
+        >>> M.limit(x, 2)
+        Matrix([
+        [2, y],
+        [1, 0]])
+
+        See Also
+        ========
+
+        integrate
+        diff
+        """
+        return self.applyfunc(lambda x: x.limit(*args))
+
+
+# https://github.com/sympy/sympy/pull/12854
+class MatrixDeprecated(MatrixCommon):
+    """A class to house deprecated matrix methods."""
+    def berkowitz_charpoly(self, x=Dummy('lambda'), simplify=_simplify):
+        return self.charpoly(x=x)
+
+    def berkowitz_det(self):
+        """Computes determinant using Berkowitz method.
+
+        See Also
+        ========
+
+        det
+        berkowitz
+        """
+        return self.det(method='berkowitz')
+
+    def berkowitz_eigenvals(self, **flags):
+        """Computes eigenvalues of a Matrix using Berkowitz method.
+
+        See Also
+        ========
+
+        berkowitz
+        """
+        return self.eigenvals(**flags)
+
+    def berkowitz_minors(self):
+        """Computes principal minors using Berkowitz method.
+
+        See Also
+        ========
+
+        berkowitz
+        """
+        sign, minors = self.one, []
+
+        for poly in self.berkowitz():
+            minors.append(sign * poly[-1])
+            sign = -sign
+
+        return tuple(minors)
+
+    def berkowitz(self):
+        from sympy.matrices import zeros
+        berk = ((1,),)
+        if not self:
+            return berk
+
+        if not self.is_square:
+            raise NonSquareMatrixError()
+
+        A, N = self, self.rows
+        transforms = [0] * (N - 1)
+
+        for n in range(N, 1, -1):
+            T, k = zeros(n + 1, n), n - 1
+
+            R, C = -A[k, :k], A[:k, k]
+            A, a = A[:k, :k], -A[k, k]
+
+            items = [C]
+
+            for i in range(0, n - 2):
+                items.append(A * items[i])
+
+            for i, B in enumerate(items):
+                items[i] = (R * B)[0, 0]
+
+            items = [self.one, a] + items
+
+            for i in range(n):
+                T[i:, i] = items[:n - i + 1]
+
+            transforms[k - 1] = T
+
+        polys = [self._new([self.one, -A[0, 0]])]
+
+        for i, T in enumerate(transforms):
+            polys.append(T * polys[i])
+
+        return berk + tuple(map(tuple, polys))
+
+    def cofactorMatrix(self, method="berkowitz"):
+        return self.cofactor_matrix(method=method)
+
+    def det_bareis(self):
+        return _det_bareiss(self)
+
+    def det_LU_decomposition(self):
+        """Compute matrix determinant using LU decomposition.
+
+
+        Note that this method fails if the LU decomposition itself
+        fails. In particular, if the matrix has no inverse this method
+        will fail.
+
+        TODO: Implement algorithm for sparse matrices (SFF),
+        https://www.eecis.udel.edu/~saunders/papers/sffge/it5.ps
+
+        See Also
+        ========
+
+
+        det
+        det_bareiss
+        berkowitz_det
+        """
+        return self.det(method='lu')
+
+    def jordan_cell(self, eigenval, n):
+        return self.jordan_block(size=n, eigenvalue=eigenval)
+
+    def jordan_cells(self, calc_transformation=True):
+        P, J = self.jordan_form()
+        return P, J.get_diag_blocks()
+
+    def minorEntry(self, i, j, method="berkowitz"):
+        return self.minor(i, j, method=method)
+
+    def minorMatrix(self, i, j):
+        return self.minor_submatrix(i, j)
+
+    def permuteBkwd(self, perm):
+        """Permute the rows of the matrix with the given permutation in reverse."""
+        return self.permute_rows(perm, direction='backward')
+
+    def permuteFwd(self, perm):
+        """Permute the rows of the matrix with the given permutation."""
+        return self.permute_rows(perm, direction='forward')

lib/python3.12/site-packages/sympy/matrices/solvers.py

@@ -0,0 +1,942 @@
+from sympy.core.function import expand_mul
+from sympy.core.symbol import Dummy, uniquely_named_symbol, symbols
+from sympy.utilities.iterables import numbered_symbols
+
+from .exceptions import ShapeError, NonSquareMatrixError, NonInvertibleMatrixError
+from .eigen import _fuzzy_positive_definite
+from .utilities import _get_intermediate_simp, _iszero
+
+
+def _diagonal_solve(M, rhs):
+    """Solves ``Ax = B`` efficiently, where A is a diagonal Matrix,
+    with non-zero diagonal entries.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix, eye
+    >>> A = eye(2)*2
+    >>> B = Matrix([[1, 2], [3, 4]])
+    >>> A.diagonal_solve(B) == B/2
+    True
+
+    See Also
+    ========
+
+    sympy.matrices.dense.DenseMatrix.lower_triangular_solve
+    sympy.matrices.dense.DenseMatrix.upper_triangular_solve
+    gauss_jordan_solve
+    cholesky_solve
+    LDLsolve
+    LUsolve
+    QRsolve
+    pinv_solve
+    cramer_solve
+    """
+
+    if not M.is_diagonal():
+        raise TypeError("Matrix should be diagonal")
+    if rhs.rows != M.rows:
+        raise TypeError("Size mismatch")
+
+    return M._new(
+        rhs.rows, rhs.cols, lambda i, j: rhs[i, j] / M[i, i])
+
+
+def _lower_triangular_solve(M, rhs):
+    """Solves ``Ax = B``, where A is a lower triangular matrix.
+
+    See Also
+    ========
+
+    upper_triangular_solve
+    gauss_jordan_solve
+    cholesky_solve
+    diagonal_solve
+    LDLsolve
+    LUsolve
+    QRsolve
+    pinv_solve
+    cramer_solve
+    """
+
+    from .dense import MutableDenseMatrix
+
+    if not M.is_square:
+        raise NonSquareMatrixError("Matrix must be square.")
+    if rhs.rows != M.rows:
+        raise ShapeError("Matrices size mismatch.")
+    if not M.is_lower:
+        raise ValueError("Matrix must be lower triangular.")
+
+    dps = _get_intermediate_simp()
+    X   = MutableDenseMatrix.zeros(M.rows, rhs.cols)
+
+    for j in range(rhs.cols):
+        for i in range(M.rows):
+            if M[i, i] == 0:
+                raise TypeError("Matrix must be non-singular.")
+
+            X[i, j] = dps((rhs[i, j] - sum(M[i, k]*X[k, j]
+                                        for k in range(i))) / M[i, i])
+
+    return M._new(X)
+
+def _lower_triangular_solve_sparse(M, rhs):
+    """Solves ``Ax = B``, where A is a lower triangular matrix.
+
+    See Also
+    ========
+
+    upper_triangular_solve
+    gauss_jordan_solve
+    cholesky_solve
+    diagonal_solve
+    LDLsolve
+    LUsolve
+    QRsolve
+    pinv_solve
+    cramer_solve
+    """
+
+    if not M.is_square:
+        raise NonSquareMatrixError("Matrix must be square.")
+    if rhs.rows != M.rows:
+        raise ShapeError("Matrices size mismatch.")
+    if not M.is_lower:
+        raise ValueError("Matrix must be lower triangular.")
+
+    dps  = _get_intermediate_simp()
+    rows = [[] for i in range(M.rows)]
+
+    for i, j, v in M.row_list():
+        if i > j:
+            rows[i].append((j, v))
+
+    X = rhs.as_mutable()
+
+    for j in range(rhs.cols):
+        for i in range(rhs.rows):
+            for u, v in rows[i]:
+                X[i, j] -= v*X[u, j]
+
+            X[i, j] = dps(X[i, j] / M[i, i])
+
+    return M._new(X)
+
+
+def _upper_triangular_solve(M, rhs):
+    """Solves ``Ax = B``, where A is an upper triangular matrix.
+
+    See Also
+    ========
+
+    lower_triangular_solve
+    gauss_jordan_solve
+    cholesky_solve
+    diagonal_solve
+    LDLsolve
+    LUsolve
+    QRsolve
+    pinv_solve
+    cramer_solve
+    """
+
+    from .dense import MutableDenseMatrix
+
+    if not M.is_square:
+        raise NonSquareMatrixError("Matrix must be square.")
+    if rhs.rows != M.rows:
+        raise ShapeError("Matrix size mismatch.")
+    if not M.is_upper:
+        raise TypeError("Matrix is not upper triangular.")
+
+    dps = _get_intermediate_simp()
+    X   = MutableDenseMatrix.zeros(M.rows, rhs.cols)
+
+    for j in range(rhs.cols):
+        for i in reversed(range(M.rows)):
+            if M[i, i] == 0:
+                raise ValueError("Matrix must be non-singular.")
+
+            X[i, j] = dps((rhs[i, j] - sum(M[i, k]*X[k, j]
+                                        for k in range(i + 1, M.rows))) / M[i, i])
+
+    return M._new(X)
+
+def _upper_triangular_solve_sparse(M, rhs):
+    """Solves ``Ax = B``, where A is an upper triangular matrix.
+
+    See Also
+    ========
+
+    lower_triangular_solve
+    gauss_jordan_solve
+    cholesky_solve
+    diagonal_solve
+    LDLsolve
+    LUsolve
+    QRsolve
+    pinv_solve
+    cramer_solve
+    """
+
+    if not M.is_square:
+        raise NonSquareMatrixError("Matrix must be square.")
+    if rhs.rows != M.rows:
+        raise ShapeError("Matrix size mismatch.")
+    if not M.is_upper:
+        raise TypeError("Matrix is not upper triangular.")
+
+    dps  = _get_intermediate_simp()
+    rows = [[] for i in range(M.rows)]
+
+    for i, j, v in M.row_list():
+        if i < j:
+            rows[i].append((j, v))
+
+    X = rhs.as_mutable()
+
+    for j in range(rhs.cols):
+        for i in reversed(range(rhs.rows)):
+            for u, v in reversed(rows[i]):
+                X[i, j] -= v*X[u, j]
+
+            X[i, j] = dps(X[i, j] / M[i, i])
+
+    return M._new(X)
+
+
+def _cholesky_solve(M, rhs):
+    """Solves ``Ax = B`` using Cholesky decomposition,
+    for a general square non-singular matrix.
+    For a non-square matrix with rows > cols,
+    the least squares solution is returned.
+
+    See Also
+    ========
+
+    sympy.matrices.dense.DenseMatrix.lower_triangular_solve
+    sympy.matrices.dense.DenseMatrix.upper_triangular_solve
+    gauss_jordan_solve
+    diagonal_solve
+    LDLsolve
+    LUsolve
+    QRsolve
+    pinv_solve
+    cramer_solve
+    """
+
+    if M.rows < M.cols:
+        raise NotImplementedError(
+            'Under-determined System. Try M.gauss_jordan_solve(rhs)')
+
+    hermitian = True
+    reform    = False
+
+    if M.is_symmetric():
+        hermitian = False
+    elif not M.is_hermitian:
+        reform = True
+
+    if reform or _fuzzy_positive_definite(M) is False:
+        H         = M.H
+        M         = H.multiply(M)
+        rhs       = H.multiply(rhs)
+        hermitian = not M.is_symmetric()
+
+    L = M.cholesky(hermitian=hermitian)
+    Y = L.lower_triangular_solve(rhs)
+
+    if hermitian:
+        return (L.H).upper_triangular_solve(Y)
+    else:
+        return (L.T).upper_triangular_solve(Y)
+
+
+def _LDLsolve(M, rhs):
+    """Solves ``Ax = B`` using LDL decomposition,
+    for a general square and non-singular matrix.
+
+    For a non-square matrix with rows > cols,
+    the least squares solution is returned.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix, eye
+    >>> A = eye(2)*2
+    >>> B = Matrix([[1, 2], [3, 4]])
+    >>> A.LDLsolve(B) == B/2
+    True
+
+    See Also
+    ========
+
+    sympy.matrices.dense.DenseMatrix.LDLdecomposition
+    sympy.matrices.dense.DenseMatrix.lower_triangular_solve
+    sympy.matrices.dense.DenseMatrix.upper_triangular_solve
+    gauss_jordan_solve
+    cholesky_solve
+    diagonal_solve
+    LUsolve
+    QRsolve
+    pinv_solve
+    cramer_solve
+    """
+
+    if M.rows < M.cols:
+        raise NotImplementedError(
+            'Under-determined System. Try M.gauss_jordan_solve(rhs)')
+
+    hermitian = True
+    reform    = False
+
+    if M.is_symmetric():
+        hermitian = False
+    elif not M.is_hermitian:
+        reform = True
+
+    if reform or _fuzzy_positive_definite(M) is False:
+        H         = M.H
+        M         = H.multiply(M)
+        rhs       = H.multiply(rhs)
+        hermitian = not M.is_symmetric()
+
+    L, D = M.LDLdecomposition(hermitian=hermitian)
+    Y    = L.lower_triangular_solve(rhs)
+    Z    = D.diagonal_solve(Y)
+
+    if hermitian:
+        return (L.H).upper_triangular_solve(Z)
+    else:
+        return (L.T).upper_triangular_solve(Z)
+
+
+def _LUsolve(M, rhs, iszerofunc=_iszero):
+    """Solve the linear system ``Ax = rhs`` for ``x`` where ``A = M``.
+
+    This is for symbolic matrices, for real or complex ones use
+    mpmath.lu_solve or mpmath.qr_solve.
+
+    See Also
+    ========
+
+    sympy.matrices.dense.DenseMatrix.lower_triangular_solve
+    sympy.matrices.dense.DenseMatrix.upper_triangular_solve
+    gauss_jordan_solve
+    cholesky_solve
+    diagonal_solve
+    LDLsolve
+    QRsolve
+    pinv_solve
+    LUdecomposition
+    cramer_solve
+    """
+
+    if rhs.rows != M.rows:
+        raise ShapeError(
+            "``M`` and ``rhs`` must have the same number of rows.")
+
+    m = M.rows
+    n = M.cols
+
+    if m < n:
+        raise NotImplementedError("Underdetermined systems not supported.")
+
+    try:
+        A, perm = M.LUdecomposition_Simple(
+            iszerofunc=iszerofunc, rankcheck=True)
+    except ValueError:
+        raise NonInvertibleMatrixError("Matrix det == 0; not invertible.")
+
+    dps = _get_intermediate_simp()
+    b   = rhs.permute_rows(perm).as_mutable()
+
+    # forward substitution, all diag entries are scaled to 1
+    for i in range(m):
+        for j in range(min(i, n)):
+            scale = A[i, j]
+            b.zip_row_op(i, j, lambda x, y: dps(x - y * scale))
+
+    # consistency check for overdetermined systems
+    if m > n:
+        for i in range(n, m):
+            for j in range(b.cols):
+                if not iszerofunc(b[i, j]):
+                    raise ValueError("The system is inconsistent.")
+
+        b = b[0:n, :]   # truncate zero rows if consistent
+
+    # backward substitution
+    for i in range(n - 1, -1, -1):
+        for j in range(i + 1, n):
+            scale = A[i, j]
+            b.zip_row_op(i, j, lambda x, y: dps(x - y * scale))
+
+        scale = A[i, i]
+        b.row_op(i, lambda x, _: dps(x / scale))
+
+    return rhs.__class__(b)
+
+
+def _QRsolve(M, b):
+    """Solve the linear system ``Ax = b``.
+
+    ``M`` is the matrix ``A``, the method argument is the vector
+    ``b``.  The method returns the solution vector ``x``.  If ``b`` is a
+    matrix, the system is solved for each column of ``b`` and the
+    return value is a matrix of the same shape as ``b``.
+
+    This method is slower (approximately by a factor of 2) but
+    more stable for floating-point arithmetic than the LUsolve method.
+    However, LUsolve usually uses an exact arithmetic, so you do not need
+    to use QRsolve.
+
+    This is mainly for educational purposes and symbolic matrices, for real
+    (or complex) matrices use mpmath.qr_solve.
+
+    See Also
+    ========
+
+    sympy.matrices.dense.DenseMatrix.lower_triangular_solve
+    sympy.matrices.dense.DenseMatrix.upper_triangular_solve
+    gauss_jordan_solve
+    cholesky_solve
+    diagonal_solve
+    LDLsolve
+    LUsolve
+    pinv_solve
+    QRdecomposition
+    cramer_solve
+    """
+
+    dps  = _get_intermediate_simp(expand_mul, expand_mul)
+    Q, R = M.QRdecomposition()
+    y    = Q.T * b
+
+    # back substitution to solve R*x = y:
+    # We build up the result "backwards" in the vector 'x' and reverse it
+    # only in the end.
+    x = []
+    n = R.rows
+
+    for j in range(n - 1, -1, -1):
+        tmp = y[j, :]
+
+        for k in range(j + 1, n):
+            tmp -= R[j, k] * x[n - 1 - k]
+
+        tmp = dps(tmp)
+
+        x.append(tmp / R[j, j])
+
+    return M.vstack(*x[::-1])
+
+
+def _gauss_jordan_solve(M, B, freevar=False):
+    """
+    Solves ``Ax = B`` using Gauss Jordan elimination.
+
+    There may be zero, one, or infinite solutions.  If one solution
+    exists, it will be returned. If infinite solutions exist, it will
+    be returned parametrically. If no solutions exist, It will throw
+    ValueError.
+
+    Parameters
+    ==========
+
+    B : Matrix
+        The right hand side of the equation to be solved for.  Must have
+        the same number of rows as matrix A.
+
+    freevar : boolean, optional
+        Flag, when set to `True` will return the indices of the free
+        variables in the solutions (column Matrix), for a system that is
+        undetermined (e.g. A has more columns than rows), for which
+        infinite solutions are possible, in terms of arbitrary
+        values of free variables. Default `False`.
+
+    Returns
+    =======
+
+    x : Matrix
+        The matrix that will satisfy ``Ax = B``.  Will have as many rows as
+        matrix A has columns, and as many columns as matrix B.
+
+    params : Matrix
+        If the system is underdetermined (e.g. A has more columns than
+        rows), infinite solutions are possible, in terms of arbitrary
+        parameters. These arbitrary parameters are returned as params
+        Matrix.
+
+    free_var_index : List, optional
+        If the system is underdetermined (e.g. A has more columns than
+        rows), infinite solutions are possible, in terms of arbitrary
+        values of free variables. Then the indices of the free variables
+        in the solutions (column Matrix) are returned by free_var_index,
+        if the flag `freevar` is set to `True`.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> A = Matrix([[1, 2, 1, 1], [1, 2, 2, -1], [2, 4, 0, 6]])
+    >>> B = Matrix([7, 12, 4])
+    >>> sol, params = A.gauss_jordan_solve(B)
+    >>> sol
+    Matrix([
+    [-2*tau0 - 3*tau1 + 2],
+    [                 tau0],
+    [           2*tau1 + 5],
+    [                 tau1]])
+    >>> params
+    Matrix([
+    [tau0],
+    [tau1]])
+    >>> taus_zeroes = { tau:0 for tau in params }
+    >>> sol_unique = sol.xreplace(taus_zeroes)
+    >>> sol_unique
+        Matrix([
+    [2],
+    [0],
+    [5],
+    [0]])
+
+
+    >>> A = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 10]])
+    >>> B = Matrix([3, 6, 9])
+    >>> sol, params = A.gauss_jordan_solve(B)
+    >>> sol
+    Matrix([
+    [-1],
+    [ 2],
+    [ 0]])
+    >>> params
+    Matrix(0, 1, [])
+
+    >>> A = Matrix([[2, -7], [-1, 4]])
+    >>> B = Matrix([[-21, 3], [12, -2]])
+    >>> sol, params = A.gauss_jordan_solve(B)
+    >>> sol
+    Matrix([
+    [0, -2],
+    [3, -1]])
+    >>> params
+    Matrix(0, 2, [])
+
+
+    >>> from sympy import Matrix
+    >>> A = Matrix([[1, 2, 1, 1], [1, 2, 2, -1], [2, 4, 0, 6]])
+    >>> B = Matrix([7, 12, 4])
+    >>> sol, params, freevars = A.gauss_jordan_solve(B, freevar=True)
+    >>> sol
+    Matrix([
+    [-2*tau0 - 3*tau1 + 2],
+    [                 tau0],
+    [           2*tau1 + 5],
+    [                 tau1]])
+    >>> params
+    Matrix([
+    [tau0],
+    [tau1]])
+    >>> freevars
+    [1, 3]
+
+
+    See Also
+    ========
+
+    sympy.matrices.dense.DenseMatrix.lower_triangular_solve
+    sympy.matrices.dense.DenseMatrix.upper_triangular_solve
+    cholesky_solve
+    diagonal_solve
+    LDLsolve
+    LUsolve
+    QRsolve
+    pinv
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Gaussian_elimination
+
+    """
+
+    from sympy.matrices import Matrix, zeros
+
+    cls      = M.__class__
+    aug      = M.hstack(M.copy(), B.copy())
+    B_cols   = B.cols
+    row, col = aug[:, :-B_cols].shape
+
+    # solve by reduced row echelon form
+    A, pivots = aug.rref(simplify=True)
+    A, v      = A[:, :-B_cols], A[:, -B_cols:]
+    pivots    = list(filter(lambda p: p < col, pivots))
+    rank      = len(pivots)
+
+    # Get index of free symbols (free parameters)
+    # non-pivots columns are free variables
+    free_var_index = [c for c in range(A.cols) if c not in pivots]
+
+    # Bring to block form
+    permutation = Matrix(pivots + free_var_index).T
+
+    # check for existence of solutions
+    # rank of aug Matrix should be equal to rank of coefficient matrix
+    if not v[rank:, :].is_zero_matrix:
+        raise ValueError("Linear system has no solution")
+
+    # Free parameters
+    # what are current unnumbered free symbol names?
+    name = uniquely_named_symbol('tau', [aug],
+            compare=lambda i: str(i).rstrip('1234567890'),
+            modify=lambda s: '_' + s).name
+    gen  = numbered_symbols(name)
+    tau  = Matrix([next(gen) for k in range((col - rank)*B_cols)]).reshape(
+            col - rank, B_cols)
+
+    # Full parametric solution
+    V        = A[:rank, free_var_index]
+    vt       = v[:rank, :]
+    free_sol = tau.vstack(vt - V * tau, tau)
+
+    # Undo permutation
+    sol = zeros(col, B_cols)
+
+    for k in range(col):
+        sol[permutation[k], :] = free_sol[k,:]
+
+    sol, tau = cls(sol), cls(tau)
+
+    if freevar:
+        return sol, tau, free_var_index
+    else:
+        return sol, tau
+
+
+def _pinv_solve(M, B, arbitrary_matrix=None):
+    """Solve ``Ax = B`` using the Moore-Penrose pseudoinverse.
+
+    There may be zero, one, or infinite solutions.  If one solution
+    exists, it will be returned.  If infinite solutions exist, one will
+    be returned based on the value of arbitrary_matrix.  If no solutions
+    exist, the least-squares solution is returned.
+
+    Parameters
+    ==========
+
+    B : Matrix
+        The right hand side of the equation to be solved for.  Must have
+        the same number of rows as matrix A.
+    arbitrary_matrix : Matrix
+        If the system is underdetermined (e.g. A has more columns than
+        rows), infinite solutions are possible, in terms of an arbitrary
+        matrix.  This parameter may be set to a specific matrix to use
+        for that purpose; if so, it must be the same shape as x, with as
+        many rows as matrix A has columns, and as many columns as matrix
+        B.  If left as None, an appropriate matrix containing dummy
+        symbols in the form of ``wn_m`` will be used, with n and m being
+        row and column position of each symbol.
+
+    Returns
+    =======
+
+    x : Matrix
+        The matrix that will satisfy ``Ax = B``.  Will have as many rows as
+        matrix A has columns, and as many columns as matrix B.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> A = Matrix([[1, 2, 3], [4, 5, 6]])
+    >>> B = Matrix([7, 8])
+    >>> A.pinv_solve(B)
+    Matrix([
+    [ _w0_0/6 - _w1_0/3 + _w2_0/6 - 55/18],
+    [-_w0_0/3 + 2*_w1_0/3 - _w2_0/3 + 1/9],
+    [ _w0_0/6 - _w1_0/3 + _w2_0/6 + 59/18]])
+    >>> A.pinv_solve(B, arbitrary_matrix=Matrix([0, 0, 0]))
+    Matrix([
+    [-55/18],
+    [   1/9],
+    [ 59/18]])
+
+    See Also
+    ========
+
+    sympy.matrices.dense.DenseMatrix.lower_triangular_solve
+    sympy.matrices.dense.DenseMatrix.upper_triangular_solve
+    gauss_jordan_solve
+    cholesky_solve
+    diagonal_solve
+    LDLsolve
+    LUsolve
+    QRsolve
+    pinv
+
+    Notes
+    =====
+
+    This may return either exact solutions or least squares solutions.
+    To determine which, check ``A * A.pinv() * B == B``.  It will be
+    True if exact solutions exist, and False if only a least-squares
+    solution exists.  Be aware that the left hand side of that equation
+    may need to be simplified to correctly compare to the right hand
+    side.
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Moore-Penrose_pseudoinverse#Obtaining_all_solutions_of_a_linear_system
+
+    """
+
+    from sympy.matrices import eye
+
+    A      = M
+    A_pinv = M.pinv()
+
+    if arbitrary_matrix is None:
+        rows, cols       = A.cols, B.cols
+        w                = symbols('w:{}_:{}'.format(rows, cols), cls=Dummy)
+        arbitrary_matrix = M.__class__(cols, rows, w).T
+
+    return A_pinv.multiply(B) + (eye(A.cols) -
+            A_pinv.multiply(A)).multiply(arbitrary_matrix)
+
+
+def _cramer_solve(M, rhs, det_method="laplace"):
+    """Solves system of linear equations using Cramer's rule.
+
+    This method is relatively inefficient compared to other methods.
+    However it only uses a single division, assuming a division-free determinant
+    method is provided. This is helpful to minimize the chance of divide-by-zero
+    cases in symbolic solutions to linear systems.
+
+    Parameters
+    ==========
+    M : Matrix
+        The matrix representing the left hand side of the equation.
+    rhs : Matrix
+        The matrix representing the right hand side of the equation.
+    det_method : str or callable
+        The method to use to calculate the determinant of the matrix.
+        The default is ``'laplace'``.  If a callable is passed, it should take a
+        single argument, the matrix, and return the determinant of the matrix.
+
+    Returns
+    =======
+    x : Matrix
+        The matrix that will satisfy ``Ax = B``.  Will have as many rows as
+        matrix A has columns, and as many columns as matrix B.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> A = Matrix([[0, -6, 1], [0, -6, -1], [-5, -2, 3]])
+    >>> B = Matrix([[-30, -9], [-18, -27], [-26, 46]])
+    >>> x = A.cramer_solve(B)
+    >>> x
+    Matrix([
+    [ 0, -5],
+    [ 4,  3],
+    [-6,  9]])
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Cramer%27s_rule#Explicit_formulas_for_small_systems
+
+    """
+    from .dense import zeros
+
+    def entry(i, j):
+        return rhs[i, sol] if j == col else M[i, j]
+
+    if det_method == "bird":
+        from .determinant import _det_bird
+        det = _det_bird
+    elif det_method == "laplace":
+        from .determinant import _det_laplace
+        det = _det_laplace
+    elif isinstance(det_method, str):
+        det = lambda matrix: matrix.det(method=det_method)
+    else:
+        det = det_method
+    det_M = det(M)
+    x = zeros(*rhs.shape)
+    for sol in range(rhs.shape[1]):
+        for col in range(rhs.shape[0]):
+            x[col, sol] = det(M.__class__(*M.shape, entry)) / det_M
+    return M.__class__(x)
+
+
+def _solve(M, rhs, method='GJ'):
+    """Solves linear equation where the unique solution exists.
+
+    Parameters
+    ==========
+
+    rhs : Matrix
+        Vector representing the right hand side of the linear equation.
+
+    method : string, optional
+        If set to ``'GJ'`` or ``'GE'``, the Gauss-Jordan elimination will be
+        used, which is implemented in the routine ``gauss_jordan_solve``.
+
+        If set to ``'LU'``, ``LUsolve`` routine will be used.
+
+        If set to ``'QR'``, ``QRsolve`` routine will be used.
+
+        If set to ``'PINV'``, ``pinv_solve`` routine will be used.
+
+        If set to ``'CRAMER'``, ``cramer_solve`` routine will be used.
+
+        It also supports the methods available for special linear systems
+
+        For positive definite systems:
+
+        If set to ``'CH'``, ``cholesky_solve`` routine will be used.
+
+        If set to ``'LDL'``, ``LDLsolve`` routine will be used.
+
+        To use a different method and to compute the solution via the
+        inverse, use a method defined in the .inv() docstring.
+
+    Returns
+    =======
+
+    solutions : Matrix
+        Vector representing the solution.
+
+    Raises
+    ======
+
+    ValueError
+        If there is not a unique solution then a ``ValueError`` will be
+        raised.
+
+        If ``M`` is not square, a ``ValueError`` and a different routine
+        for solving the system will be suggested.
+    """
+
+    if method in ('GJ', 'GE'):
+        try:
+            soln, param = M.gauss_jordan_solve(rhs)
+
+            if param:
+                raise NonInvertibleMatrixError("Matrix det == 0; not invertible. "
+                "Try ``M.gauss_jordan_solve(rhs)`` to obtain a parametric solution.")
+
+        except ValueError:
+            raise NonInvertibleMatrixError("Matrix det == 0; not invertible.")
+
+        return soln
+
+    elif method == 'LU':
+        return M.LUsolve(rhs)
+    elif method == 'CH':
+        return M.cholesky_solve(rhs)
+    elif method == 'QR':
+        return M.QRsolve(rhs)
+    elif method == 'LDL':
+        return M.LDLsolve(rhs)
+    elif method == 'PINV':
+        return M.pinv_solve(rhs)
+    elif method == 'CRAMER':
+        return M.cramer_solve(rhs)
+    else:
+        return M.inv(method=method).multiply(rhs)
+
+
+def _solve_least_squares(M, rhs, method='CH'):
+    """Return the least-square fit to the data.
+
+    Parameters
+    ==========
+
+    rhs : Matrix
+        Vector representing the right hand side of the linear equation.
+
+    method : string or boolean, optional
+        If set to ``'CH'``, ``cholesky_solve`` routine will be used.
+
+        If set to ``'LDL'``, ``LDLsolve`` routine will be used.
+
+        If set to ``'QR'``, ``QRsolve`` routine will be used.
+
+        If set to ``'PINV'``, ``pinv_solve`` routine will be used.
+
+        Otherwise, the conjugate of ``M`` will be used to create a system
+        of equations that is passed to ``solve`` along with the hint
+        defined by ``method``.
+
+    Returns
+    =======
+
+    solutions : Matrix
+        Vector representing the solution.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix, ones
+    >>> A = Matrix([1, 2, 3])
+    >>> B = Matrix([2, 3, 4])
+    >>> S = Matrix(A.row_join(B))
+    >>> S
+    Matrix([
+    [1, 2],
+    [2, 3],
+    [3, 4]])
+
+    If each line of S represent coefficients of Ax + By
+    and x and y are [2, 3] then S*xy is:
+
+    >>> r = S*Matrix([2, 3]); r
+    Matrix([
+    [ 8],
+    [13],
+    [18]])
+
+    But let's add 1 to the middle value and then solve for the
+    least-squares value of xy:
+
+    >>> xy = S.solve_least_squares(Matrix([8, 14, 18])); xy
+    Matrix([
+    [ 5/3],
+    [10/3]])
+
+    The error is given by S*xy - r:
+
+    >>> S*xy - r
+    Matrix([
+    [1/3],
+    [1/3],
+    [1/3]])
+    >>> _.norm().n(2)
+    0.58
+
+    If a different xy is used, the norm will be higher:
+
+    >>> xy += ones(2, 1)/10
+    >>> (S*xy - r).norm().n(2)
+    1.5
+
+    """
+
+    if method == 'CH':
+        return M.cholesky_solve(rhs)
+    elif method == 'QR':
+        return M.QRsolve(rhs)
+    elif method == 'LDL':
+        return M.LDLsolve(rhs)
+    elif method == 'PINV':
+        return M.pinv_solve(rhs)
+    else:
+        t = M.H
+        return (t * M).solve(t * rhs, method=method)

lib/python3.12/site-packages/sympy/matrices/sparse.py

@@ -0,0 +1,473 @@
+from collections.abc import Callable
+
+from sympy.core.containers import Dict
+from sympy.utilities.exceptions import sympy_deprecation_warning
+from sympy.utilities.iterables import is_sequence
+from sympy.utilities.misc import as_int
+
+from .matrixbase import MatrixBase
+from .repmatrix import MutableRepMatrix, RepMatrix
+
+from .utilities import _iszero
+
+from .decompositions import (
+    _liupc, _row_structure_symbolic_cholesky, _cholesky_sparse,
+    _LDLdecomposition_sparse)
+
+from .solvers import (
+    _lower_triangular_solve_sparse, _upper_triangular_solve_sparse)
+
+
+class SparseRepMatrix(RepMatrix):
+    """
+    A sparse matrix (a matrix with a large number of zero elements).
+
+    Examples
+    ========
+
+    >>> from sympy import SparseMatrix, ones
+    >>> SparseMatrix(2, 2, range(4))
+    Matrix([
+    [0, 1],
+    [2, 3]])
+    >>> SparseMatrix(2, 2, {(1, 1): 2})
+    Matrix([
+    [0, 0],
+    [0, 2]])
+
+    A SparseMatrix can be instantiated from a ragged list of lists:
+
+    >>> SparseMatrix([[1, 2, 3], [1, 2], [1]])
+    Matrix([
+    [1, 2, 3],
+    [1, 2, 0],
+    [1, 0, 0]])
+
+    For safety, one may include the expected size and then an error
+    will be raised if the indices of any element are out of range or
+    (for a flat list) if the total number of elements does not match
+    the expected shape:
+
+    >>> SparseMatrix(2, 2, [1, 2])
+    Traceback (most recent call last):
+    ...
+    ValueError: List length (2) != rows*columns (4)
+
+    Here, an error is not raised because the list is not flat and no
+    element is out of range:
+
+    >>> SparseMatrix(2, 2, [[1, 2]])
+    Matrix([
+    [1, 2],
+    [0, 0]])
+
+    But adding another element to the first (and only) row will cause
+    an error to be raised:
+
+    >>> SparseMatrix(2, 2, [[1, 2, 3]])
+    Traceback (most recent call last):
+    ...
+    ValueError: The location (0, 2) is out of designated range: (1, 1)
+
+    To autosize the matrix, pass None for rows:
+
+    >>> SparseMatrix(None, [[1, 2, 3]])
+    Matrix([[1, 2, 3]])
+    >>> SparseMatrix(None, {(1, 1): 1, (3, 3): 3})
+    Matrix([
+    [0, 0, 0, 0],
+    [0, 1, 0, 0],
+    [0, 0, 0, 0],
+    [0, 0, 0, 3]])
+
+    Values that are themselves a Matrix are automatically expanded:
+
+    >>> SparseMatrix(4, 4, {(1, 1): ones(2)})
+    Matrix([
+    [0, 0, 0, 0],
+    [0, 1, 1, 0],
+    [0, 1, 1, 0],
+    [0, 0, 0, 0]])
+
+    A ValueError is raised if the expanding matrix tries to overwrite
+    a different element already present:
+
+    >>> SparseMatrix(3, 3, {(0, 0): ones(2), (1, 1): 2})
+    Traceback (most recent call last):
+    ...
+    ValueError: collision at (1, 1)
+
+    See Also
+    ========
+    DenseMatrix
+    MutableSparseMatrix
+    ImmutableSparseMatrix
+    """
+
+    @classmethod
+    def _handle_creation_inputs(cls, *args, **kwargs):
+        if len(args) == 1 and isinstance(args[0], MatrixBase):
+            rows = args[0].rows
+            cols = args[0].cols
+            smat = args[0].todok()
+            return rows, cols, smat
+
+        smat = {}
+        # autosizing
+        if len(args) == 2 and args[0] is None:
+            args = [None, None, args[1]]
+
+        if len(args) == 3:
+            r, c = args[:2]
+            if r is c is None:
+                rows = cols = None
+            elif None in (r, c):
+                raise ValueError(
+                    'Pass rows=None and no cols for autosizing.')
+            else:
+                rows, cols = as_int(args[0]), as_int(args[1])
+
+            if isinstance(args[2], Callable):
+                op = args[2]
+
+                if None in (rows, cols):
+                    raise ValueError(
+                        "{} and {} must be integers for this "
+                        "specification.".format(rows, cols))
+
+                row_indices = [cls._sympify(i) for i in range(rows)]
+                col_indices = [cls._sympify(j) for j in range(cols)]
+
+                for i in row_indices:
+                    for j in col_indices:
+                        value = cls._sympify(op(i, j))
+                        if value != cls.zero:
+                            smat[i, j] = value
+
+                return rows, cols, smat
+
+            elif isinstance(args[2], (dict, Dict)):
+                def update(i, j, v):
+                    # update smat and make sure there are no collisions
+                    if v:
+                        if (i, j) in smat and v != smat[i, j]:
+                            raise ValueError(
+                                "There is a collision at {} for {} and {}."
+                                .format((i, j), v, smat[i, j])
+                            )
+                        smat[i, j] = v
+
+                # manual copy, copy.deepcopy() doesn't work
+                for (r, c), v in args[2].items():
+                    if isinstance(v, MatrixBase):
+                        for (i, j), vv in v.todok().items():
+                            update(r + i, c + j, vv)
+                    elif isinstance(v, (list, tuple)):
+                        _, _, smat = cls._handle_creation_inputs(v, **kwargs)
+                        for i, j in smat:
+                            update(r + i, c + j, smat[i, j])
+                    else:
+                        v = cls._sympify(v)
+                        update(r, c, cls._sympify(v))
+
+            elif is_sequence(args[2]):
+                flat = not any(is_sequence(i) for i in args[2])
+                if not flat:
+                    _, _, smat = \
+                        cls._handle_creation_inputs(args[2], **kwargs)
+                else:
+                    flat_list = args[2]
+                    if len(flat_list) != rows * cols:
+                        raise ValueError(
+                            "The length of the flat list ({}) does not "
+                            "match the specified size ({} * {})."
+                            .format(len(flat_list), rows, cols)
+                        )
+
+                    for i in range(rows):
+                        for j in range(cols):
+                            value = flat_list[i*cols + j]
+                            value = cls._sympify(value)
+                            if value != cls.zero:
+                                smat[i, j] = value
+
+            if rows is None:  # autosizing
+                keys = smat.keys()
+                rows = max(r for r, _ in keys) + 1 if keys else 0
+                cols = max(c for _, c in keys) + 1 if keys else 0
+
+            else:
+                for i, j in smat.keys():
+                    if i and i >= rows or j and j >= cols:
+                        raise ValueError(
+                            "The location {} is out of the designated range"
+                            "[{}, {}]x[{}, {}]"
+                            .format((i, j), 0, rows - 1, 0, cols - 1)
+                        )
+
+            return rows, cols, smat
+
+        elif len(args) == 1 and isinstance(args[0], (list, tuple)):
+            # list of values or lists
+            v = args[0]
+            c = 0
+            for i, row in enumerate(v):
+                if not isinstance(row, (list, tuple)):
+                    row = [row]
+                for j, vv in enumerate(row):
+                    if vv != cls.zero:
+                        smat[i, j] = cls._sympify(vv)
+                c = max(c, len(row))
+            rows = len(v) if c else 0
+            cols = c
+            return rows, cols, smat
+
+        else:
+            # handle full matrix forms with _handle_creation_inputs
+            rows, cols, mat = super()._handle_creation_inputs(*args)
+            for i in range(rows):
+                for j in range(cols):
+                    value = mat[cols*i + j]
+                    if value != cls.zero:
+                        smat[i, j] = value
+
+            return rows, cols, smat
+
+    @property
+    def _smat(self):
+
+        sympy_deprecation_warning(
+            """
+            The private _smat attribute of SparseMatrix is deprecated. Use the
+            .todok() method instead.
+            """,
+            deprecated_since_version="1.9",
+            active_deprecations_target="deprecated-private-matrix-attributes"
+        )
+
+        return self.todok()
+
+    def _eval_inverse(self, **kwargs):
+        return self.inv(method=kwargs.get('method', 'LDL'),
+                        iszerofunc=kwargs.get('iszerofunc', _iszero),
+                        try_block_diag=kwargs.get('try_block_diag', False))
+
+    def applyfunc(self, f):
+        """Apply a function to each element of the matrix.
+
+        Examples
+        ========
+
+        >>> from sympy import SparseMatrix
+        >>> m = SparseMatrix(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.")
+
+        # XXX: This only applies the function to the nonzero elements of the
+        # matrix so is inconsistent with DenseMatrix.applyfunc e.g.
+        #   zeros(2, 2).applyfunc(lambda x: x + 1)
+        dok = {}
+        for k, v in self.todok().items():
+            fv = f(v)
+            if fv != 0:
+                dok[k] = fv
+
+        return self._new(self.rows, self.cols, dok)
+
+    def as_immutable(self):
+        """Returns an Immutable version of this Matrix."""
+        from .immutable import ImmutableSparseMatrix
+        return ImmutableSparseMatrix(self)
+
+    def as_mutable(self):
+        """Returns a mutable version of this matrix.
+
+        Examples
+        ========
+
+        >>> from sympy import ImmutableMatrix
+        >>> X = ImmutableMatrix([[1, 2], [3, 4]])
+        >>> Y = X.as_mutable()
+        >>> Y[1, 1] = 5 # Can set values in Y
+        >>> Y
+        Matrix([
+        [1, 2],
+        [3, 5]])
+        """
+        return MutableSparseMatrix(self)
+
+    def col_list(self):
+        """Returns a column-sorted list of non-zero elements of the matrix.
+
+        Examples
+        ========
+
+        >>> from sympy import SparseMatrix
+        >>> a=SparseMatrix(((1, 2), (3, 4)))
+        >>> a
+        Matrix([
+        [1, 2],
+        [3, 4]])
+        >>> a.CL
+        [(0, 0, 1), (1, 0, 3), (0, 1, 2), (1, 1, 4)]
+
+        See Also
+        ========
+
+        sympy.matrices.sparse.SparseMatrix.row_list
+        """
+        return [tuple(k + (self[k],)) for k in sorted(self.todok().keys(), key=lambda k: list(reversed(k)))]
+
+    def nnz(self):
+        """Returns the number of non-zero elements in Matrix."""
+        return len(self.todok())
+
+    def row_list(self):
+        """Returns a row-sorted list of non-zero elements of the matrix.
+
+        Examples
+        ========
+
+        >>> from sympy import SparseMatrix
+        >>> a = SparseMatrix(((1, 2), (3, 4)))
+        >>> a
+        Matrix([
+        [1, 2],
+        [3, 4]])
+        >>> a.RL
+        [(0, 0, 1), (0, 1, 2), (1, 0, 3), (1, 1, 4)]
+
+        See Also
+        ========
+
+        sympy.matrices.sparse.SparseMatrix.col_list
+        """
+        return [tuple(k + (self[k],)) for k in
+            sorted(self.todok().keys(), key=list)]
+
+    def scalar_multiply(self, scalar):
+        "Scalar element-wise multiplication"
+        return scalar * self
+
+    def solve_least_squares(self, rhs, method='LDL'):
+        """Return the least-square fit to the data.
+
+        By default the cholesky_solve routine is used (method='CH'); other
+        methods of matrix inversion can be used. To find out which are
+        available, see the docstring of the .inv() method.
+
+        Examples
+        ========
+
+        >>> from sympy import SparseMatrix, Matrix, ones
+        >>> A = Matrix([1, 2, 3])
+        >>> B = Matrix([2, 3, 4])
+        >>> S = SparseMatrix(A.row_join(B))
+        >>> S
+        Matrix([
+        [1, 2],
+        [2, 3],
+        [3, 4]])
+
+        If each line of S represent coefficients of Ax + By
+        and x and y are [2, 3] then S*xy is:
+
+        >>> r = S*Matrix([2, 3]); r
+        Matrix([
+        [ 8],
+        [13],
+        [18]])
+
+        But let's add 1 to the middle value and then solve for the
+        least-squares value of xy:
+
+        >>> xy = S.solve_least_squares(Matrix([8, 14, 18])); xy
+        Matrix([
+        [ 5/3],
+        [10/3]])
+
+        The error is given by S*xy - r:
+
+        >>> S*xy - r
+        Matrix([
+        [1/3],
+        [1/3],
+        [1/3]])
+        >>> _.norm().n(2)
+        0.58
+
+        If a different xy is used, the norm will be higher:
+
+        >>> xy += ones(2, 1)/10
+        >>> (S*xy - r).norm().n(2)
+        1.5
+
+        """
+        t = self.T
+        return (t*self).inv(method=method)*t*rhs
+
+    def solve(self, rhs, method='LDL'):
+        """Return solution to self*soln = rhs using given inversion method.
+
+        For a list of possible inversion methods, see the .inv() docstring.
+        """
+        if not self.is_square:
+            if self.rows < self.cols:
+                raise ValueError('Under-determined system.')
+            elif self.rows > self.cols:
+                raise ValueError('For over-determined system, M, having '
+                    'more rows than columns, try M.solve_least_squares(rhs).')
+        else:
+            return self.inv(method=method).multiply(rhs)
+
+    RL = property(row_list, None, None, "Alternate faster representation")
+    CL = property(col_list, None, None, "Alternate faster representation")
+
+    def liupc(self):
+        return _liupc(self)
+
+    def row_structure_symbolic_cholesky(self):
+        return _row_structure_symbolic_cholesky(self)
+
+    def cholesky(self, hermitian=True):
+        return _cholesky_sparse(self, hermitian=hermitian)
+
+    def LDLdecomposition(self, hermitian=True):
+        return _LDLdecomposition_sparse(self, hermitian=hermitian)
+
+    def lower_triangular_solve(self, rhs):
+        return _lower_triangular_solve_sparse(self, rhs)
+
+    def upper_triangular_solve(self, rhs):
+        return _upper_triangular_solve_sparse(self, rhs)
+
+    liupc.__doc__                           = _liupc.__doc__
+    row_structure_symbolic_cholesky.__doc__ = _row_structure_symbolic_cholesky.__doc__
+    cholesky.__doc__                        = _cholesky_sparse.__doc__
+    LDLdecomposition.__doc__                = _LDLdecomposition_sparse.__doc__
+    lower_triangular_solve.__doc__          = lower_triangular_solve.__doc__
+    upper_triangular_solve.__doc__          = upper_triangular_solve.__doc__
+
+
+class MutableSparseMatrix(SparseRepMatrix, MutableRepMatrix):
+
+    @classmethod
+    def _new(cls, *args, **kwargs):
+        rows, cols, smat = cls._handle_creation_inputs(*args, **kwargs)
+
+        rep = cls._smat_to_DomainMatrix(rows, cols, smat)
+
+        return cls._fromrep(rep)
+
+
+SparseMatrix = MutableSparseMatrix

lib/python3.12/site-packages/sympy/matrices/subspaces.py

@@ -0,0 +1,174 @@
+from .utilities import _iszero
+
+
+def _columnspace(M, simplify=False):
+    """Returns a list of vectors (Matrix objects) that span columnspace of ``M``
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> M = Matrix(3, 3, [1, 3, 0, -2, -6, 0, 3, 9, 6])
+    >>> M
+    Matrix([
+    [ 1,  3, 0],
+    [-2, -6, 0],
+    [ 3,  9, 6]])
+    >>> M.columnspace()
+    [Matrix([
+    [ 1],
+    [-2],
+    [ 3]]), Matrix([
+    [0],
+    [0],
+    [6]])]
+
+    See Also
+    ========
+
+    nullspace
+    rowspace
+    """
+
+    reduced, pivots = M.echelon_form(simplify=simplify, with_pivots=True)
+
+    return [M.col(i) for i in pivots]
+
+
+def _nullspace(M, simplify=False, iszerofunc=_iszero):
+    """Returns list of vectors (Matrix objects) that span nullspace of ``M``
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> M = Matrix(3, 3, [1, 3, 0, -2, -6, 0, 3, 9, 6])
+    >>> M
+    Matrix([
+    [ 1,  3, 0],
+    [-2, -6, 0],
+    [ 3,  9, 6]])
+    >>> M.nullspace()
+    [Matrix([
+    [-3],
+    [ 1],
+    [ 0]])]
+
+    See Also
+    ========
+
+    columnspace
+    rowspace
+    """
+
+    reduced, pivots = M.rref(iszerofunc=iszerofunc, simplify=simplify)
+
+    free_vars = [i for i in range(M.cols) if i not in pivots]
+    basis     = []
+
+    for free_var in free_vars:
+        # for each free variable, we will set it to 1 and all others
+        # to 0.  Then, we will use back substitution to solve the system
+        vec           = [M.zero] * M.cols
+        vec[free_var] = M.one
+
+        for piv_row, piv_col in enumerate(pivots):
+            vec[piv_col] -= reduced[piv_row, free_var]
+
+        basis.append(vec)
+
+    return [M._new(M.cols, 1, b) for b in basis]
+
+
+def _rowspace(M, simplify=False):
+    """Returns a list of vectors that span the row space of ``M``.
+
+    Examples
+    ========
+
+    >>> from sympy import Matrix
+    >>> M = Matrix(3, 3, [1, 3, 0, -2, -6, 0, 3, 9, 6])
+    >>> M
+    Matrix([
+    [ 1,  3, 0],
+    [-2, -6, 0],
+    [ 3,  9, 6]])
+    >>> M.rowspace()
+    [Matrix([[1, 3, 0]]), Matrix([[0, 0, 6]])]
+    """
+
+    reduced, pivots = M.echelon_form(simplify=simplify, with_pivots=True)
+
+    return [reduced.row(i) for i in range(len(pivots))]
+
+
+def _orthogonalize(cls, *vecs, normalize=False, rankcheck=False):
+    """Apply the Gram-Schmidt orthogonalization procedure
+    to vectors supplied in ``vecs``.
+
+    Parameters
+    ==========
+
+    vecs
+        vectors to be made orthogonal
+
+    normalize : bool
+        If ``True``, return an orthonormal basis.
+
+    rankcheck : bool
+        If ``True``, the computation does not stop when encountering
+        linearly dependent vectors.
+
+        If ``False``, it will raise ``ValueError`` when any zero
+        or linearly dependent vectors are found.
+
+    Returns
+    =======
+
+    list
+        List of orthogonal (or orthonormal) basis vectors.
+
+    Examples
+    ========
+
+    >>> from sympy import I, Matrix
+    >>> v = [Matrix([1, I]), Matrix([1, -I])]
+    >>> Matrix.orthogonalize(*v)
+    [Matrix([
+    [1],
+    [I]]), Matrix([
+    [ 1],
+    [-I]])]
+
+    See Also
+    ========
+
+    MatrixBase.QRdecomposition
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Gram%E2%80%93Schmidt_process
+    """
+    from .decompositions import _QRdecomposition_optional
+
+    if not vecs:
+        return []
+
+    all_row_vecs = (vecs[0].rows == 1)
+
+    vecs = [x.vec() for x in vecs]
+    M = cls.hstack(*vecs)
+    Q, R = _QRdecomposition_optional(M, normalize=normalize)
+
+    if rankcheck and Q.cols < len(vecs):
+        raise ValueError("GramSchmidt: vector set not linearly independent")
+
+    ret = []
+    for i in range(Q.cols):
+        if all_row_vecs:
+            col = cls(Q[:, i].T)
+        else:
+            col = cls(Q[:, i])
+        ret.append(col)
+    return ret

lib/python3.12/site-packages/sympy/polys/agca/__init__.py

@@ -0,0 +1,5 @@
+"""Module for algebraic geometry and commutative algebra."""
+
+from .homomorphisms import homomorphism
+
+__all__ = ['homomorphism']