
    \ht             	      ^   S r SSKJr  SSKJr  SSKJr  SSKJr  SSK	J
r
  SSKJr  SSKJrJr  SS	KJr  SS
KJr  SSKJrJr  SSKJr  SSKJr  SSKJr  SSKJr  SSKJ r   SSK!J"r"J#r#J$r$  SSK%J&r&  SSK'J(r(J)r)  SSK*J+r+  SSK,J-r-J.r.  SSK/J0r0J1r1  SSK2J3r3  SSK'J4r4  SSK5J6r6J7r7J8r8J9r9J:r:  Sr; " S S\<5      r= " S S\=S 9r> " S! S"\>5      r? " S# S$\>5      r@ " S% S&\>5      rA " S' S(\>5      rB " S) S*\>5      rC " S+ S,\C\B\A\@\?5      rD " S- S.5      rE " S/ S05      rF " S1 S25      rGS3 rHS7S5 jrIS6 rJg4)8au  
A module containing deprecated matrix mixin classes.

The classes in this module are deprecated and will be removed in a future
release. They are kept here for backwards compatibility in case downstream
code was subclassing them.

Importing anything else from this module is deprecated so anything here
should either not be used or should be imported from somewhere else.
    )annotations)defaultdict)Iterable)
isfunction)reducerefine)SympifyErrorAdd)Atom)call_highest_priority)	fuzzy_and	FuzzyBool)IntegerMod)S)Symbol)sympify)Absreim)sympy_deprecation_warning   )_dotprodsimp	_simplify)Poly)flattenis_sequence)as_int
filldedent)	NDimArray)_get_intermediate_simp_bool)MatrixError
ShapeErrorNonSquareMatrixErrorNonInvertibleMatrixErrorNonPositiveDefiniteMatrixError)MatrixShapingMatrixSpecialMatrixPropertiesMatrixOperationsMatrixArithmeticMatrixCommonMatrixDeterminantMatrixReductionsMatrixSubspacesMatrixEigenMatrixCalculusMatrixDeprecatedc                  (   ^  \ rS rSrU 4S jrSrU =r$ )_MatrixDeprecatedMeta?   c                  > [        SU R                   SU R                   S3SSSS9  SS	KJn  SS
KJnJnJnJnJ	nJ
n  [        [        [        [        [        [         ["        UUUUUU4n	X	;   a  [%        X5      (       a  g[&        T
U ]Q  U5      $ )Nz:
            Checking whether an object is an instance of zc is
            deprecated.

            Use `isinstance(obj, Matrix)` instead of `isinstance(obj, z)`.
            1.13deprecated-matrix-mixins   deprecated_since_versionactive_deprecations_target
stacklevelr   
MatrixBase)r/   r0   r1   r2   r3   r4   T)r   __name__sympy.matrices.matrixbaserA   sympy.matrices.matricesr/   r0   r1   r2   r3   r4   MatrixRequiredr)   r*   r+   r,   r-   r.   
isinstancesuper__instancecheck__)clsinstancerA   r/   r0   r1   r2   r3   r4   
all_mixins	__class__s             M/var/www/auris/envauris/lib/python3.13/site-packages/sympy/matrices/common.pyrH   '_MatrixDeprecatedMeta.__instancecheck__Q   s    !::=,, HG HK||n U	 &,'A
	
 	9	
 	
 

  H!A!A7,X66     )rB   
__module____qualname____firstlineno__rH   __static_attributes____classcell__rL   s   @rM   r6   r6   ?   s    $+7 +7rO   r6   c                  x   ^  \ rS rSr% SrS\S'   S\S'   SrU 4S jr\S 5       r	S	 r
S
 rS r\S 5       rSrU =r$ )rE      z1Deprecated mixin class for making matrix classes.introwscolsNc                   > U R                   [        ;  a  [        SU R                    S3SSSS9  [        TU ]  " S0 UD6  g )Nzd
                Inheriting from the Matrix mixin classes is deprecated.

                The class z4 is subclassing a deprecated mixin.
                r9   r:   r;   r<   rP   )rB   _DEPRECATED_MIXINSr   rG   __init_subclass__)rI   kwargsrL   s     rM   r^    MatrixRequired.__init_subclass__   sQ     <<11% <<. )
 *0+E	 	!+F+rO   c                    [        S5      e)zv`_new` must, at minimum, be callable as
`_new(rows, cols, mat) where mat is a flat list of the
elements of the matrix.Subclasses must implement this.NotImplementedErrorrI   argsr_   s      rM   _newMatrixRequired._new       
 ""CDDrO   c                    [        S5      eNrb   rc   selfothers     rM   __eq__MatrixRequired.__eq__   s    !"CDDrO   c                    [        S5      e)zImplementations of __getitem__ should accept ints, in which
case the matrix is indexed as a flat list, tuples (i,j) in which
case the (i,j) entry is returned, slices, or mixed tuples (a,b)
where a and b are any combination of slices and integers.rb   rc   rm   keys     rM   __getitem__MatrixRequired.__getitem__   ri   rO   c                    [        S5      e)z*The total number of entries in the matrix.rb   rc   rm   s    rM   __len__MatrixRequired.__len__       !"CDDrO   c                    [        S5      erk   rc   rw   s    rM   shapeMatrixRequired.shape   rz   rO   rP   )rB   rQ   rR   rS   __doc____annotations__r   r^   classmethodrg   ro   rt   rx   propertyr|   rT   rU   rV   s   @rM   rE   rE      sX    ;
I
II,6 E EEEE E ErO   rE   )	metaclassc                      \ rS rSrSrS rS rS rS rS r	S r
S	 rS
 rS rS rS rS rS rS rS rS rS rS r\S 5       rS rS rS rS rS%S jrS r\S 5       r S r!S r"S r#S  r$S&S! jr%\S" 5       r&S#r'g$)'r)      z;Provides basic matrix shaping and extracting of submatricesc                h   ^ ^ UU 4S jnT R                  T R                  T R                  S-
  U5      $ )Nc                .   > UT:  a  TX4   $ TXS-   4   $ Nr   rP   )ijcolrm   s     rM   entry*MatrixShaping._eval_col_del.<locals>.entry   s$    !"S4:<d1!e8n<rO   r   rg   rZ   r[   )rm   r   r   s   `` rM   _eval_col_delMatrixShaping._eval_col_del   s'    	=yyDIIM599rO   c                   ^ ^^ UUU 4S jnT R                  T R                  T R                  TR                  -   U5      $ )Nc                   > UT:  a  TX4   $ TUs=::  a  TTR                   -   :  a  O  O	TXT-
  4   $ TXTR                   -
  4   $ Nr[   )r   r   rn   posrm   s     rM   r   -MatrixShaping._eval_col_insert.<locals>.entry   sS    3wADz!,C%**,,QCZ((uzz>)**rO   r   )rm   r   rn   r   s   ``` rM   _eval_col_insertMatrixShaping._eval_col_insert   s.    	+ yyDII

$:EBBrO   c                   ^ ^^ T R                   mUUU 4S jn[        T T5      R                  T R                   TR                   -   T R                  U5      $ )Nc                0   > U T:  a  TX4   $ TU T-
  U4   $ r   rP   )r   r   rn   rZ   rm   s     rM   r   +MatrixShaping._eval_col_join.<locals>.entry   s)    4xADz!T1%%rO   )rZ   classofrg   r[   )rm   rn   r   rZ   s   `` @rM   _eval_col_joinMatrixShaping._eval_col_join   sE    yy	&
 tU#((UZZ)?).0 	0rO   c           	        ^^ [        U 5      nU R                  mUU4S jU 5       nU R                  [        U5      [        T5      U Vs/ s H  oSU   PM	     sn5      $ s  snf )Nc              3  F   >#    U  H  nT  H  o!T-  U-   v   M     M     g 7fr   rP   ).0r   r   r[   colsLists      rM   	<genexpr>.MatrixShaping._eval_extract.<locals>.<genexpr>   s     DA8at8a<8<   !)listr[   rg   len)rm   rowsListr   matindicesr   r[   s     `   @rM   _eval_extractMatrixShaping._eval_extract   sS    4jyyDDyyXH*12'Qa&'24 	42s   
Ac                ,   ^^ / mUU4S jmT" U 5        T$ )Nc                  > [        SU R                  S   S-   5       H  nUS:X  a  U SUS 24   nXS 2S4   nOU S U2US 24   nXS 2S U24   n[        U5      (       d  [        U5      (       a  MR  TR                  U S U2S U24   5        U R                  U S U2S U24   R                  :w  a  T" XS 2US 24   5          g    g Nr   r   )ranger|   anyappend)Mr   to_the_rightto_the_bottomrecurse_sub_blocks
sub_blockss       rM   r   ?MatrixShaping._eval_get_diag_blocks.<locals>.recurse_sub_blocks   s    1aggaj1n-6#$QU8L$%b!eHM#$RaRV9L$%b"1"fIM|$$M(:(:!!!BQBF),77aBQBioo-&qQRy1 .rO   rP   )rm   r   r   s    @@rM   _eval_get_diag_blocks#MatrixShaping._eval_get_diag_blocks   s    
	 	4 rO   c                h   ^ ^ UU 4S jnT R                  T R                  S-
  T R                  U5      $ )Nc                0   > U T:  a  TX4   $ TU S-   U4   $ r   rP   )r   r   rowrm   s     rM   r   *MatrixShaping._eval_row_del.<locals>.entry   s&    !"S4:<d1q5!8n<rO   r   r   )rm   r   r   s   `` rM   _eval_row_delMatrixShaping._eval_row_del   s'    	=yyQ		599rO   c                    [        U 5      nXR                  -  n[        U5      X4U& U R                  U R                  UR                  -   U R                  U5      $ r   )r   r[   rg   rZ   )rm   r   rn   entries
insert_poss        rM   _eval_row_insertMatrixShaping._eval_row_insert   sH    t*99_
)-e:&yyUZZ/GDDrO   c                   ^ ^^ T R                   mUUU 4S jn[        T T5      R                  T R                  T R                   TR                   -   U5      $ )Nc                .   > UT:  a  TX4   $ TXT-
  4   $ r   rP   )r   r   r[   rn   rm   s     rM   r   +MatrixShaping._eval_row_join.<locals>.entry  s'    4xADz!H%%rO   )r[   r   rg   rZ   )rm   rn   r   r[   s   `` @rM   _eval_row_joinMatrixShaping._eval_row_join   sE    yy	&
 tU#((DII

4J).0 	0rO   c           	     v    [        U R                  5       Vs/ s H  n[        XS S 24   5      PM     sn$ s  snf r   )r   rZ   r   rm   r   s     rM   _eval_tolistMatrixShaping._eval_tolist  s/    ).tyy)9:)9ATA#Y)9:::s   6c                    0 nU R                   u  p#[        U5       H1  n[        U5       H  nXU4   nX`R                  :w  d  M  XaXE4'   M!     M3     U$ r   )r|   r   zero)rm   dokrZ   r[   r   r   vals          rM   _eval_todokMatrixShaping._eval_todok  sS    ZZ
tA4[a4j))# #I ! 
 
rO   c                d   ^ ^ T R                   mUU 4S jnT R                  [        T 5      SU5      $ )Nc                (   > U T-  nXT-  -
  nTX24   $ r   rP   )n_r   r   rZ   rm   s       rM   r   &MatrixShaping._eval_vec.<locals>.entry  s#    T	AHA:rO   r   )rZ   rg   r   )rm   r   rZ   s   ` @rM   	_eval_vecMatrixShaping._eval_vec  s*    yy	 yyTAu--rO   c                R   U R                   n/ nU(       a:  [        U5       H*  n[        XB5       H  nUR                  XU4   5        M     M,     O=[        U5       H.  n[        US-   U5       H  nUR                  XU4   5        M     M0     U R                  [	        U5      SU5      $ r   )r[   r   r   rg   r   )rm   diagonalcvr   r   s         rM   
_eval_vechMatrixShaping._eval_vech#  s    II1XqAHHTQ$Z( %  1Xq1uaAHHTQ$Z( )  yyQA&&rO   c                    US:  a  XR                   -  nSUs=::  a  U R                   :  d  O  [        SR                  U5      5      eU R                  U5      $ )zDelete the specified column.r   zColumn {} is out of range.)r[   
IndexErrorformatr   )rm   r   s     rM   col_delMatrixShaping.col_del0  sN    799CC#$))#9@@EFF!!#&&rO   c                n   U (       d  [        U 5      " U5      $ [        U5      nUS:  a  U R                  U-   nUS:  a  SnOXR                  :  a  U R                  nU R                  UR                  :w  a/  [	        SR                  U R                  UR                  5      5      eU R                  X5      $ )a  Insert one or more columns at the given column position.

Examples
========

>>> from sympy import zeros, ones
>>> M = zeros(3)
>>> V = ones(3, 1)
>>> M.col_insert(1, V)
Matrix([
[0, 1, 0, 0],
[0, 1, 0, 0],
[0, 1, 0, 0]])

See Also
========

col
row_insert
r   9The matrices have incompatible number of rows ({} and {}))typer    r[   rZ   r%   r   r   rm   r   rn   s      rM   
col_insertMatrixShaping.col_insert8  s    , :e$$Sk7))c/C7C99_))C99

"K		5::.0 0 $$S00rO   c                b   U R                   S:X  aF  U R                  UR                  :w  a,  U R                  SUR                  / 5      R                  U5      $ U R                  UR                  :w  a/  [	        SR                  U R                  UR                  5      5      eU R                  U5      $ )a  Concatenates two matrices along self's last and other's first row.

Examples
========

>>> from sympy import zeros, ones
>>> M = zeros(3)
>>> V = ones(1, 3)
>>> M.col_join(V)
Matrix([
[0, 0, 0],
[0, 0, 0],
[0, 0, 0],
[1, 1, 1]])

See Also
========

col
row_join
r   <The matrices have incompatible number of columns ({} and {}))rZ   r[   rg   col_joinr%   r   r   rl   s     rM   r   MatrixShaping.col_joina  s    . 99>dii5::599Q

B/88??99

"N		5::.0 0 ""5))rO   c                    U SS2U4   $ )zElementary column selector.

Examples
========

>>> from sympy import eye
>>> eye(2).col(0)
Matrix([
[1],
[0]])

See Also
========

row
col_del
col_join
col_insert
NrP   )rm   r   s     rM   r   MatrixShaping.col  s    ( AqDzrO   c                R   [        U5      (       a  [        U5      (       d  [        S5      eU(       a?  [        S U 5       5      (       a(  [        U5       VVs/ s H  u  p4U(       d  M  UPM     nnnU(       a?  [        S U 5       5      (       a(  [        U5       VVs/ s H  u  p4U(       d  M  UPM     nnnU Vs/ s H  n[	        XPR
                  5      PM     nnU Vs/ s H  n[	        XPR                  5      PM     nnU R                  X5      $ s  snnf s  snnf s  snf s  snf )a\  Return a submatrix by specifying a list of rows and columns.
Negative indices can be given. All indices must be in the range
$-n \le i < n$ where $n$ is the number of rows or columns.

Examples
========

>>> from sympy import Matrix
>>> m = Matrix(4, 3, range(12))
>>> m
Matrix([
[0,  1,  2],
[3,  4,  5],
[6,  7,  8],
[9, 10, 11]])
>>> m.extract([0, 1, 3], [0, 1])
Matrix([
[0,  1],
[3,  4],
[9, 10]])

Rows or columns can be repeated:

>>> m.extract([0, 0, 1], [-1])
Matrix([
[2],
[2],
[5]])

Every other row can be taken by using range to provide the indices:

>>> m.extract(range(0, m.rows, 2), [-1])
Matrix([
[2],
[8]])

RowsList or colsList can also be a list of booleans, in which case
the rows or columns corresponding to the True values will be selected:

>>> m.extract([0, 1, 2, 3], [True, False, True])
Matrix([
[0,  2],
[3,  5],
[6,  8],
[9, 11]])
z&rowsList and colsList must be iterablec              3  B   #    U  H  n[        U[        5      v   M     g 7fr   rF   boolr   r   s     rM   r   (MatrixShaping.extract.<locals>.<genexpr>       BAJq$//   c              3  B   #    U  H  n[        U[        5      v   M     g 7fr   r   r   s     rM   r   r     r   r   )r   	TypeErrorall	enumeratea2idxrZ   r[   r   )rm   r   r   indexitemks         rM   extractMatrixShaping.extract  s    ` 8$$K,A,ADEEBBBB1:81DM1D+%1DHMBBBB1:81DM1D+%1DHM 2::AE!YY':19:AE!YY':!!(55 NM ;:s$   D)DD/D<D!D$c                "    U R                  5       $ )a  Obtains the square sub-matrices on the main diagonal of a square matrix.

Useful for inverting symbolic matrices or solving systems of
linear equations which may be decoupled by having a block diagonal
structure.

Examples
========

>>> from sympy import Matrix
>>> from sympy.abc import x, y, z
>>> A = Matrix([[1, 3, 0, 0], [y, z*z, 0, 0], [0, 0, x, 0], [0, 0, 0, 0]])
>>> a1, a2, a3 = A.get_diag_blocks()
>>> a1
Matrix([
[1,    3],
[y, z**2]])
>>> a2
Matrix([[x]])
>>> a3
Matrix([[0]])

)r   rw   s    rM   get_diag_blocksMatrixShaping.get_diag_blocks  s    0 ))++rO   c                    [        U5      S:X  a  U R                  5       $ [        US   5      n[        UR                  U5      $ )zReturn a matrix formed by joining args horizontally (i.e.
by repeated application of row_join).

Examples
========

>>> from sympy import Matrix, eye
>>> Matrix.hstack(eye(2), 2*eye(2))
Matrix([
[1, 0, 2, 0],
[0, 1, 0, 2]])
r   )r   rg   r   r   row_joinrI   rf   klss      rM   hstackMatrixShaping.hstack  s9     t9>88:47mcllD))rO   c                   ^ ^ T R                   T R                  -  UT-  :w  a  [        SUT4-  5      eT R                  UTUU 4S j5      $ )a'  Reshape the matrix. Total number of elements must remain the same.

Examples
========

>>> from sympy import Matrix
>>> m = Matrix(2, 3, lambda i, j: 1)
>>> m
Matrix([
[1, 1, 1],
[1, 1, 1]])
>>> m.reshape(1, 6)
Matrix([[1, 1, 1, 1, 1, 1]])
>>> m.reshape(3, 2)
Matrix([
[1, 1],
[1, 1],
[1, 1]])

z Invalid reshape parameters %d %dc                   > TU T-  U-      $ r   rP   )r   r   r[   rm   s     rM   <lambda>'MatrixShaping.reshape.<locals>.<lambda>  s    $q4x!|2DrO   )rZ   r[   
ValueErrorrg   )rm   rZ   r[   s   ` `rM   reshapeMatrixShaping.reshape  sG    * 99tyy D4K/?4,NOOyyt%DEErO   c                    US:  a  XR                   -  nSUs=::  a  U R                   :  d  O  [        SR                  U5      5      eU R                  U5      $ )zDelete the specified row.r   zRow {} is out of range.)rZ   r   r   r   )rm   r   s     rM   row_delMatrixShaping.row_del  sN    799CC#$))#6==cBCC!!#&&rO   c                n   U (       d  U R                  U5      $ [        U5      nUS:  a  U R                  U-   nUS:  a  SnOXR                  :  a  U R                  nU R                  UR                  :w  a/  [	        SR                  U R                  UR                  5      5      eU R                  X5      $ )zInsert one or more rows at the given row position.

Examples
========

>>> from sympy import zeros, ones
>>> M = zeros(3)
>>> V = ones(1, 3)
>>> M.row_insert(1, V)
Matrix([
[0, 0, 0],
[1, 1, 1],
[0, 0, 0],
[0, 0, 0]])

See Also
========

row
col_insert
r   r   )rg   r    rZ   r[   r%   r   r   r   s      rM   
row_insertMatrixShaping.row_insert%  s    . 99U##Sk7))c/C7C99_))C99

"N		5::.0 0 $$S00rO   c                b   U R                   S:X  aF  U R                  UR                  :w  a,  U R                  UR                  S/ 5      R                  U5      $ U R                  UR                  :w  a/  [	        SR                  U R                  UR                  5      5      eU R                  U5      $ )a  Concatenates two matrices along self's last and rhs's first column

Examples
========

>>> from sympy import zeros, ones
>>> M = zeros(3)
>>> V = ones(3, 1)
>>> M.row_join(V)
Matrix([
[0, 0, 0, 1],
[0, 0, 0, 1],
[0, 0, 0, 1]])

See Also
========

row
col_join
r   r   )r[   rZ   rg   r  r%   r   r   rl   s     rM   r  MatrixShaping.row_joinO  s    , 99>dii5::599UZZB/88??99

"K		5::.0 0 ""5))rO   c                   / n[        U5      nUS:  a  SOU* nU(       a  SOUn X0R                  :X  d  X@R                  :X  a  O!UR                  XU4   5        US-  nUS-  nM@  U(       d;  [	        [        SU< SSU R                  -
  < SU R                  S-
  < S35      5      eU R                  S[        U5      U5      $ )a  Returns the kth diagonal of self. The main diagonal
corresponds to `k=0`; diagonals above and below correspond to
`k > 0` and `k < 0`, respectively. The values of `self[i, j]`
for which `j - i = k`, are returned in order of increasing
`i + j`, starting with `i + j = |k|`.

Examples
========

>>> from sympy import Matrix
>>> m = Matrix(3, 3, lambda i, j: j - i); m
Matrix([
[ 0,  1, 2],
[-1,  0, 1],
[-2, -1, 0]])
>>> _.diagonal()
Matrix([[0, 0, 0]])
>>> m.diagonal(1)
Matrix([[1, 1]])
>>> m.diagonal(-2)
Matrix([[-2]])

Even though the diagonal is returned as a Matrix, the element
retrieval can be done with a single index:

>>> Matrix.diag(1, 2, 3).diagonal()[1]  # instead of [0, 1]
2

See Also
========

diag
r   r   z
            The z diagonal is out of range [, ])r    rZ   r[   r   r  r!   rg   r   )rm   r  rvrr   s        rM   r   MatrixShaping.diagonaln  s    D 1IQAQBAII~iiIIda4j!FAFA  Zq499}dii!m)- . / / yyCGR((rO   c                    XSS24   $ )zElementary row selector.

Examples
========

>>> from sympy import eye
>>> eye(2).row(0)
Matrix([[1, 0]])

See Also
========

col
row_del
row_join
row_insert
NrP   r   s     rM   r   MatrixShaping.row  s    $ qDzrO   c                2    U R                   U R                  4$ )zThe shape (dimensions) of the matrix as the 2-tuple (rows, cols).

Examples
========

>>> from sympy import zeros
>>> M = zeros(2, 3)
>>> M.shape
(2, 3)
>>> M.rows
2
>>> M.cols
3
rZ   r[   rw   s    rM   r|   MatrixShaping.shape  s      		499%%rO   c                "    U R                  5       $ )zReturn the matrix as dictionary of keys.

Examples
========

>>> from sympy import Matrix
>>> M = Matrix.eye(3)
>>> M.todok()
{(0, 0): 1, (1, 1): 1, (2, 2): 1}
)r   rw   s    rM   todokMatrixShaping.todok  s     !!rO   c                    U R                   (       d  / $ U R                  (       d&  [        U R                   5       Vs/ s H  n/ PM     sn$ U R                  5       $ s  snf )a  Return the Matrix as a nested Python list.

Examples
========

>>> from sympy import Matrix, ones
>>> m = Matrix(3, 3, range(9))
>>> m
Matrix([
[0, 1, 2],
[3, 4, 5],
[6, 7, 8]])
>>> m.tolist()
[[0, 1, 2], [3, 4, 5], [6, 7, 8]]
>>> ones(3, 0).tolist()
[[], [], []]

When there are no rows then it will not be possible to tell how
many columns were in the original matrix:

>>> ones(0, 3).tolist()
[]

)rZ   r[   r   r   r   s     rM   tolistMatrixShaping.tolist  sK    2 yyIyy %dii 01 01B 011  "" 2s   Ac                    0 nU R                  5       n[        U5       H:  u  p4[        U5       VVs0 s H  u  pVU(       d  M  XV_M     nnnU(       d  M6  XqU'   M<     U$ s  snnf )zReturns matrix as dict of dicts containing non-zero elements of the Matrix

Examples
========

>>> from sympy import Matrix
>>> A = Matrix([[0, 1],[0, 3]])
>>> A
Matrix([
[0, 1],
[0, 3]])
>>> A.todod()
{0: {1: 1}, 1: {1: 3}}


)r+  r   )r   rowsdictMlolr   Mir   Mijr   s           rM   tododMatrixShaping.todod  s\    " xxzt_EA(1"=fa616C=s! %  >s   AAc                "    U R                  5       $ )zReturn the Matrix converted into a one column matrix by stacking columns

Examples
========

>>> from sympy import Matrix
>>> m=Matrix([[1, 3], [2, 4]])
>>> m
Matrix([
[1, 3],
[2, 4]])
>>> m.vec()
Matrix([
[1],
[2],
[3],
[4]])

See Also
========

vech
)r   rw   s    rM   vecMatrixShaping.vec  s    0 ~~rO   c                    U R                   (       d  [        eU(       a   U R                  5       (       d  [        S5      eU R	                  U5      $ )a  Reshapes the matrix into a column vector by stacking the
elements in the lower triangle.

Parameters
==========

diagonal : bool, optional
    If ``True``, it includes the diagonal elements.

check_symmetry : bool, optional
    If ``True``, it checks whether the matrix is symmetric.

Examples
========

>>> from sympy import Matrix
>>> m=Matrix([[1, 2], [2, 3]])
>>> m
Matrix([
[1, 2],
[2, 3]])
>>> m.vech()
Matrix([
[1],
[2],
[3]])
>>> m.vech(diagonal=False)
Matrix([[2]])

Notes
=====

This should work for symmetric matrices and ``vech`` can
represent symmetric matrices in vector form with less size than
``vec``.

See Also
========

vec
zThe matrix is not symmetric.)	is_squarer&   is_symmetricr  r   )rm   r   check_symmetrys      rM   vechMatrixShaping.vech%  s>    T ~~&&$"3"3"5"5;<<x((rO   c                    [        U5      S:X  a  U R                  5       $ [        US   5      n[        UR                  U5      $ )zReturn a matrix formed by joining args vertically (i.e.
by repeated application of col_join).

Examples
========

>>> from sympy import Matrix, eye
>>> Matrix.vstack(eye(2), 2*eye(2))
Matrix([
[1, 0],
[0, 1],
[2, 0],
[0, 2]])
r   )r   rg   r   r   r   r	  s      rM   vstackMatrixShaping.vstackW  s9      t9>88:47mcllD))rO   rP   Nr   )TT)(rB   rQ   rR   rS   r~   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r  r  r   r  r  r  r  r  r   r   r   r|   r(  r+  r2  r5  r;  r>  rT   rP   rO   rM   r)   r)      s    E:
	C	04*:
E	0;	.'''1R*@,<6|,4 * *&F2'(1T*>0)d( & &""#>2 40)d * *rO   r)   c                     \ rS rSrSr\S 5       r\S 5       r\SSS jj5       r\S 5       r	\S 5       r
\S	 5       r\S
SSSS.S j5       r\SS j5       r\SSS.S jj5       r\SS j5       r\SS j5       r\S 5       r\S 5       rSrg)r*   in  z Construction of special matricesc                4   ^ U4S jnU R                  XU5      $ )zMdiag_dict is a defaultdict containing
all the entries of the diagonal matrix.c                   > TX4   $ r   rP   )r   r   	diag_dicts     rM   r   'MatrixSpecial._eval_diag.<locals>.entryu  s    aV$$rO   rg   )rI   rZ   r[   rD  r   s      ` rM   
_eval_diagMatrixSpecial._eval_diagq  s    	%xxE**rO   c                    U R                   /X-  -  nU R                  /[        X5      -  US S US-   2'   U R                  XUSS9$ )Nr   Fcopy)r   oneminrg   )rI   rZ   r[   valss       rM   	_eval_eyeMatrixSpecial._eval_eyey  sI    z49%''3t?2XtAvXxxDux55rO   upperc                T   ^ ^ US:X  a  U U4S jnOU U4S jnT R                  XU5      $ )Nlowerc                T   > X:X  a  T$ US-   U :X  a  TR                   $ TR                  $ r   rL  r   r   r   rI   
eigenvalues     rM   r   /MatrixSpecial._eval_jordan_block.<locals>.entry  +    6%%UaZ77NxxrO   c                T   > X:X  a  T$ U S-   U:X  a  TR                   $ TR                  $ r   rU  rV  s     rM   r   rX    rY  rO   rF  )rI   sizerW  bandr   s   ` `  rM   _eval_jordan_block MatrixSpecial._eval_jordan_block  s'    7?   xxE**rO   c                4   ^  U 4S jnT R                  XU5      $ )Nc                   > TR                   $ r   rL  r   r   rI   s     rM   r   'MatrixSpecial._eval_ones.<locals>.entry  s    77NrO   rF  )rI   rZ   r[   r   s   `   rM   
_eval_onesMatrixSpecial._eval_ones  s    	xxE**rO   c                D    U R                  XU R                  /X-  -  SS9$ )NFrJ  )rg   r   )rI   rZ   r[   s      rM   _eval_zerosMatrixSpecial._eval_zeros  s$    xxSXXJ	$:xGGrO   c                B  ^  U 4S jnT R                  SU-  S-   SU-  S-   U5      nT R                  [        [        U* US-   5      5      SS9U-   UR                  -   n[        T R                  [        [        U* US-   5      5      SS95      U-   UR                  -   nXE4$ )Nc                F   > U S-   U:X  a  TR                   $ TR                  $ r   rU  rb  s     rM   r   ,MatrixSpecial._eval_wilkinson.<locals>.entry  s     !eqj3776chh6rO      r   T)unpack)rg   diagr   r   Tabs)rI   r   r   Dwminuswpluss   `     rM   _eval_wilkinsonMatrixSpecial._eval_wilkinson  s    	7 HHQqS1WacAgu-$uaRQ/0>BQSSHCHHT%AE"23DHABQFL}rO   FTN)strictrm  rZ   r[   c          
        SSK Jn  SSKJn  SSKJn	  UR                  SU 5      n
U(       a;  [        U5      S:X  a,  [        US   5      (       a  [        US   U5      (       d  US   n[        [        5      nS=pU GH  n[        U[        5      (       ap  U(       a(  U" U5      nUR                  u  nnUR                  5       nOU	R                  U5      u  nnnUR!                  5        H  u  u  nnnXUU-   UU-   4'   M     / nOB[#        US5      (       a   UR                  u  nnUR                  5       nOXX4'   US-  nUS-  nM  [%        U5       H'  u  nn[%        U5       H  u  nnXUU-   UU-   4'   M     M)     UU-  nUU-  nGM     Uc  XCpCUc  XpCOUc  UOUnX<:  d  XM:  a$  ['        [)        SR+                  XX45      5      5      eU
R-                  X4U5      $ )	a)  Returns a matrix with the specified diagonal.
If matrices are passed, a block-diagonal matrix
is created (i.e. the "direct sum" of the matrices).

kwargs
======

rows : rows of the resulting matrix; computed if
       not given.

cols : columns of the resulting matrix; computed if
       not given.

cls : class for the resulting matrix

unpack : bool which, when True (default), unpacks a single
sequence rather than interpreting it as a Matrix.

strict : bool which, when False (default), allows Matrices to
have variable-length rows.

Examples
========

>>> from sympy import Matrix
>>> Matrix.diag(1, 2, 3)
Matrix([
[1, 0, 0],
[0, 2, 0],
[0, 0, 3]])

The current default is to unpack a single sequence. If this is
not desired, set `unpack=False` and it will be interpreted as
a matrix.

>>> Matrix.diag([1, 2, 3]) == Matrix.diag(1, 2, 3)
True

When more than one element is passed, each is interpreted as
something to put on the diagonal. Lists are converted to
matrices. Filling of the diagonal always continues from
the bottom right hand corner of the previous item: this
will create a block-diagonal matrix whether the matrices
are square or not.

>>> col = [1, 2, 3]
>>> row = [[4, 5]]
>>> Matrix.diag(col, row)
Matrix([
[1, 0, 0],
[2, 0, 0],
[3, 0, 0],
[0, 4, 5]])

When `unpack` is False, elements within a list need not all be
of the same length. Setting `strict` to True would raise a
ValueError for the following:

>>> Matrix.diag([[1, 2, 3], [4, 5], [6]], unpack=False)
Matrix([
[1, 2, 3],
[4, 5, 0],
[6, 0, 0]])

The type of the returned matrix can be set with the ``cls``
keyword.

>>> from sympy import ImmutableMatrix
>>> from sympy.utilities.misc import func_name
>>> func_name(Matrix.diag(1, cls=ImmutableMatrix))
'ImmutableDenseMatrix'

A zero dimension matrix can be used to position the start of
the filling at the start of an arbitrary row or column:

>>> from sympy import ones
>>> r2 = ones(0, 2)
>>> Matrix.diag(r2, 1, 2)
Matrix([
[0, 0, 1, 0],
[0, 0, 0, 2]])

See Also
========
eye
diagonal
.dense.diag
.expressions.blockmatrix.BlockMatrix
.sparsetools.banded
r   r@   )Matrix)SparseMatrixrI   r   r|   zg
                The constructed matrix is {} x {} but a size of {} x {}
                was specified.)rC   rA   sympy.matrices.denserx  sympy.matricesry  getr   r   rF   r   rY   r   r|   r+  _handle_creation_inputsitemshasattrr   r  r!   r   rG  )r
  rv  rm  rZ   r[   rf   r_   rA   rx  ry  klassdiag_entriesrmaxcmaxmr   r   r   smatr   r   mis                         rM   rn  MatrixSpecial.diag  s   x 	9//

5#&c$i1nT!W)=)=tAw
337D #3'A!T""q	A77DAq
A!-!E!Ea!HJAq$%)ZZ\	A=>a$hD%9: &2AG$$ww1HHJ-.d\*		"12%bMDAq9:!d(AH!56 * & AIDAID5 6 <$<$<4TD;$+Z )""(&T"@B C C L99rO   c                    Uc  UnUS:  d  US:  a  [        SR                  X5      5      eUR                  SU 5      n[        U5      [        U5      p!UR	                  X5      $ )zReturns an identity matrix.

Parameters
==========

rows : rows of the matrix
cols : cols of the matrix (if None, cols=rows)

kwargs
======
cls : class of the returned matrix
r   @Cannot create a {} x {} matrix. Both dimensions must be positiverI   )r  r   r|  r    rO  r
  rZ   r[   r_   r  s        rM   eyeMatrixSpecial.eye5  sh     <D!8tax @@Ft@RT T

5#&D\6$<dt**rO   )r\  c                  UR                  SU 5      nUR                  SS5      nUc  Uc  [        S5      eX&:w  a!  SXb4;  a  [        SR                  Xb5      5      eUb  UnUc  [        S5      e[	        U5      nUR                  XU5      $ )a  Returns a Jordan block

Parameters
==========

size : Integer, optional
    Specifies the shape of the Jordan block matrix.

eigenvalue : Number or Symbol
    Specifies the value for the main diagonal of the matrix.

    .. note::
        The keyword ``eigenval`` is also specified as an alias
        of this keyword, but it is not recommended to use.

        We may deprecate the alias in later release.

band : 'upper' or 'lower', optional
    Specifies the position of the off-diagonal to put `1` s on.

cls : Matrix, optional
    Specifies the matrix class of the output form.

    If it is not specified, the class type where the method is
    being executed on will be returned.

Returns
=======

Matrix
    A Jordan block matrix.

Raises
======

ValueError
    If insufficient arguments are given for matrix size
    specification, or no eigenvalue is given.

Examples
========

Creating a default Jordan block:

>>> from sympy import Matrix
>>> from sympy.abc import x
>>> Matrix.jordan_block(4, x)
Matrix([
[x, 1, 0, 0],
[0, x, 1, 0],
[0, 0, x, 1],
[0, 0, 0, x]])

Creating an alternative Jordan block matrix where `1` is on
lower off-diagonal:

>>> Matrix.jordan_block(4, x, band='lower')
Matrix([
[x, 0, 0, 0],
[1, x, 0, 0],
[0, 1, x, 0],
[0, 0, 1, x]])

Creating a Jordan block with keyword arguments

>>> Matrix.jordan_block(size=4, eigenvalue=x)
Matrix([
[x, 1, 0, 0],
[0, x, 1, 0],
[0, 0, x, 1],
[0, 0, 0, x]])

References
==========

.. [1] https://en.wikipedia.org/wiki/Jordan_matrix
rI   eigenvalNzMust supply an eigenvaluez=Inconsistent values are given: 'eigenval'={}, 'eigenvalue'={}zMust supply a matrix size)popr|  r  r   r    r]  )r
  r[  rW  r\  r_   r  r  s          rM   jordan_blockMatrixSpecial.jordan_blockM  s    ^ 

5#&::j$/("2899#X4J(J""(&">@ @ #%
<899d|''$??rO   c                |    Uc  UnUR                  SU 5      n[        U5      [        U5      p!UR                  X5      $ )zReturns a matrix of ones.

Parameters
==========

rows : rows of the matrix
cols : cols of the matrix (if None, cols=rows)

kwargs
======
cls : class of the returned matrix
rI   )r|  r    rd  r  s        rM   onesMatrixSpecial.ones  s>     <D

5#&D\6$<d++rO   c                    Uc  UnUS:  d  US:  a  [        SR                  X5      5      eUR                  SU 5      n[        U5      [        U5      p!UR	                  X5      $ )zReturns a matrix of zeros.

Parameters
==========

rows : rows of the matrix
cols : cols of the matrix (if None, cols=rows)

kwargs
======
cls : class of the returned matrix
r   r  rI   )r  r   r|  r    rg  r  s        rM   zerosMatrixSpecial.zeros  sj     <D!8tax @@Ft@RT T

5#&D\6$<d  ,,rO   c                  ^ ^^ T R                  U5      n[        U[        5      (       d  [        SR	                  U5      5      eUR
                  (       d  [        SR	                  U5      5      eUR                  (       d  [        SR	                  U5      5      eUR                  5       mTS:  d  [        SR	                  U5      5      eUR                  5       mUU U4S jnT R                  TTU5      $ )ar  Returns a companion matrix of a polynomial.

Examples
========

>>> from sympy import Matrix, Poly, Symbol, symbols
>>> x = Symbol('x')
>>> c0, c1, c2, c3, c4 = symbols('c0:5')
>>> p = Poly(c0 + c1*x + c2*x**2 + c3*x**3 + c4*x**4 + x**5, x)
>>> Matrix.companion(p)
Matrix([
[0, 0, 0, 0, -c0],
[1, 0, 0, 0, -c1],
[0, 1, 0, 0, -c2],
[0, 0, 1, 0, -c3],
[0, 0, 0, 1, -c4]])
z{} must be a Poly instance.z{} must be a monic polynomial.z#{} must be a univariate polynomial.r   z${} must have degree not less than 1.c                h   > UTS-
  :X  a	  TSU -
     * $ XS-   :X  a  TR                   $ TR                  $ )Nr   rU  )r   r   coeffsr
  r[  s     rM   r   &MatrixSpecial.companion.<locals>.entry  s9    D1H}rAv&!eww88OrO   )
_sympifyrF   r   r  r   is_monicis_univariatedegree
all_coeffsrg   )r
  polyr   r  r[  s   `  @@rM   	companionMatrixSpecial.companion  s    & ||D!$%%:AA$GHH}}=DDTJKK!!5<<TBD D {{}qy6==dCE E "	 xxdE**rO   c                ^    UR                  SU 5      n[        U5      nUR                  U5      $ )a  Returns two square Wilkinson Matrix of size 2*n + 1
$W_{2n + 1}^-, W_{2n + 1}^+ =$ Wilkinson(n)

Examples
========

>>> from sympy import Matrix
>>> wminus, wplus = Matrix.wilkinson(3)
>>> wminus
Matrix([
[-3,  1,  0, 0, 0, 0, 0],
[ 1, -2,  1, 0, 0, 0, 0],
[ 0,  1, -1, 1, 0, 0, 0],
[ 0,  0,  1, 0, 1, 0, 0],
[ 0,  0,  0, 1, 1, 1, 0],
[ 0,  0,  0, 0, 1, 2, 1],
[ 0,  0,  0, 0, 0, 1, 3]])
>>> wplus
Matrix([
[3, 1, 0, 0, 0, 0, 0],
[1, 2, 1, 0, 0, 0, 0],
[0, 1, 1, 1, 0, 0, 0],
[0, 0, 1, 0, 1, 0, 0],
[0, 0, 0, 1, 1, 1, 0],
[0, 0, 0, 0, 1, 2, 1],
[0, 0, 0, 0, 0, 1, 3]])

References
==========

.. [1] https://blogs.mathworks.com/cleve/2013/04/15/wilkinsons-matrices-2/
.. [2] J. H. Wilkinson, The Algebraic Eigenvalue Problem, Claredon Press, Oxford, 1965, 662 pp.

rI   )r|  r    rt  )r
  r   r_   r  s       rM   	wilkinsonMatrixSpecial.wilkinson  s/    H 

5#&1I$$Q''rO   rP   )rQ  )r[  rY   r   )NN)rB   rQ   rR   rS   r~   r   rG  rO  r]  rd  rg  rt  rn  r  r  r  r  r  r  rT   rP   rO   rM   r*   r*   n  s$   *+ + 6 6
 + +" + +
 H H 	 	  %dD K: K:Z + +. _@g _@ _@B , ,( - -. '+ '+T %( %(rO   r*   c                  b   \ rS rSrSrS rS rS rS rS r	S r
S'S	 jrS
 rS rS rS rS rS rS rS rS rS r\S 5       rS rS(S jrS r\S 5       r\S 5       r\S 5       r\S'S j5       r\S 5       r\S 5       r \S 5       r!S r"S(S  jr#\S! 5       r$\S" 5       r%\S# 5       r&S$ r'S%r(g&))r+   i/  z&Provides basic properties of a matrix.c                h    [        5       nU  H!  nUR                  UR                  " U6 5        M#     U$ r   )setupdateatoms)rm   typesresultr   s       rM   _eval_atomsMatrixProperties._eval_atoms2  s,    AMM!''5/* rO   c                >    [        5       R                  " S U  5       6 $ )Nc              3  J   #    U  H  o(       d  M  UR                   v   M     g 7fr   )free_symbolsr   s     rM   r   6MatrixProperties._eval_free_symbols.<locals>.<genexpr>9  s     ?TQ^Q^^Ts   
##)r  unionrw   s    rM   _eval_free_symbols#MatrixProperties._eval_free_symbols8  s    u{{?T?@@rO   c                .   ^ [        U4S jU  5       5      $ )Nc              3  @   >#    U  H  oR                   " T6 v   M     g 7fr   )has)r   apatternss     rM   r   -MatrixProperties._eval_has.<locals>.<genexpr><  s     2T55(#Ts   r   rm   r  s    `rM   	_eval_hasMatrixProperties._eval_has;  s    2T222rO   c                f   ^ ^ [        U U4S j[        T R                  5       5       5      (       d  gg)Nc              3     >#    U  H?  n[        TR                  5        H"  nT" TX4   TX!4   -   5      R                  v   M$     MA     g 7fr   r   r[   is_zero)r   r   r   rm   simpfuncs      rM   r   ;MatrixProperties._eval_is_anti_symmetric.<locals>.<genexpr>?  sG     qFV`efjfofo`p[\8DJad34<<`p<FV   AA
FTr   r   rZ   )rm   r  s   ``rM   _eval_is_anti_symmetric(MatrixProperties._eval_is_anti_symmetric>  s#    qeDIIFVqqqrO   c                    [        U R                  5       H4  n[        U R                  5       H  nX:w  d  M
  XU4   (       d  M      g   M6     g)NFT)r   rZ   r[   )rm   r   r   s      rM   _eval_is_diagonal"MatrixProperties._eval_is_diagonalC  s?    tyy!A499%6da4jj  & " rO   c                v   ^ ^ T R                  T R                  T R                  U U4S j5      nUR                  $ )Nc                F   > T" TX4   TX4   R                  5       -
  5      $ r   	conjugater   r   rm   r  s     rM   r  <MatrixProperties._eval_is_matrix_hermitian.<locals>.<lambda>N  s(    8DJQUVWVZQ[QeQeQgDg;hrO   rg   rZ   r[   is_zero_matrixrm   r  r   s   `` rM   _eval_is_matrix_hermitian*MatrixProperties._eval_is_matrix_hermitianM  s*    ii		499.hi!!!rO   c                ^   ^ ^ S m[        UU 4S j[        T R                  5       5       5      $ )Nc                    X:X  a  ggr   rP   r   r   s     rM   dirac1MatrixProperties._eval_is_Identity.<locals>.diracR  s    vrO   c              3  |   >#    U  H1  n[        TR                  5        H  nTX4   T" X5      :H  v   M     M3     g 7fr   )r   r[   )r   r   r   r  rm   s      rM   r   5MatrixProperties._eval_is_Identity.<locals>.<genexpr>W  s=      +)Atyy)A :q,) -)s   9<r  )rm   r  s   `@rM   _eval_is_Identity"MatrixProperties._eval_is_IdentityQ  s-    	
  +tyy)+ + 	+rO   c                T   ^  [        U 4S j[        T R                  5       5       5      $ )Nc              3     >#    U  H6  n[        US -   TR                  5        H  nTX4   R                  v   M     M8     g7f)rl  Nr  r   r   r   rm   s      rM   r   =MatrixProperties._eval_is_lower_hessenberg.<locals>.<genexpr>\  @      5,q!!a%3q :%%3 &,   >Ar  rw   s   `rM   _eval_is_lower_hessenberg*MatrixProperties._eval_is_lower_hessenberg[  &     5!$)),5 5 	5rO   c                T   ^  [        U 4S j[        T R                  5       5       5      $ )Nc              3     >#    U  H6  n[        US -   TR                  5        H  nTX4   R                  v   M     M8     g7fr   Nr  r  s      rM   r   2MatrixProperties._eval_is_lower.<locals>.<genexpr>a  r  r  r  rw   s   `rM   _eval_is_lowerMatrixProperties._eval_is_lower`  r  rO   c                ,    U R                  [        5      $ r   )r  r   rw   s    rM   _eval_is_symbolic"MatrixProperties._eval_is_symbolice  s    xxrO   c                v   ^ ^ T R                  T R                  T R                  U U4S j5      nUR                  $ )Nc                *   > T" TX4   TX4   -
  5      $ r   rP   r  s     rM   r  5MatrixProperties._eval_is_symmetric.<locals>.<lambda>i  s    8DJQUVWVZQ[D[;\rO   r  r  s   `` rM   _eval_is_symmetric#MatrixProperties._eval_is_symmetrich  s*    ii		499.\]!!!rO   c                d    [        S U  5       5      (       a  g[        S U  5       5      (       a  g g)Nc              3  >   #    U  H  oR                   S :H  v   M     g7f)FNr  r   s     rM   r   8MatrixProperties._eval_is_zero_matrix.<locals>.<genexpr>m  s     04ayyE!4s   Fc              3  <   #    U  H  oR                   S L v   M     g 7fr   r  r   s     rM   r   r  o  s     /$QyyD $s   Tr  rw   s    rM   _eval_is_zero_matrix%MatrixProperties._eval_is_zero_matrixl  s-    04000/$///rO   c                V   ^  [        U 4S j[        ST R                  5       5       5      $ )Nc              3     >#    U  H?  n[        [        TR                  US -
  5      5        H  nTX4   R                  v   M     MA     g7fr  r   rM  r[   r  r  s      rM   r   =MatrixProperties._eval_is_upper_hessenberg.<locals>.<genexpr>t  sE      </q!#dii!a%"9:q :%%: &/r  rl  r  rw   s   `rM   _eval_is_upper_hessenberg*MatrixProperties._eval_is_upper_hessenbergs  s(     <!!TYY/< < 	<rO   c                V    U  Vs/ s H  oR                   (       a  M  UPM     sn$ s  snf r   r  r   s     rM   _eval_valuesMatrixProperties._eval_valuesx  s    14ayy4111s   &&c                f   ^  U 4S j[        T R                  5       5       n[        S U 5       5      $ )Nc              3  0   >#    U  H  nTX4   v   M     g 7fr   rP   r   r   rm   s     rM   r   ;MatrixProperties._has_positive_diagonals.<locals>.<genexpr>|       A0@1DJ0@   c              3  8   #    U  H  oR                   v   M     g 7fr   )is_positiver   xs     rM   r   r  }  s     A0@10@   r   rZ   r   rm   diagonal_entriess   ` rM   _has_positive_diagonals(MatrixProperties._has_positive_diagonals{  s)    Adii0@AA0@AAArO   c                f   ^  U 4S j[        T R                  5       5       n[        S U 5       5      $ )Nc              3  0   >#    U  H  nTX4   v   M     g 7fr   rP   r  s     rM   r   >MatrixProperties._has_nonnegative_diagonals.<locals>.<genexpr>  r  r  c              3  8   #    U  H  oR                   v   M     g 7fr   )is_nonnegativer  s     rM   r   r    s     D3Ca))3Cr  r  r  s   ` rM   _has_nonnegative_diagonals+MatrixProperties._has_nonnegative_diagonals  s)    Adii0@AD3CDDDrO   c                `    [        S U 5       5      nU(       d  [        4nU R                  " U6 $ )zReturns the atoms that form the current object.

Examples
========

>>> from sympy.abc import x, y
>>> from sympy import Matrix
>>> Matrix([[x]])
Matrix([[x]])
>>> _.atoms()
{x}
>>> Matrix([[x, y], [y, x]])
Matrix([
[x, y],
[y, x]])
>>> _.atoms()
{x, y}
c              3  f   #    U  H'  n[        U[        5      (       a  UO
[        U5      v   M)     g 7fr   )rF   r   )r   ts     rM   r   )MatrixProperties.atoms.<locals>.<genexpr>  s%     KU:a..aDG;Us   /1)tupler   r  )rm   r  s     rM   r  MatrixProperties.atoms  s/    ( KUKKGE''rO   c                "    U R                  5       $ )zReturns the free symbols within the matrix.

Examples
========

>>> from sympy.abc import x
>>> from sympy import Matrix
>>> Matrix([[x], [1]]).free_symbols
{x}
)r  rw   s    rM   r  MatrixProperties.free_symbols  s     &&((rO   c                     U R                   " U6 $ )ac  Test whether any subexpression matches any of the patterns.

Examples
========

>>> from sympy import Matrix, SparseMatrix, Float
>>> from sympy.abc import x, y
>>> A = Matrix(((1, x), (0.2, 3)))
>>> B = SparseMatrix(((1, x), (0.2, 3)))
>>> A.has(x)
True
>>> A.has(y)
False
>>> A.has(Float)
True
>>> B.has(x)
True
>>> B.has(y)
False
>>> B.has(Float)
True
)r  r  s     rM   r  MatrixProperties.has  s    . ~~x((rO   c                    Un[        U5      (       d  U(       a  [        OS nU R                  (       d  gU R                  U5      $ )a  Check if matrix M is an antisymmetric matrix,
that is, M is a square matrix with all M[i, j] == -M[j, i].

When ``simplify=True`` (default), the sum M[i, j] + M[j, i] is
simplified before testing to see if it is zero. By default,
the SymPy simplify function is used. To use a custom function
set simplify to a function that accepts a single argument which
returns a simplified expression. To skip simplification, set
simplify to False but note that although this will be faster,
it may induce false negatives.

Examples
========

>>> from sympy import Matrix, symbols
>>> m = Matrix(2, 2, [0, 1, -1, 0])
>>> m
Matrix([
[ 0, 1],
[-1, 0]])
>>> m.is_anti_symmetric()
True
>>> x, y = symbols('x y')
>>> m = Matrix(2, 3, [0, 0, x, -y, 0, 0])
>>> m
Matrix([
[ 0, 0, x],
[-y, 0, 0]])
>>> m.is_anti_symmetric()
False

>>> from sympy.abc import x, y
>>> m = Matrix(3, 3, [0, x**2 + 2*x + 1, y,
...                   -(x + 1)**2, 0, x*y,
...                   -y, -x*y, 0])

Simplification of matrix elements is done by default so even
though two elements which should be equal and opposite would not
pass an equality test, the matrix is still reported as
anti-symmetric:

>>> m[0, 1] == -m[1, 0]
False
>>> m.is_anti_symmetric()
True

If ``simplify=False`` is used for the case when a Matrix is already
simplified, this will speed things up. Here, we see that without
simplification the matrix does not appear anti-symmetric:

>>> print(m.is_anti_symmetric(simplify=False))
None

But if the matrix were already expanded, then it would appear
anti-symmetric and simplification in the is_anti_symmetric routine
is not needed:

>>> m = m.expand()
>>> m.is_anti_symmetric(simplify=False)
True
c                    U $ r   rP   r  s    rM   r  4MatrixProperties.is_anti_symmetric.<locals>.<lambda>      ArO   F)r   r   r8  r  rm   simplifyr  s      rM   is_anti_symmetric"MatrixProperties.is_anti_symmetric  s9    ~ (##$,y+H~~++H55rO   c                "    U R                  5       $ )a&  Check if matrix is diagonal,
that is matrix in which the entries outside the main diagonal are all zero.

Examples
========

>>> from sympy import Matrix, diag
>>> m = Matrix(2, 2, [1, 0, 0, 2])
>>> m
Matrix([
[1, 0],
[0, 2]])
>>> m.is_diagonal()
True

>>> m = Matrix(2, 2, [1, 1, 0, 2])
>>> m
Matrix([
[1, 1],
[0, 2]])
>>> m.is_diagonal()
False

>>> m = diag(1, 2, 3)
>>> m
Matrix([
[1, 0, 0],
[0, 2, 0],
[0, 0, 3]])
>>> m.is_diagonal()
True

See Also
========

is_lower
is_upper
sympy.matrices.matrixbase.MatrixCommon.is_diagonalizable
diagonalize
)r  rw   s    rM   is_diagonalMatrixProperties.is_diagonal
  s    R %%''rO   c                   ^ ^^ T R                   (       d  gT R                  u  nmUU 4S jm[        U4S j[        U5       5       5      $ )a  Tests if the matrix is row weakly diagonally dominant.

Explanation
===========

A $n, n$ matrix $A$ is row weakly diagonally dominant if

.. math::
    \left|A_{i, i}\right| \ge \sum_{j = 0, j \neq i}^{n-1}
    \left|A_{i, j}\right| \quad {\text{for all }}
    i \in \{ 0, ..., n-1 \}

Examples
========

>>> from sympy import Matrix
>>> A = Matrix([[3, -2, 1], [1, -3, 2], [-1, 2, 4]])
>>> A.is_weakly_diagonally_dominant
True

>>> A = Matrix([[-2, 2, 1], [1, 3, 2], [1, -2, 0]])
>>> A.is_weakly_diagonally_dominant
False

>>> A = Matrix([[-4, 2, 1], [1, 6, 2], [1, -2, 5]])
>>> A.is_weakly_diagonally_dominant
True

Notes
=====

If you want to test whether a matrix is column diagonally
dominant, you can apply the test after transposing the matrix.
Fc                   > TR                   n[        T5       H  nX:w  d  M
  U[        TX4   5      -  nM     [        TX 4   5      U-
  R                  $ r   )r   r   r   r  r   	summationr   r[   rm   s      rM   test_row@MatrixProperties.is_weakly_diagonally_dominant.<locals>.test_row^  sP    		I4[6T!$Z0I ! QT
Oi/???rO   c              3  4   >#    U  H  nT" U5      v   M     g 7fr   rP   r   r   r;  s     rM   r   AMatrixProperties.is_weakly_diagonally_dominant.<locals>.<genexpr>e       :k!k   r8  r|   r   r   rm   rZ   r[   r;  s   ` @@rM   is_weakly_diagonally_dominant.MatrixProperties.is_weakly_diagonally_dominant5  s:    H ~~ZZ
d	@ :eDk:::rO   c                   ^ ^^ T R                   (       d  gT R                  u  nmUU 4S jm[        U4S j[        U5       5       5      $ )a  Tests if the matrix is row strongly diagonally dominant.

Explanation
===========

A $n, n$ matrix $A$ is row strongly diagonally dominant if

.. math::
    \left|A_{i, i}\right| > \sum_{j = 0, j \neq i}^{n-1}
    \left|A_{i, j}\right| \quad {\text{for all }}
    i \in \{ 0, ..., n-1 \}

Examples
========

>>> from sympy import Matrix
>>> A = Matrix([[3, -2, 1], [1, -3, 2], [-1, 2, 4]])
>>> A.is_strongly_diagonally_dominant
False

>>> A = Matrix([[-2, 2, 1], [1, 3, 2], [1, -2, 0]])
>>> A.is_strongly_diagonally_dominant
False

>>> A = Matrix([[-4, 2, 1], [1, 6, 2], [1, -2, 5]])
>>> A.is_strongly_diagonally_dominant
True

Notes
=====

If you want to test whether a matrix is column diagonally
dominant, you can apply the test after transposing the matrix.
Fc                   > TR                   n[        T5       H  nX:w  d  M
  U[        TX4   5      -  nM     [        TX 4   5      U-
  R                  $ r   )r   r   r   r  r9  s      rM   r;  BMatrixProperties.is_strongly_diagonally_dominant.<locals>.test_row  sP    		I4[6T!$Z0I ! QT
Oi/<<<rO   c              3  4   >#    U  H  nT" U5      v   M     g 7fr   rP   r>  s     rM   r   CMatrixProperties.is_strongly_diagonally_dominant.<locals>.<genexpr>  r@  rA  rB  rC  s   ` @@rM   is_strongly_diagonally_dominant0MatrixProperties.is_strongly_diagonally_dominantg  s9    H ~~ZZ
d	= :eDk:::rO   c                P    U R                   (       d  gU R                  [        5      $ )a  Checks if the matrix is Hermitian.

In a Hermitian matrix element i,j is the complex conjugate of
element j,i.

Examples
========

>>> from sympy import Matrix
>>> from sympy import I
>>> from sympy.abc import x
>>> a = Matrix([[1, I], [-I, 1]])
>>> a
Matrix([
[ 1, I],
[-I, 1]])
>>> a.is_hermitian
True
>>> a[0, 0] = 2*I
>>> a.is_hermitian
False
>>> a[0, 0] = x
>>> a.is_hermitian
>>> a[0, 1] = a[1, 0]*I
>>> a.is_hermitian
False
F)r8  r  r   rw   s    rM   is_hermitianMatrixProperties.is_hermitian  s    : ~~--i88rO   c                F    U R                   (       d  gU R                  5       $ NF)r8  r  rw   s    rM   is_IdentityMatrixProperties.is_Identity  s    ~~%%''rO   c                "    U R                  5       $ )a  Checks if the matrix is in the lower-Hessenberg form.

The lower hessenberg matrix has zero entries
above the first superdiagonal.

Examples
========

>>> from sympy import Matrix
>>> a = Matrix([[1, 2, 0, 0], [5, 2, 3, 0], [3, 4, 3, 7], [5, 6, 1, 1]])
>>> a
Matrix([
[1, 2, 0, 0],
[5, 2, 3, 0],
[3, 4, 3, 7],
[5, 6, 1, 1]])
>>> a.is_lower_hessenberg
True

See Also
========

is_upper_hessenberg
is_lower
)r  rw   s    rM   is_lower_hessenberg$MatrixProperties.is_lower_hessenberg      6 --//rO   c                "    U R                  5       $ )a\  Check if matrix is a lower triangular matrix. True can be returned
even if the matrix is not square.

Examples
========

>>> from sympy import Matrix
>>> m = Matrix(2, 2, [1, 0, 0, 1])
>>> m
Matrix([
[1, 0],
[0, 1]])
>>> m.is_lower
True

>>> m = Matrix(4, 3, [0, 0, 0, 2, 0, 0, 1, 4, 0, 6, 6, 5])
>>> m
Matrix([
[0, 0, 0],
[2, 0, 0],
[1, 4, 0],
[6, 6, 5]])
>>> m.is_lower
True

>>> from sympy.abc import x, y
>>> m = Matrix(2, 2, [x**2 + y, y**2 + x, 0, x + y])
>>> m
Matrix([
[x**2 + y, x + y**2],
[       0,    x + y]])
>>> m.is_lower
False

See Also
========

is_upper
is_diagonal
is_lower_hessenberg
)r  rw   s    rM   is_lowerMatrixProperties.is_lower  s    V ""$$rO   c                4    U R                   U R                  :H  $ )a  Checks if a matrix is square.

A matrix is square if the number of rows equals the number of columns.
The empty matrix is square by definition, since the number of rows and
the number of columns are both zero.

Examples
========

>>> from sympy import Matrix
>>> a = Matrix([[1, 2, 3], [4, 5, 6]])
>>> b = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> c = Matrix([])
>>> a.is_square
False
>>> b.is_square
True
>>> c.is_square
True
r%  rw   s    rM   r8  MatrixProperties.is_square  s    , yyDII%%rO   c                "    U R                  5       $ )zChecks if any elements contain Symbols.

Examples
========

>>> from sympy import Matrix
>>> from sympy.abc import x, y
>>> M = Matrix([[x, y], [1, 0]])
>>> M.is_symbolic()
True

)r  rw   s    rM   is_symbolicMatrixProperties.is_symbolic#  s     %%''rO   c                    Un[        U5      (       d  U(       a  [        OS nU R                  (       d  gU R                  U5      $ )a(  Check if matrix is symmetric matrix,
that is square matrix and is equal to its transpose.

By default, simplifications occur before testing symmetry.
They can be skipped using 'simplify=False'; while speeding things a bit,
this may however induce false negatives.

Examples
========

>>> from sympy import Matrix
>>> m = Matrix(2, 2, [0, 1, 1, 2])
>>> m
Matrix([
[0, 1],
[1, 2]])
>>> m.is_symmetric()
True

>>> m = Matrix(2, 2, [0, 1, 2, 0])
>>> m
Matrix([
[0, 1],
[2, 0]])
>>> m.is_symmetric()
False

>>> m = Matrix(2, 3, [0, 0, 0, 0, 0, 0])
>>> m
Matrix([
[0, 0, 0],
[0, 0, 0]])
>>> m.is_symmetric()
False

>>> from sympy.abc import x, y
>>> m = Matrix(3, 3, [1, x**2 + 2*x + 1, y, (x + 1)**2, 2, 0, y, 0, 3])
>>> m
Matrix([
[         1, x**2 + 2*x + 1, y],
[(x + 1)**2,              2, 0],
[         y,              0, 3]])
>>> m.is_symmetric()
True

If the matrix is already simplified, you may speed-up is_symmetric()
test by using 'simplify=False'.

>>> bool(m.is_symmetric(simplify=False))
False
>>> m1 = m.expand()
>>> m1.is_symmetric(simplify=False)
True
c                    U $ r   rP   r-  s    rM   r  /MatrixProperties.is_symmetric.<locals>.<lambda>k  r/  rO   F)r   r   r8  r  r0  s      rM   r9  MatrixProperties.is_symmetric2  s9    n (##$,y+H~~&&x00rO   c                "    U R                  5       $ )a  Checks if the matrix is the upper-Hessenberg form.

The upper hessenberg matrix has zero entries
below the first subdiagonal.

Examples
========

>>> from sympy import Matrix
>>> a = Matrix([[1, 4, 2, 3], [3, 4, 1, 7], [0, 2, 3, 4], [0, 0, 1, 3]])
>>> a
Matrix([
[1, 4, 2, 3],
[3, 4, 1, 7],
[0, 2, 3, 4],
[0, 0, 1, 3]])
>>> a.is_upper_hessenberg
True

See Also
========

is_lower_hessenberg
is_upper
)r  rw   s    rM   is_upper_hessenberg$MatrixProperties.is_upper_hessenbergr  rW  rO   c                V   ^  [        U 4S j[        ST R                  5       5       5      $ )a  Check if matrix is an upper triangular matrix. True can be returned
even if the matrix is not square.

Examples
========

>>> from sympy import Matrix
>>> m = Matrix(2, 2, [1, 0, 0, 1])
>>> m
Matrix([
[1, 0],
[0, 1]])
>>> m.is_upper
True

>>> m = Matrix(4, 3, [5, 1, 9, 0, 4, 6, 0, 0, 5, 0, 0, 0])
>>> m
Matrix([
[5, 1, 9],
[0, 4, 6],
[0, 0, 5],
[0, 0, 0]])
>>> m.is_upper
True

>>> m = Matrix(2, 3, [4, 2, 5, 6, 1, 1])
>>> m
Matrix([
[4, 2, 5],
[6, 1, 1]])
>>> m.is_upper
False

See Also
========

is_lower
is_diagonal
is_upper_hessenberg
c              3     >#    U  H<  n[        [        UTR                  5      5        H  nTX4   R                  v   M     M>     g 7fr   r  r  s      rM   r   ,MatrixProperties.is_upper.<locals>.<genexpr>  sA      6/q!#a"34q :%%4 &/s   AAr   r  rw   s   `rM   is_upperMatrixProperties.is_upper  s+    T  6!!TYY/6 6 	6rO   c                "    U R                  5       $ )at  Checks if a matrix is a zero matrix.

A matrix is zero if every element is zero.  A matrix need not be square
to be considered zero.  The empty matrix is zero by the principle of
vacuous truth.  For a matrix that may or may not be zero (e.g.
contains a symbol), this will be None

Examples
========

>>> from sympy import Matrix, zeros
>>> from sympy.abc import x
>>> a = Matrix([[0, 0], [0, 0]])
>>> b = zeros(3, 4)
>>> c = Matrix([[0, 1], [0, 0]])
>>> d = Matrix([])
>>> e = Matrix([[x, 0], [0, 0]])
>>> a.is_zero_matrix
True
>>> b.is_zero_matrix
True
>>> c.is_zero_matrix
False
>>> d.is_zero_matrix
True
>>> e.is_zero_matrix
)r  rw   s    rM   r  MatrixProperties.is_zero_matrix  s    : ((**rO   c                "    U R                  5       $ )zReturn non-zero values of self.)r  rw   s    rM   valuesMatrixProperties.values  s      ""rO   rP   N)returnr   T))rB   rQ   rR   rS   r~   r  r  r  r  r  r  r  r  r  r  r  r  r  r  r  r  r  r   r  r  r2  r5  rD  rK  rN  rR  rU  rY  r8  r^  r9  re  rj  r  ro  rT   rP   rO   rM   r+   r+   /  s`   0A3
"+5
5
 "<
2BE(2 ) ))2E6N)(V /; /;b /; /;b 9 9B ( (
 0 08 *% *%X & &.(>1@ 0 08 +6 +6Z + +<#rO   r+   c                  2   \ rS rSrSrS rS rS rS rS r	S r
S	 rS
 rS rS rS'S jrS rS rS(S jr  S)S jr\S 5       rS*S jrS+S jrS+S jrS'S jrS,S jrS-S jrS rS rS rS r\S 5       r \S 5       r!S  r"S! r#S" r$S# r%S.S$ jr&S.S% jr'S&r(g)/r,   i  z]Provides basic matrix shape and elementwise
operations.  Should not be instantiated directly.c                >    U R                  5       R                  5       $ r   )	transposer  rw   s    rM   _eval_adjointMatrixOperations._eval_adjoint  s    ~~))++rO   c           
         U R                  U R                  U R                  U  Vs/ s H
  o!" U5      PM     sn5      nU$ s  snf r   r   )rm   fr  outs       rM   _eval_applyfunc MatrixOperations._eval_applyfunc  s:    ii		499T.BTqtT.BC
 /Cs   A c                V    U R                  [        5      U R                  [        5      4$ r   )	applyfuncr   r   rw   s    rM   _eval_as_real_imag#MatrixOperations._eval_as_real_imag  s    r"DNN2$677rO   c                &    U R                  S 5      $ )Nc                "    U R                  5       $ r   r  r-  s    rM   r  2MatrixOperations._eval_conjugate.<locals>.<lambda>  s
    rO   r~  rw   s    rM   _eval_conjugate MatrixOperations._eval_conjugate  s    ~~566rO   c                x   ^ ^ [        U5      mUU 4S jnT R                  T R                  T R                  U5      $ )Nc                   > TU TU   4   $ r   rP   r   r   mappingrm   s     rM   r   2MatrixOperations._eval_permute_cols.<locals>.entry  s    71:&&rO   r   rg   rZ   r[   rm   permr   r  s   `  @rM   _eval_permute_cols#MatrixOperations._eval_permute_cols  .    t*	' yyDIIu55rO   c                x   ^ ^ [        U5      mUU 4S jnT R                  T R                  T R                  U5      $ )Nc                   > TTU    U4   $ r   rP   r  s     rM   r   2MatrixOperations._eval_permute_rows.<locals>.entry  s    
A&&rO   r  r  s   `  @rM   _eval_permute_rows#MatrixOperations._eval_permute_rows  r  rO   c                T   ^  [        U 4S j[        T R                  5       5       5      $ )Nc              3  0   >#    U  H  nTX4   v   M     g 7fr   rP   r  s     rM   r   /MatrixOperations._eval_trace.<locals>.<genexpr>  s     8'7!4:'7r  )sumr   rZ   rw   s   `rM   _eval_traceMatrixOperations._eval_trace  s    8uTYY'7888rO   c                Z   ^  T R                  T R                  T R                  U 4S j5      $ )Nc                   > TX4   $ r   rP   r   r   rm   s     rM   r  2MatrixOperations._eval_transpose.<locals>.<lambda>  s    DJrO   )rg   r[   rZ   rw   s   `rM   _eval_transpose MatrixOperations._eval_transpose  s    yyDII/FGGrO   c                "    U R                  5       $ )z-Conjugate transpose or Hermitian conjugation.)rv  rw   s    rM   adjointMatrixOperations.adjoint
  s    !!##rO   c                Z    [        U5      (       d  [        S5      eU R                  U5      $ )zApply a function to each element of the matrix.

Examples
========

>>> from sympy import Matrix
>>> m = Matrix(2, 2, lambda i, j: i*2+j)
>>> m
Matrix([
[0, 1],
[2, 3]])
>>> m.applyfunc(lambda i: 2*i)
Matrix([
[0, 2],
[4, 6]])

z`f` must be callable.)callabler   r{  )rm   ry  s     rM   r~  MatrixOperations.applyfunc  s*    $ {{344##A&&rO   c                "    U R                  5       $ )z@Returns a tuple containing the (real, imaginary) part of matrix.)r  )rm   deephintss      rM   as_real_imagMatrixOperations.as_real_imag%  s     &&((rO   c                "    U R                  5       $ )a  Return the by-element conjugation.

Examples
========

>>> from sympy import SparseMatrix, I
>>> a = SparseMatrix(((1, 2 + I), (3, 4), (I, -I)))
>>> a
Matrix([
[1, 2 + I],
[3,     4],
[I,    -I]])
>>> a.C
Matrix([
[ 1, 2 - I],
[ 3,     4],
[-I,     I]])

See Also
========

transpose: Matrix transposition
H: Hermite conjugation
sympy.matrices.matrixbase.MatrixBase.D: Dirac conjugation
)r  rw   s    rM   r  MatrixOperations.conjugate*  s    4 ##%%rO   c                .   ^ U R                  U4S j5      $ )Nc                (   > U R                   " S0 TD6$ NrP   )doit)r  r  s    rM   r  'MatrixOperations.doit.<locals>.<lambda>G  s    rO   r  )rm   r  s    `rM   r  MatrixOperations.doitF  s    ~~788rO   Nc                >   ^^ X#XEXgS.mU R                  UU4S j5      $ )&Apply evalf() to each element of self.)subsmaxnchoprv  quadverbosec                *   > U R                   " T40 TD6$ r   evalf)r   r   optionss    rM   r  (MatrixOperations.evalf.<locals>.<lambda>M  s    (=W(=rO   r  )	rm   r   r  r  r  rv  r  r  r  s	    `      @rM   r  MatrixOperations.evalfI  s"    D0~~=>>rO   c	                N   ^^^^^^^^^	 U R                  UUU	UUUUUU4	S j5      $ )zApply core.function.expand to each entry of the matrix.

Examples
========

>>> from sympy.abc import x
>>> from sympy import Matrix
>>> Matrix(1, 1, [x*(x+1)])
Matrix([[x*(x + 1)]])
>>> _.expand()
Matrix([[x**2 + x]])

c           
     8   >	 U R                   " TTTT	TTTT40 TD6$ r   )expand)
r  basicr  r  logmodulusmulmultinomial
power_base	power_exps
    rM   r  )MatrixOperations.expand.<locals>.<lambda>^  s'    ':y#sK))rO   r  )
rm   r  r  r  r  r  r  r  r  r  s
    `````````rM   r  MatrixOperations.expandO  s!     ~~    	rO   c                .    U R                   R                  $ )a6  Return Hermite conjugate.

Examples
========

>>> from sympy import Matrix, I
>>> m = Matrix((0, 1 + I, 2, 3))
>>> m
Matrix([
[    0],
[1 + I],
[    2],
[    3]])
>>> m.H
Matrix([[0, 1 - I, 2, 3]])

See Also
========

conjugate: By-element conjugation
sympy.matrices.matrixbase.MatrixBase.D: Dirac conjugation
)ro  Crw   s    rM   HMatrixOperations.Hb  s    0 vvxxrO   c                  ^ SSK Jn  US:X  a  SnUS:X  a  SnUS:X  a  SnUS	;  a  [        S
R                  U5      5      eUS;  a  [        SR                  U5      5      e[	        X[
        45      (       d  [        SR                  U5      5      eUS:X  a  U R                  OU R                  m[        U4S j[        [        U5      5       5       5      (       d  [        S5      eU(       aM  [	        X5      (       d=  [	        US   [
        5      (       a%  US:X  a  [        [        U5      5      nU" UTS-   S9nO
U" UTS-   S9nUS:X  a  U R                  U5      $ US:X  a  U R                  U5      $ g)a	  Permute the rows or columns of a matrix by the given list of
swaps.

Parameters
==========

perm : Permutation, list, or list of lists
    A representation for the permutation.

    If it is ``Permutation``, it is used directly with some
    resizing with respect to the matrix size.

    If it is specified as list of lists,
    (e.g., ``[[0, 1], [0, 2]]``), then the permutation is formed
    from applying the product of cycles. The direction how the
    cyclic product is applied is described in below.

    If it is specified as a list, the list should represent
    an array form of a permutation. (e.g., ``[1, 2, 0]``) which
    would would form the swapping function
    `0 \mapsto 1, 1 \mapsto 2, 2\mapsto 0`.

orientation : 'rows', 'cols'
    A flag to control whether to permute the rows or the columns

direction : 'forward', 'backward'
    A flag to control whether to apply the permutations from
    the start of the list first, or from the back of the list
    first.

    For example, if the permutation specification is
    ``[[0, 1], [0, 2]]``,

    If the flag is set to ``'forward'``, the cycle would be
    formed as `0 \mapsto 2, 2 \mapsto 1, 1 \mapsto 0`.

    If the flag is set to ``'backward'``, the cycle would be
    formed as `0 \mapsto 1, 1 \mapsto 2, 2 \mapsto 0`.

    If the argument ``perm`` is not in a form of list of lists,
    this flag takes no effect.

Examples
========

>>> from sympy import eye
>>> M = eye(3)
>>> M.permute([[0, 1], [0, 2]], orientation='rows', direction='forward')
Matrix([
[0, 0, 1],
[1, 0, 0],
[0, 1, 0]])

>>> from sympy import eye
>>> M = eye(3)
>>> M.permute([[0, 1], [0, 2]], orientation='rows', direction='backward')
Matrix([
[0, 1, 0],
[0, 0, 1],
[1, 0, 0]])

Notes
=====

If a bijective function
`\sigma : \mathbb{N}_0 \rightarrow \mathbb{N}_0` denotes the
permutation.

If the matrix `A` is the matrix to permute, represented as
a horizontal or a vertical stack of vectors:

.. math::
    A =
    \begin{bmatrix}
    a_0 \\ a_1 \\ \vdots \\ a_{n-1}
    \end{bmatrix} =
    \begin{bmatrix}
    \alpha_0 & \alpha_1 & \cdots & \alpha_{n-1}
    \end{bmatrix}

If the matrix `B` is the result, the permutation of matrix rows
is defined as:

.. math::
    B := \begin{bmatrix}
    a_{\sigma(0)} \\ a_{\sigma(1)} \\ \vdots \\ a_{\sigma(n-1)}
    \end{bmatrix}

And the permutation of matrix columns is defined as:

.. math::
    B := \begin{bmatrix}
    \alpha_{\sigma(0)} & \alpha_{\sigma(1)} &
    \cdots & \alpha_{\sigma(n-1)}
    \end{bmatrix}
r   )Permutationforwardsforward	backwardsbackwardcolumnsr[   )r  r  z?direction='{}' is an invalid kwarg. Try 'forward' or 'backward'r%  z:orientation='{}' is an invalid kwarg. Try 'rows' or 'cols'zB{} must be a list, a list of lists, or a SymPy permutation object.rZ   c              3  N   >#    U  H  nS Us=:*  =(       a    T:*  Os  v   M     g7f)r   NrP   )r   r#  	max_indexs     rM   r   +MatrixOperations.permute.<locals>.<genexpr>  s#     D0C11&&Y&&0Cs   "%z`swap` indices out of range.r   )r[  N)sympy.combinatoricsr  r   r   rF   r   r  rZ   r[   r   r   r   r   reversedr  r  )rm   r  orientation	directionr  r  s        @rM   permuteMatrixOperations.permute|  sv   B 	4 
"!I#"I)# K33 ::@&:KM M.. 3396+3FH H $h 788117? ?
 "-!6DIIDII	DT
0CDDD;<<
455tAw))I%HTN+t)A+6Dt)A+6D& **400& **400 !rO   c                $    U R                  USUS9$ )zgAlias for
``self.permute(swaps, orientation='cols', direction=direction)``

See Also
========

permute
r[   r  r  r  rm   swapsr  s      rM   permute_colsMatrixOperations.permute_cols	       ||Ev|KKrO   c                $    U R                  USUS9$ )zgAlias for
``self.permute(swaps, orientation='rows', direction=direction)``

See Also
========

permute
rZ   r  r  r  s      rM   permute_rowsMatrixOperations.permute_rows	  r  rO   c                .   ^ U R                  U4S j5      $ )aJ  Apply refine to each element of the matrix.

Examples
========

>>> from sympy import Symbol, Matrix, Abs, sqrt, Q
>>> x = Symbol('x')
>>> Matrix([[Abs(x)**2, sqrt(x**2)],[sqrt(x**2), Abs(x)**2]])
Matrix([
[ Abs(x)**2, sqrt(x**2)],
[sqrt(x**2),  Abs(x)**2]])
>>> _.refine(Q.real(x))
Matrix([
[  x**2, Abs(x)],
[Abs(x),   x**2]])

c                   > [        U T5      $ r   r   )r  assumptionss    rM   r  )MatrixOperations.refine.<locals>.<lambda>-	  s    q+(>rO   r  )rm   r  s    `rM   r	   MatrixOperations.refine	  s    $ ~~>??rO   c                >   ^^^^^ U R                  UUUUU4S j5      $ )a;  Replaces Function F in Matrix entries with Function G.

Examples
========

>>> from sympy import symbols, Function, Matrix
>>> F, G = symbols('F, G', cls=Function)
>>> M = Matrix(2, 2, lambda i, j: F(i+j)) ; M
Matrix([
[F(0), F(1)],
[F(1), F(2)]])
>>> N = M.replace(F,G)
>>> N
Matrix([
[G(0), G(1)],
[G(1), G(2)]])
c                *   > U R                  TTTTTS9$ )N)mapsimultaneousexact)replace)r  FGr  r  r  s    rM   r  *MatrixOperations.replace.<locals>.<lambda>B	  s    aii1#LPUiVrO   r  )rm   r  r  r  r  r  s    `````rM   r  MatrixOperations.replace/	  s    $ ~~VVX 	XrO   c                    US-  nUS:X  a  U $ US:X  a  U SSS2SS24   R                   $ US:X  a  U SSS2SSS24   $ US:X  a  U SS2SSS24   R                   $ g)a  Rotates Matrix by 90 degrees

Parameters
==========

k : int
    Specifies how many times the matrix is rotated by 90 degrees
    (clockwise when positive, counter-clockwise when negative).

Examples
========

>>> from sympy import Matrix, symbols
>>> A = Matrix(2, 2, symbols('a:d'))
>>> A
Matrix([
[a, b],
[c, d]])

Rotating the matrix clockwise one time:

>>> A.rot90(1)
Matrix([
[c, a],
[d, b]])

Rotating the matrix anticlockwise two times:

>>> A.rot90(-2)
Matrix([
[d, c],
[b, a]])
   r   r   Nr  rl  r;   )ro  )rm   r  mods      rM   rot90MatrixOperations.rot90D	  s{    F c!8K!8"b>###!8"dd
##!8DbD>### rO   c                .   ^ U R                  U4S j5      $ )a  Apply simplify to each element of the matrix.

Examples
========

>>> from sympy.abc import x, y
>>> from sympy import SparseMatrix, sin, cos
>>> SparseMatrix(1, 1, [x*sin(y)**2 + x*cos(y)**2])
Matrix([[x*sin(y)**2 + x*cos(y)**2]])
>>> _.simplify()
Matrix([[x]])
c                (   > U R                   " S0 TD6$ r  )r1  )r  r_   s    rM   r  +MatrixOperations.simplify.<locals>.<lambda>~	  s    

(<V(<rO   r  rm   r_   s    `rM   r1  MatrixOperations.simplifyq	  s     ~~<==rO   c                   ^^ [        T5      S:X  aS  [        TS   [        [        45      (       d5  [	        TS   5      (       a"  [        TS   5      (       d  [        TS   5      4mU R                  UU4S j5      $ )a  Return a new matrix with subs applied to each entry.

Examples
========

>>> from sympy.abc import x, y
>>> from sympy import SparseMatrix, Matrix
>>> SparseMatrix(1, 1, [x])
Matrix([[x]])
>>> _.subs(x, y)
Matrix([[y]])
>>> Matrix(_).subs(y, x)
Matrix([[x]])
r   r   c                (   > U R                   " T0 TD6$ r   )r  )r  rf   r_   s    rM   r  'MatrixOperations.subs.<locals>.<lambda>	  s    (?(?rO   )r   rF   dictr  iterr   r   r~  rm   rf   r_   s    ``rM   r  MatrixOperations.subs	  sc      t9>:d1gc{#C#CTRSW^ijnopjq^r^raM#D~~?@@rO   c                j    U R                   U R                  :w  a
  [        5       eU R                  5       $ )z
Returns the trace of a square matrix i.e. the sum of the
diagonal elements.

Examples
========

>>> from sympy import Matrix
>>> A = Matrix(2, 2, [1, 2, 3, 4])
>>> A.trace()
5

)rZ   r[   r&   r  rw   s    rM   traceMatrixOperations.trace	  s,     99		!&((!!rO   c                "    U R                  5       $ )a  
Returns the transpose of the matrix.

Examples
========

>>> from sympy import Matrix
>>> A = Matrix(2, 2, [1, 2, 3, 4])
>>> A.transpose()
Matrix([
[1, 3],
[2, 4]])

>>> from sympy import Matrix, I
>>> m=Matrix(((1, 2+I), (3, 4)))
>>> m
Matrix([
[1, 2 + I],
[3,     4]])
>>> m.transpose()
Matrix([
[    1, 3],
[2 + I, 4]])
>>> m.T == m.transpose()
True

See Also
========

conjugate: By-element conjugation

)r  rw   s    rM   ru  MatrixOperations.transpose	  s    B ##%%rO   c                "    U R                  5       $ )zMatrix transposition)ru  rw   s    rM   ro  MatrixOperations.T	       ~~rO   c                "    U R                  5       $ )zBy-element conjugationr  rw   s    rM   r  MatrixOperations.C	  r  rO   c                &    U R                   " U0 UD6$ )r  r  r  s      rM   r   MatrixOperations.n	  s    zz4*6**rO   c                .   ^ U R                  U4S j5      $ )a  Return a new matrix with xreplace applied to each entry.

Examples
========

>>> from sympy.abc import x, y
>>> from sympy import SparseMatrix, Matrix
>>> SparseMatrix(1, 1, [x])
Matrix([[x]])
>>> _.xreplace({x: y})
Matrix([[y]])
>>> Matrix(_).xreplace({y: x})
Matrix([[x]])
c                &   > U R                  T5      $ r   )xreplace)r  rules    rM   r  +MatrixOperations.xreplace.<locals>.<lambda>	  s    

4(8rO   r  )rm   r  s    `rM   r  MatrixOperations.xreplace	  s     ~~899rO   c                0    [         R                  " U 40 UD6$ r   )r,   r1  r  s     rM   _eval_simplifyMatrixOperations._eval_simplify	  s      ((888rO   c                >   ^^ SSK Jm  U R                  UU4S j5      $ )Nr   )trigsimpc                   > T" U 40 TD6$ r   rP   )r  optsr$  s    rM   r  1MatrixOperations._eval_trigsimp.<locals>.<lambda>	  s    (;d(;rO   )sympy.simplify.trigsimpr$  r~  )rm   r&  r$  s    `@rM   _eval_trigsimpMatrixOperations._eval_trigsimp	  s    4~~;<<rO   c                b   ^ ^ UU 4S jnT R                  T R                  T R                  U5      $ )a  Return the elements on and above the kth diagonal of a matrix.
If k is not specified then simply returns upper-triangular portion
of a matrix

Examples
========

>>> from sympy import ones
>>> A = ones(4)
>>> A.upper_triangular()
Matrix([
[1, 1, 1, 1],
[0, 1, 1, 1],
[0, 0, 1, 1],
[0, 0, 0, 1]])

>>> A.upper_triangular(2)
Matrix([
[0, 0, 1, 1],
[0, 0, 0, 1],
[0, 0, 0, 0],
[0, 0, 0, 0]])

>>> A.upper_triangular(-1)
Matrix([
[1, 1, 1, 1],
[1, 1, 1, 1],
[0, 1, 1, 1],
[0, 0, 1, 1]])

c                :   > U T-   U::  a  TX4   $ TR                   $ r   r   r   r   r  rm   s     rM   r   0MatrixOperations.upper_triangular.<locals>.entry
  "    !"Q!4:::rO   r   rm   r  r   s   `` rM   upper_triangular!MatrixOperations.upper_triangular	  &    B	; yyDIIu55rO   c                b   ^ ^ UU 4S jnT R                  T R                  T R                  U5      $ )a  Return the elements on and below the kth diagonal of a matrix.
If k is not specified then simply returns lower-triangular portion
of a matrix

Examples
========

>>> from sympy import ones
>>> A = ones(4)
>>> A.lower_triangular()
Matrix([
[1, 0, 0, 0],
[1, 1, 0, 0],
[1, 1, 1, 0],
[1, 1, 1, 1]])

>>> A.lower_triangular(-2)
Matrix([
[0, 0, 0, 0],
[0, 0, 0, 0],
[1, 0, 0, 0],
[1, 1, 0, 0]])

>>> A.lower_triangular(1)
Matrix([
[1, 1, 0, 0],
[1, 1, 1, 0],
[1, 1, 1, 1],
[1, 1, 1, 1]])

c                :   > U T-   U:  a  TX4   $ TR                   $ r   r-  r.  s     rM   r   0MatrixOperations.lower_triangular.<locals>.entry:
  r0  rO   r   r1  s   `` rM   lower_triangular!MatrixOperations.lower_triangular
  r4  rO   rP   rr  )   Nd   FFNF)TNTTTTTT)rZ   r  )r  )FTN)r   r@  ))rB   rQ   rR   rS   r~   rv  r{  r  r  r  r  r  r  r  r~  r  r  r  r  r  r   r  r  r  r  r	   r  r   r1  r  r  ru  ro  r  r   r  r!  r)  r2  r8  rT   rP   rO   rM   r,   r,     s    9,87669H$'.)
&89? JN;?&  2G1R	L	L@(X*+$Z>A*"$!&F        +:"9
=$6N$6rO   r,   c                     \ rS rSrSrSrS rS rS rS r	S r
S	 rS
 rS,S jrS rS rS rS r\" S5      S 5       r\" S5      S 5       r\" S5      S 5       rS r\" S5      S 5       rS,S jrS rS r\" S5      S 5       rS,S jr\" S 5      S! 5       r\" S"5      S# 5       r\" S$5      S% 5       rS,S& jr \" S'5      S( 5       r!\" S)5      S* 5       r"S+r#g)-r-   iA
  zQProvides basic matrix arithmetic operations.
Should not be instantiated directly.gQ$@c                Z   ^  T R                  T R                  T R                  U 4S j5      $ )Nc                "   > [        TX4   5      $ r   )r   r  s     rM   r  ,MatrixArithmetic._eval_Abs.<locals>.<lambda>H
  s    CQT
OrO   r   rw   s   `rM   	_eval_AbsMatrixArithmetic._eval_AbsG
  s    yyDII/KLLrO   c                ^   ^ ^ T R                  T R                  T R                  UU 4S j5      $ )Nc                   > TX4   TX4   -   $ r   rP   r   r   rn   rm   s     rM   r  ,MatrixArithmetic._eval_add.<locals>.<lambda>L
  s    d14j5;&>rO   r   rl   s   ``rM   	_eval_addMatrixArithmetic._eval_addJ
  s%    yyDII>@ 	@rO   c                b   ^ ^ UU 4S jnT R                  T R                  TR                  U5      $ )Nc                   > [        TR                  5       Vs/ s H  nTX4   TX!4   -  PM     nn [        U6 $ s  snf ! [        [        4 a    [        S U5      s $ f = f)Nc                
    X-   $ r   rP   )r  bs     rM   r  BMatrixArithmetic._eval_matrix_mul.<locals>.entry.<locals>.<lambda>W
  s    15rO   )r   r[   r   r   r
   r   )r   r   r  r5  rn   rm   s       rM   r   0MatrixArithmetic._eval_matrix_mul.<locals>.entryO
  sn    16tyy1AB1AA49U13Z'1ACB7Cy  C |, 7 0#66	7s   ;A   A A r   rm   rn   r   s   `` rM   _eval_matrix_mul!MatrixArithmetic._eval_matrix_mulN
  s%    	7 yyEJJ66rO   c                ^   ^ ^ T R                  T R                  T R                  UU 4S j5      $ )Nc                   > TX4   TX4   -  $ r   rP   rD  s     rM   r  ?MatrixArithmetic._eval_matrix_mul_elementwise.<locals>.<lambda>\
  s    DIeACj<PrO   r   rl   s   ``rM   _eval_matrix_mul_elementwise-MatrixArithmetic._eval_matrix_mul_elementwise[
  s    yyDII/PQQrO   c                b   ^ ^ UU 4S jnT R                  TR                  T R                  U5      $ )Nc                ^   >^ ^ [        U UUU4S j[        TR                  5       5       5      $ )Nc              3  B   >#    U  H  nTTU4   TUT4   -  v   M     g 7fr   rP   )r   r  r   r   rn   rm   s     rM   r   DMatrixArithmetic._eval_matrix_rmul.<locals>.entry.<locals>.<genexpr>`
  s(     G5FuQqSz$qs)+5Fs   )r  r   r[   rD  s   ``rM   r   1MatrixArithmetic._eval_matrix_rmul.<locals>.entry_
  s    GU5::5FGGGrO   r   rN  s   `` rM   _eval_matrix_rmul"MatrixArithmetic._eval_matrix_rmul^
  s$    	HyyTYY66rO   c                    US:X  a  U $ US-  S:X  a  X R                  US-
  5      p2OU R                  US-  5      =p#UR                  U5      $ )Nr   rl  )_eval_pow_by_recursionmultiply)rm   numr  rK  s       rM   r^  'MatrixArithmetic._eval_pow_by_recursionc
  sR    !8K7a<44S1W=q//q99Azz!}rO   c                   SSK Jn  U R                  S   nU R                  5       nU* R	                  5       SS  nU" XQ5      nU R                  U5      nU R                  U5      n[        U5       H  nXuU   U-  -  nX`-  nM     U$ )Nr   )linrec_coeffsr   )sympy.discrete.recurrencesrc  r|   charpolyr  r  r  r   )	rm   exprc  r   pr  new_matansr   s	            rM   _eval_pow_by_cayley$MatrixArithmetic._eval_pow_by_cayleyn
  s    <jjmMMO""12&v+((3-jjosA!9W$$COG  
rO   Nc                   Uc  S/[        U 5      -  nUS:X  a  U $ US-  S:X  a  X R                  US-
  US9pCOU R                  US-  US9=p4UR                  USS9n[        U5      nS /U-  n[        U5       H'  nX(   (       a  [	        XX   SS9u  Xx'   X('   M!  XX   Xx'   M)     UR                  UR                  UR                  U5      $ )NTr   rl  )prevsimpF)dotprodsimp)withsimp)r   "_eval_pow_by_recursion_dotprodsimpr_  r   r   rg   rZ   r[   )	rm   r`  rm  r  rK  r  lenmelemsr   s	            rM   rp  3MatrixArithmetic._eval_pow_by_recursion_dotprodsimp~
  s    vc$i'H!8K7a<@@q% A 'q ;;C1H% < ' 'A 

1%
0AttA{(4QTD(I%(+4	  vvaffaffe,,rO   c                ^   ^ ^ T R                  T R                  T R                  UU 4S j5      $ )Nc                   > TX4   T-  $ r   rP   rD  s     rM   r  3MatrixArithmetic._eval_scalar_mul.<locals>.<lambda>
  s    DIeOrO   r   rl   s   ``rM   _eval_scalar_mul!MatrixArithmetic._eval_scalar_mul
      yyDII/KLLrO   c                ^   ^ ^ T R                  T R                  T R                  UU 4S j5      $ )Nc                   > TTX4   -  $ r   rP   rD  s     rM   r  4MatrixArithmetic._eval_scalar_rmul.<locals>.<lambda>
  s    E$qs)OrO   r   rl   s   ``rM   _eval_scalar_rmul"MatrixArithmetic._eval_scalar_rmul
  ry  rO   c                ^   ^ ^ T R                  T R                  T R                  UU 4S j5      $ )Nc                $   > [        TX4   T5      $ r   r   rD  s     rM   r  ,MatrixArithmetic._eval_Mod.<locals>.<lambda>
  s    CQT
E<RrO   r   rl   s   ``rM   	_eval_ModMatrixArithmetic._eval_Mod
  s    yyDII/RSSrO   c                "    U R                  5       $ )z5Returns a new matrix with entry-wise absolute values.)r@  rw   s    rM   __abs__MatrixArithmetic.__abs__
  s    ~~rO   __radd__c                
   [        U[        5      (       a  [        $ [        U5      n[	        US5      (       aA  U R
                  UR
                  :w  a'  [        SU R
                  < SUR
                  < 35      e[        USS5      (       a.  Xp2UR                  [        X#5      :w  a  X#p#UR                  U5      $ [        USS5      (       a  [        R                  X5      $ [        S[        U 5      < S[        U5      < 35      e)	z?Return self + other, raising ShapeError if shapes do not match.r|   Matrix size mismatch: z + 	is_MatrixFis_MatrixLikezcannot add z and )rF   r"   NotImplemented
_matrixifyr  r|   r%   getattrrL   r   rF  r-   r   r   )rm   rn   r  rK  s       rM   __add__MatrixArithmetic.__add__
  s     eY''!!5! 5'""zzU[[( JJ"- . . 5+u--q{{gam+1;;q>!5/511#--d::$t*d5kJKKrO   __rtruediv__c                $    X R                   U-  -  $ r   ra  rl   s     rM   __truediv__MatrixArithmetic.__truediv__
  s    xx%'((rO   __rmatmul__c                    [        U5      n[        USS5      (       d  [        USS5      (       d  [        $ U R                  U5      $ Nr  Fr  )r  r  r  __mul__rl   s     rM   
__matmul__MatrixArithmetic.__matmul__
  s?    5!uk511'%Z_:`:`!!||E""rO   c                .   ^ U R                  U4S j5      $ )Nc                   > U T-  $ r   rP   )r  rn   s    rM   r  *MatrixArithmetic.__mod__.<locals>.<lambda>
  s	    E	rO   r  rl   s    `rM   __mod__MatrixArithmetic.__mod__
  s    ~~122rO   __rmul__c                $    U R                  U5      $ )a  Return self*other where other is either a scalar or a matrix
of compatible dimensions.

Examples
========

>>> from sympy import Matrix
>>> A = Matrix([[1, 2, 3], [4, 5, 6]])
>>> 2*A == A*2 == Matrix([[2, 4, 6], [8, 10, 12]])
True
>>> B = Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> A*B
Matrix([
[30, 36, 42],
[66, 81, 96]])
>>> B*A
Traceback (most recent call last):
...
ShapeError: Matrices size mismatch.
>>>

See Also
========

matrix_multiply_elementwise
)r_  rl   s     rM   r  MatrixArithmetic.__mul__
  s    : }}U##rO   c           
        [        SU5      n[        U5      n[        US5      (       a  [        UR                  5      S:X  al  [        USS5      (       d  [        USS5      (       aH  U R                  S   UR                  S   :w  a(  [        S	U R                  < S
UR                  < S35      e[        USS5      (       a[  U R                  U5      nU(       aA  UR                  UR                  UR                  U Vs/ s H  n[        U5      PM     sn5      $ U$ [        USS5      (       a  [        R                  X5      $ [        U[        5      (       d   U R                  U5      $ ["        $ s  snf ! [          a     ["        $ f = f)a$  Same as __mul__() but with optional simplification.

Parameters
==========

dotprodsimp : bool, optional
    Specifies whether intermediate term algebraic simplification is used
    during matrix multiplications to control expression blowup and thus
    speed up calculation. Default is off.
Fr|   rl  r  Tr  r   r   r  z * .)r#   r  r  r   r|   r  r%   rO  rg   rZ   r[   r   r-   rF   r   rw  r   r  rm   rn   rn  	isimpboolr  es         rM   r_  MatrixArithmetic.multiply
  sT    0{C	5! E7##EKK(8A(=UK..UOT22zz!}A. JJ"- . . 5+u--%%e,Avvaffaff.J1|A.JKKH 5/511#44TAA %**,,U33  /K  s   =E/E4 4
FFc                    U R                   UR                   :w  a/  [        SR                  U R                   UR                   5      5      eU R                  U5      $ )a{  Return the Hadamard product (elementwise product) of A and B

Examples
========

>>> from sympy import Matrix
>>> A = Matrix([[0, 1, 2], [3, 4, 5]])
>>> B = Matrix([[1, 10, 100], [100, 10, 1]])
>>> A.multiply_elementwise(B)
Matrix([
[  0, 10, 200],
[300, 40,   5]])

See Also
========

sympy.matrices.matrixbase.MatrixBase.cross
sympy.matrices.matrixbase.MatrixBase.dot
multiply
z!Matrix shapes must agree {} != {})r|   r%   r   rT  rl   s     rM   multiply_elementwise%MatrixArithmetic.multiply_elementwise  sI    * ::$@GG

TYT_T_`aa0077rO   c                $    U R                  S5      $ )Nr  )rw  rw   s    rM   __neg__MatrixArithmetic.__neg__3  s    $$R((rO   __rpow__c                $    U R                  U5      $ )z$Return self**exp a scalar or symbol.)pow)rm   rf  s     rM   __pow__MatrixArithmetic.__pow__6  s     xx}rO   c                  ^^ Ub  US;  a  [        S5      eU R                  U R                  :w  a
  [        5       eU m[	        TSS5      n[        T5      mTR                  (       a(  TR                  TR                  TR                  S 5      $ TS:X  a  T$ [	        TSS5      nUb8  U" 5       (       a,  TR                  TR                  TR                  UU4S j5      $ TR                  (       aK  TS-  S	:X  aB  TR                  S:X  a  TR                  TS	   T-  //5      $ TS	:  a  T* mTR                  5       mUS
:X  a	   U" T5      $ US:X  a6  TR                  (       a	  TS-  S	:w  a  [        S5      eTR                  T5      $ US:X  a6  TR                  (       a	  TS-  S	:w  a  [        S5      eTR                  T5      $ US:X  a6  TR                  (       a	  TS-  S	:w  a  [        S5      eTR                  T5      $ Uc  TR                  (       a  TS-  S	:X  a  TR                  (       a  [!        T5      mTR                  S:X  a  TS:  a  U" T5      $ [#        SS5      (       a  TR                  T5      $ TS:  a  TR                  T5      $ TR                  T5      $ U(       a	   U" T5      $ S	SKJn  U" TT5      $ ! [         a
    US
:X  a  e  N2f = f! [$         a"    TR&                  SL d  TR(                  SL a  e  NQf = f)as  Return self**exp a scalar or symbol.

Parameters
==========

method : multiply, mulsimp, jordan, cayley
    If multiply then it returns exponentiation using recursion.
    If jordan then Jordan form exponentiation will be used.
    If cayley then the exponentiation is done using Cayley-Hamilton
    theorem.
    If mulsimp then the exponentiation is done using recursion
    with dotprodsimp. This specifies whether intermediate term
    algebraic simplification is used during naive matrix power to
    control expression blowup and thus speed up calculation.
    If None, then it heuristically decides which method to use.

N)r_  mulsimpjordancayleyzNo such method_matrix_pow_by_jordan_blocksc                    [        X:H  5      $ r   )rY   r  s     rM   r  &MatrixArithmetic.pow.<locals>.<lambda>Y  s
    s16{rO   r   r5  c                $   > X:X  a	  TX4   T-  $ S$ )Nr   rP   )r   r   r  rf  s     rM   r  r  _  s    afqvs{7SRS7SrO   r   r  r  z.cayley method is only valid for integer powersr  z/mulsimp method is only valid for integer powersr_  z0multiply method is only valid for integer powersrl  i Ti'  F)MatPow)r   rZ   r[   r&   r  r   r  rg   	is_Numberinvr$   r  rj  rp  r^  is_Floatr   r#   r'   
is_integerr  sympy.matrices.expressionsr  )rm   rf  method
jordan_powr   r  r  s    `    @rM   r  MatrixArithmetic.pow=  s   & &0["[,--99		!&((Q >E
cl;;66!&&!&&*BCC!8H1mT2HJJ66!&&!&&*STT==S1W\vv{vv!c	{m,,QwdEEG X!#&
 x==C!GqL !QRR((--y ==C!GqL !RSS77<<z!==C!GqL !STT++C00^#'Q,||clvv{sV|!#&,T488;;C@@u,,S11//44!#& 	6a~Y  X% &F , 
 >>U*c.@.@E.I /Js$   J= &K =KK)L ?L r  c                
    X-   $ r   rP   rl   s     rM   r  MatrixArithmetic.__radd__  s
    |rO   r  c                    [        U5      n[        USS5      (       d  [        USS5      (       d  [        $ U R                  U5      $ r  )r  r  r  r  rl   s     rM   r  MatrixArithmetic.__rmatmul__  s?    5!uk511'%Z_:`:`!!}}U##rO   r  c                $    U R                  U5      $ r   )	rmultiplyrl   s     rM   r  MatrixArithmetic.__rmul__  s    ~~e$$rO   c           
        [        SU5      n[        U5      n[        US5      (       ah  [        UR                  5      S:X  aO  [        USS5      (       d  [        USS5      (       a+  U R                  S   UR                  S   :w  a  [        S	5      e[        USS5      (       a[  U R                  U5      nU(       aA  UR                  UR                  UR                  U Vs/ s H  n[        U5      PM     sn5      $ U$ [        USS5      (       a  [        R                  X5      $ [        U[        5      (       d   U R                  U5      $ ["        $ s  snf ! [          a     ["        $ f = f)
a%  Same as __rmul__() but with optional simplification.

Parameters
==========

dotprodsimp : bool, optional
    Specifies whether intermediate term algebraic simplification is used
    during matrix multiplications to control expression blowup and thus
    speed up calculation. Default is off.
Fr|   rl  r  Tr  r   r   zMatrix size mismatch.)r#   r  r  r   r|   r  r%   r[  rg   rZ   r[   r   r-   rF   r   r}  r   r  r  s         rM   r  MatrixArithmetic.rmultiply  s?    0{C	5! E7##EKK(8A(=UK..UOT22zz!}A. !899 5+u--&&u-Avvaffaff.J1|A.JKKH5/511#55dBB %**--e44  /K  s    E;E 
E)(E)__sub__c                    U * U-   $ r   rP   rm   r  s     rM   __rsub__MatrixArithmetic.__rsub__  s    {rO   r  c                    X* -   $ r   rP   r  s     rM   r  MatrixArithmetic.__sub__  s    r{rO   rP   r   )$rB   rQ   rR   rS   r~   _op_priorityr@  rF  rO  rT  r[  r^  rj  rp  rw  r}  r  r  r   r  r  r  r  r  r_  r  r  r  r  r  r  r  r  r  r  rT   rP   rO   rM   r-   r-   A
  sn   , LM@7R7
	 -4MMT  :&L 'L2 >*) +) =)# *#3 :&$ '$<)V84) :& '\| 9% & <($ )$ 9%% &%&P 9% & :& 'rO   r-   c                  (    \ rS rSr% SrSrS\S'   Srg)r.   i  zoAll common matrix operations including basic arithmetic, shaping,
and special matrices like `zeros`, and `eye`.Tr   	_diff_wrtrP   N)rB   rQ   rR   rS   r~   r  r   rT   rP   rO   rM   r.   r.     s    5ItrO   r.   c                      \ rS rSrSrSr\" \5      rSr	\
R                  r\
R                  rSrSr\S 5       rSS jrS	 rS
 rS rS r\S 5       rSrg)_MinimalMatrixi  a  Class providing the minimum functionality
for a matrix-like object and implementing every method
required for a `MatrixRequired`.  This class does not have everything
needed to become a full-fledged SymPy object, but it will satisfy the
requirements of anything inheriting from `MatrixRequired`.  If you wish
to make a specialized matrix type, make sure to implement these
methods and properties with the exception of `__init__` and `__repr__`
which are included for convenience.Tr;   Fc                    U " U0 UD6$ r   rP   re   s      rM   rg   _MinimalMatrix._new  s    D#F##rO   Nc           	       ^  [        U5      (       a5  [        U5       VVs/ s H  n[        U5        H
  oc" XV5      PM     M     nnnUc  Uc  Un[        USX45      u  p Uc  Uc  Un[        US   5      n[        U5      nU VVs/ s H  ow  H  oPM     M     nnn[        U 4S jU 5       5      T l        XsT l        T l	        T R                  b  T R                  c  [        S5      eg s  snnf s  snnf ! [        [
        4 a     Nlf = f)Nr|   r   c              3  F   >#    U  H  nTR                  U5      v   M     g 7fr   )r  )r   r  rm   s     rM   r   *_MinimalMatrix.__init__.<locals>.<genexpr>
  s     73aq))3r   z.Cannot initialize matrix with given parameters)r   r   r  r   r   r   r%  r   rZ   r[   rd   )	rm   rZ   r[   r   rK  r   r   lr  s	   `        rM   __init___MinimalMatrix.__init__  s   c??&+DkGk5;a3q9;9kCG<CKCS'D<8
	|s1v;Ds8D!-c1a111cC- 7377#	4999		 1%&VWW !2 H .I& 		s)   $C+ &C7 C1C7 1C7 7D
	D
c           	       ^ ^ U 4S jnU 4S jn[        U[        5      (       a  Uu  pE[        U[        5      (       d  [        U[        5      (       a  U" XE5      u  pE[        [	        T R
                  5      5      U   [        [	        T R                  5      5      U   snmUU 4S jU 5       nT R                  [        U5      [        T5      U Vs/ s H  nT R                  U   PM     sn5      $ U" XE5      nT R                  U   $ s  snf )Nc                  > [        U [        5      (       d  [        X S-   S5      n [        U R                  TR                  5      6 n [        U[        5      (       d  [        XS-   S5      n[        UR                  TR                  5      6 nX4$ )z|Ensure that row_slice and col_slice do not have
`None` in their arguments.  Any integers are converted
to slices of length 1r   N)rF   slicer   rZ   r[   )	row_slice	col_slicerm   s     rM   _normalize_slices5_MinimalMatrix.__getitem__.<locals>._normalize_slices  sz     i//!)]DA	y00;<Ii//!)]DA	y00;<I))rO   c                (   > U TR                   -  U-   $ )zLReturn the index in _mat corresponding
to the (i,j) position in the matrix. r   r  s     rM   _coord_to_index3_MinimalMatrix.__getitem__.<locals>._coord_to_index  s     tyy=1$$rO   c              3  Z   >#    U  H   nT  H  o!TR                   -  U-   v   M     M"     g 7fr   r   )r   r   r   r   rm   s      rM   r   -_MinimalMatrix.__getitem__.<locals>.<genexpr>,  s0      %h# DEtyy=1,# -hs   (+)
rF   r%  r  r   r   rZ   r[   rg   r   r   )	rm   rs   r  r  r   r   r   r   r   s	   `       @rM   rt   _MinimalMatrix.__getitem__  s    	*	%
 c5!!DA!U##z!U';'; ).%)%		*:%;A%>%)%		*:%;A%> #(%h %yyXH7>!?w!$((1+w!?A A
 "!'Cxx} "@s   Dc                     [        X5        U R                  UR                  :H  =(       a    [        U 5      [        U5      :H  $ ! [         a     gf = frQ  )r   r   r|   r   rl   s     rM   ro   _MinimalMatrix.__eq__6  sM    	D  JJ%++%C$t*U*C	E  		s   A 
AAc                4    U R                   U R                  -  $ r   r%  rw   s    rM   rx   _MinimalMatrix.__len__>  s    yy""rO   c                d    SR                  U R                  U R                  U R                  5      $ )Nz_MinimalMatrix({}, {}, {}))r   rZ   r[   r   rw   s    rM   __repr___MinimalMatrix.__repr__A  s(    +22499dii3788= 	=rO   c                2    U R                   U R                  4$ r   r%  rw   s    rM   r|   _MinimalMatrix.shapeE  s    		499%%rO   )r[   r   rZ   )NNF)rB   rQ   rR   rS   r~   r  staticmethodr   r  _class_priorityr   Zeror   OnerL  r  is_MatrixExprr   rg   r  rt   ro   rx   r  r   r|   rT   rP   rO   rM   r  r    s{    + MG$HO66D
%%CIM$ $X*%NE#= & &rO   r  c                       \ rS rSrS rS rSrg)_CastableMatrixiJ  c                    U $ r   rP   rw   s    rM   
as_mutable_CastableMatrix.as_mutableK      rO   c                    U $ r   rP   rw   s    rM   as_immutable_CastableMatrix.as_immutableN  r  rO   rP   N)rB   rQ   rR   rS   r   r  rT   rP   rO   rM   r  r  J  s    rO   r  c                  2    \ rS rSrSrSrSrS rS rS r	Sr
g	)
_MatrixWrapperiR  al  Wrapper class providing the minimum functionality for a matrix-like
object: .rows, .cols, .shape, indexability, and iterability. CommonMatrix
math operations should work on matrix-like objects. This one is intended for
matrix-like objects which use the same indexing format as SymPy with respect
to returning matrix elements instead of rows for non-tuple indexes.
FTc                :    Xl         X l        Uu  U l        U l        g r   )r   r|   rZ   r[   )rm   r   r|   s      rM   r  _MatrixWrapper.__init__]  s    
$	49rO   c                    [        U[        5      (       a$  [        U R                  R	                  U5      5      $ [        U R                  R	                  XR
                  -  XR                  -  45      5      $ r   )rF   r%  r   r   rt   rZ   r[   rr   s     rM   rt   _MatrixWrapper.__getitem__b  sU    c5!!488//455txx++SII-=sYY,OPQQrO   c                   ^^ U R                   mU R                  m[        UU4S j[        U R                  5       5       5      $ )Nc              3  h   >#    U  H'  n[        T5        H  n[        TX4   5      v   M     M)     g 7fr   )r   r   )r   r   r   r[   r   s      rM   r   *_MatrixWrapper.__iter__.<locals>.<genexpr>l  s/     V0@1%PT+QGCI&&+&0@s   /2)r   r[   r  r   rZ   )rm   r[   r   s    @@rM   __iter___MatrixWrapper.__iter__h  s/    hhyyVdii0@VVVrO   )r[   r   rZ   r|   N)rB   rQ   rR   rS   r~   r  r  r  rt   r  rT   rP   rO   rM   r  r  R  s$     IM%
RWrO   r  c                   [        U SS5      (       d  [        U SS5      (       a  U $ [        U SS5      (       d  [        U SS5      (       d  U $ Sn[        U S5      (       a&  [        U R                  5      S:X  a  U R                  nO:[        U S5      (       a)  [        U S	5      (       a  U R                  U R
                  4nU(       a  [        X5      $ U $ )
zIf `mat` is a Matrix or is matrix-like,
return a Matrix or MatrixWrapper object.  Otherwise
`mat` is passed through without modification.r  Fr  TNr|   rl  rZ   r[   )r  r  r   r|   rZ   r[   r  )r   r|   s     rM   r  r  o  s    
 sK''73+O+O
3T**gc?D.Q.Q
EsGsyy>QIIE	f		'#v"6"6388$c))JrO   Nc                    [        U [        5      (       d(  [        U SS5      nUb  U" 5       n O[        SU < S35      eUb%  U S:  a  X-  n U S:  a  X:  d  [        SU < S35      e[        U 5      $ )z>Return integer after making positive and validating against n.	__index__NzInvalid index a[r  r   zIndex out of range: a[)rF   rY   r  r   )r   r   jindexs      rM   r   r     sm    aK.Aa9::}q5FAQ15A?@@q6MrO   c                   [        U SS5      n[        USS5      nSX#4;  a2  U R                  UR                  :  a  U R                  $ UR                  $  SSKn[	        XR
                  5      (       a  UR                  $ [	        XR
                  5      (       a  U R                  $  [        SU R                  < SUR                  < 35      e! [         a     N3f = f)a  
Get the type of the result when combining matrices of different types.

Currently the strategy is that immutability is contagious.

Examples
========

>>> from sympy import Matrix, ImmutableMatrix
>>> from sympy.matrices.matrixbase import classof
>>> M = Matrix([[1, 2], [3, 4]]) # a Mutable Matrix
>>> IM = ImmutableMatrix([[1, 2], [3, 4]])
>>> classof(M, IM)
<class 'sympy.matrices.immutable.ImmutableDenseMatrix'>
r  Nr   zIncompatible classes r  )r  r  rL   numpyrF   ndarrayImportErrorr   )AB
priority_A
priority_Br  s        rM   r   r     s      -t4J-t4JJ++q000;;;; a'';;a'';; ( Q[[!++N
OO  s   C 
CCr   )Kr~   
__future__r   collectionsr   collections.abcr   inspectr   	functoolsr   sympy.assumptions.refiner	   
sympy.corer
   r   sympy.core.basicr   sympy.core.decoratorsr   sympy.core.logicr   r   sympy.core.numbersr   sympy.core.modr   sympy.core.singletonr   sympy.core.symbolr   sympy.core.sympifyr   $sympy.functions.elementary.complexesr   r   r   sympy.utilities.exceptionsr   	utilitiesr   r   sympy.polys.polytoolsr   sympy.utilities.iterablesr   r   sympy.utilities.miscr    r!   sympy.tensor.arrayr"   r#   
exceptionsr$   r%   r&   r'   r(   r]   r   r6   rE   r)   r*   r+   r,   r-   r.   r  r  r  r  r   r   rP   rO   rM   <module>r4     s  	 # # $   + ( ! 7 1 &  " $ & < < @ . & : 3 ( 2   =7D =7@9E4 9Exp
*N p
*f(N (Bo
#~ o
#d\	6~ \	6@X~ Xv#%57Gd& d&N W W:2 "PrO   