Base class for matrices, part 0
Note
For design documentation see matrix/docs.py.
EXAMPLES:
sage: matrix(2,[1,2,3,4])
[1 2]
[3 4]
Bases: sage.structure.element.Matrix
A generic matrix.
The Matrix class is the base class for all matrix classes. To create a Matrix, first create a MatrixSpace, then coerce a list of elements into the MatrixSpace. See the documentation of MatrixSpace for more details.
EXAMPLES:
We illustrate matrices and matrix spaces. Note that no actual matrix that you make should have class Matrix; the class should always be derived from Matrix.
sage: M = MatrixSpace(CDF,2,3); M
Full MatrixSpace of 2 by 3 dense matrices over Complex Double Field
sage: a = M([1,2,3, 4,5,6]); a
[1.0 2.0 3.0]
[4.0 5.0 6.0]
sage: type(a)
<type 'sage.matrix.matrix_complex_double_dense.Matrix_complex_double_dense'>
sage: parent(a)
Full MatrixSpace of 2 by 3 dense matrices over Complex Double Field
sage: matrix(CDF, 2,3, [1,2,3, 4,5,6])
[1.0 2.0 3.0]
[4.0 5.0 6.0]
sage: Mat(CDF,2,3)(range(1,7))
[1.0 2.0 3.0]
[4.0 5.0 6.0]
sage: Q.<i,j,k> = QuaternionAlgebra(QQ, -1,-1)
sage: matrix(Q,2,1,[1,2])
[1]
[2]
Returns the polynomial f(self*x).
INPUT:
OUTPUT: The polynomial f(self*x).
EXAMPLES:
sage: R.<x,y> = QQ[]
sage: x, y = R.gens()
sage: f = x**2 - y**2
sage: M = MatrixSpace(QQ, 2)
sage: A = M([1,2,3,4])
sage: A.act_on_polynomial(f)
-8*x^2 - 20*x*y - 12*y^2
Add s times column j to column i.
EXAMPLES: We add -1 times the third column to the second column of an integer matrix, remembering to start numbering cols at zero:
sage: a = matrix(ZZ,2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: a.add_multiple_of_column(1,2,-1)
sage: a
[ 0 -1 2]
[ 3 -1 5]
To add a rational multiple, we first need to change the base ring:
sage: a = a.change_ring(QQ)
sage: a.add_multiple_of_column(1,0,1/3)
sage: a
[ 0 -1 2]
[ 3 0 5]
If not, we get an error message:
sage: a.add_multiple_of_column(1,0,i)
Traceback (most recent call last):
...
TypeError: Multiplying column by Symbolic Ring element cannot be done over Rational Field, use change_ring or with_added_multiple_of_column instead.
Add s times row j to row i.
EXAMPLES: We add -3 times the first row to the second row of an integer matrix, remembering to start numbering rows at zero:
sage: a = matrix(ZZ,2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: a.add_multiple_of_row(1,0,-3)
sage: a
[ 0 1 2]
[ 3 1 -1]
To add a rational multiple, we first need to change the base ring:
sage: a = a.change_ring(QQ)
sage: a.add_multiple_of_row(1,0,1/3)
sage: a
[ 0 1 2]
[ 3 4/3 -1/3]
If not, we get an error message:
sage: a.add_multiple_of_row(1,0,i)
Traceback (most recent call last):
...
TypeError: Multiplying row by Symbolic Ring element cannot be done over Rational Field, use change_ring or with_added_multiple_of_row instead.
Return the anticommutator self and other.
The anticommutator of two \(n \times n\) matrices \(A\) and \(B\) is defined as \(\{A, B\} := AB + BA\) (sometimes this is written as \([A, B]_+\)).
EXAMPLES:
sage: A = Matrix(ZZ, 2, 2, range(4))
sage: B = Matrix(ZZ, 2, 2, [0, 1, 0, 0])
sage: A.anticommutator(B)
[2 3]
[0 2]
sage: A.anticommutator(B) == B.anticommutator(A)
True
sage: A.commutator(B) + B.anticommutator(A) == 2*A*B
True
Returns the base ring of the matrix.
EXAMPLES:
sage: m=matrix(QQ,2,[1,2,3,4])
sage: m.base_ring()
Rational Field
Return the matrix obtained by coercing the entries of this matrix into the given ring.
Always returns a copy (unless self is immutable, in which case returns self).
EXAMPLES:
sage: A = Matrix(QQ, 2, 2, [1/2, 1/3, 1/3, 1/4])
sage: A.parent()
Full MatrixSpace of 2 by 2 dense matrices over Rational Field
sage: A.change_ring(GF(25,'a'))
[3 2]
[2 4]
sage: A.change_ring(GF(25,'a')).parent()
Full MatrixSpace of 2 by 2 dense matrices over Finite Field in a of size 5^2
sage: A.change_ring(ZZ)
Traceback (most recent call last):
...
TypeError: matrix has denominators so can't change to ZZ.
Changing rings preserves subdivisions:
sage: A.subdivide([1], []); A
[1/2 1/3]
[-------]
[1/3 1/4]
sage: A.change_ring(GF(25,'a'))
[3 2]
[---]
[2 4]
Return the commutator self*other - other*self.
EXAMPLES:
sage: A = Matrix(ZZ, 2, 2, range(4))
sage: B = Matrix(ZZ, 2, 2, [0, 1, 0, 0])
sage: A.commutator(B)
[-2 -3]
[ 0 2]
sage: A.commutator(B) == -B.commutator(A)
True
Dictionary of the elements of self with keys pairs (i,j) and values the nonzero entries of self.
It is safe to change the returned dictionary.
EXAMPLES:
sage: R.<x,y> = QQ[]
sage: a = matrix(R,2,[x,y,0, 0,0,2*x+y]); a
[ x y 0]
[ 0 0 2*x + y]
sage: d = a.dict(); d
{(0, 1): y, (1, 2): 2*x + y, (0, 0): x}
Notice that changing the returned list does not change a (the list is a copy):
sage: d[0,0] = 25
sage: a
[ x y 0]
[ 0 0 2*x + y]
Returns the dimensions of this matrix as the tuple (nrows, ncols).
EXAMPLES:
sage: M = matrix([[1,2,3],[4,5,6]])
sage: N = M.transpose()
sage: M.dimensions()
(2, 3)
sage: N.dimensions()
(3, 2)
AUTHORS:
Return True if self is an alternating matrix.
Here, “alternating matrix” means a square matrix \(A\) satisfying \(A^T = -A\) and such that the diagonal entries of \(A\) are \(0\). Notice that the condition that the diagonal entries be \(0\) is not redundant for matrices over arbitrary ground rings (but it is redundant when \(2\) is invertible in the ground ring). A square matrix \(A\) only required to satisfy \(A^T = -A\) is said to be “skew-symmetric”, and this property is checked by the is_skew_symmetric() method.
EXAMPLES:
sage: m = matrix(QQ, [[0,2], [-2,0]])
sage: m.is_alternating()
True
sage: m = matrix(QQ, [[1,2], [2,1]])
sage: m.is_alternating()
False
In contrast to the property of being skew-symmetric, the property of being alternating does not tolerate nonzero entries on the diagonal even if they are their own negatives:
sage: n = matrix(Zmod(4), [[0, 1], [-1, 2]])
sage: n.is_alternating()
False
Returns True if this is a dense matrix.
In Sage, being dense is a property of the underlying representation, not the number of nonzero entries.
EXAMPLES:
sage: matrix(QQ,2,2,range(4)).is_dense()
True
sage: matrix(QQ,2,2,range(4),sparse=True).is_dense()
False
Returns True if the matrix is equal to its conjugate-transpose.
OUTPUT:
True if the matrix is square and equal to the transpose with every entry conjugated, and False otherwise.
Note that if conjugation has no effect on elements of the base ring (such as for integers), then the is_symmetric() method is equivalent and faster.
This routine is for matrices over exact rings and so may not work properly for matrices over RR or CC. For matrices with approximate entries, the rings of double-precision floating-point numbers, RDF and CDF, are a better choice since the sage.matrix.matrix_double_dense.Matrix_double_dense.is_hermitian() method has a tolerance parameter. This provides control over allowing for minor discrepancies between entries when checking equality.
The result is cached.
EXAMPLES:
sage: A = matrix(QQbar, [[ 1 + I, 1 - 6*I, -1 - I],
... [-3 - I, -4*I, -2],
... [-1 + I, -2 - 8*I, 2 + I]])
sage: A.is_hermitian()
False
sage: B = A*A.conjugate_transpose()
sage: B.is_hermitian()
True
Sage has several fields besides the entire complex numbers where conjugation is non-trivial.
sage: F.<b> = QuadraticField(-7)
sage: C = matrix(F, [[-2*b - 3, 7*b - 6, -b + 3],
... [-2*b - 3, -3*b + 2, -2*b],
... [ b + 1, 0, -2]])
sage: C.is_hermitian()
False
sage: C = C*C.conjugate_transpose()
sage: C.is_hermitian()
True
A matrix that is nearly Hermitian, but for a non-real diagonal entry.
sage: A = matrix(QQbar, [[ 2, 2-I, 1+4*I],
... [ 2+I, 3+I, 2-6*I],
... [1-4*I, 2+6*I, 5]])
sage: A.is_hermitian()
False
sage: A[1,1] = 132
sage: A.is_hermitian()
True
Rectangular matrices are never Hermitian.
sage: A = matrix(QQbar, 3, 4)
sage: A.is_hermitian()
False
A square, empty matrix is trivially Hermitian.
sage: A = matrix(QQ, 0, 0)
sage: A.is_hermitian()
True
Return True if this matrix is immutable.
See the documentation for self.set_immutable for more details about mutability.
EXAMPLES:
sage: A = Matrix(QQ['t','s'], 2, 2, range(4))
sage: A.is_immutable()
False
sage: A.set_immutable()
sage: A.is_immutable()
True
Return True if this matrix is invertible.
EXAMPLES: The following matrix is invertible over \(\QQ\) but not over \(\ZZ\).
sage: A = MatrixSpace(ZZ, 2)(range(4))
sage: A.is_invertible()
False
sage: A.matrix_over_field().is_invertible()
True
The inverse function is a constructor for matrices over the fraction field, so it can work even if A is not invertible.
sage: ~A # inverse of A
[-3/2 1/2]
[ 1 0]
The next matrix is invertible over \(\ZZ\).
sage: A = MatrixSpace(IntegerRing(),2)([1,10,0,-1])
sage: A.is_invertible()
True
sage: ~A # compute the inverse
[ 1 10]
[ 0 -1]
The following nontrivial matrix is invertible over \(\ZZ[x]\).
sage: R.<x> = PolynomialRing(IntegerRing())
sage: A = MatrixSpace(R,2)([1,x,0,-1])
sage: A.is_invertible()
True
sage: ~A
[ 1 x]
[ 0 -1]
Return True if this matrix is mutable.
See the documentation for self.set_immutable for more details about mutability.
EXAMPLES:
sage: A = Matrix(QQ['t','s'], 2, 2, range(4))
sage: A.is_mutable()
True
sage: A.set_immutable()
sage: A.is_mutable()
False
Returns True if self is singular.
OUTPUT:
A square matrix is singular if it has a zero determinant and this method will return True in exactly this case. When the entries of the matrix come from a field, this is equivalent to having a nontrivial kernel, or lacking an inverse, or having linearly dependent rows, or having linearly dependent columns.
For square matrices over a field the methods is_invertible() and is_singular() are logical opposites. However, it is an error to apply is_singular() to a matrix that is not square, while is_invertible() will always return False for a matrix that is not square.
EXAMPLES:
A singular matrix over the field QQ.
sage: A = matrix(QQ, 4, [-1,2,-3,6,0,-1,-1,0,-1,1,-5,7,-1,6,5,2])
sage: A.is_singular()
True
sage: A.right_kernel().dimension()
1
A matrix that is not singular, i.e. nonsingular, over a field.
sage: B = matrix(QQ, 4, [1,-3,-1,-5,2,-5,-2,-7,-2,5,3,4,-1,4,2,6])
sage: B.is_singular()
False
sage: B.left_kernel().dimension()
0
For rectangular matrices, invertibility is always False, but asking about singularity will give an error.
sage: C = matrix(QQ, 5, range(30))
sage: C.is_invertible()
False
sage: C.is_singular()
Traceback (most recent call last):
...
ValueError: self must be a square matrix
When the base ring is not a field, then a matrix may be both not invertible and not singular.
sage: D = matrix(ZZ, 4, [2,0,-4,8,2,1,-2,7,2,5,7,0,0,1,4,-6])
sage: D.is_invertible()
False
sage: D.is_singular()
False
sage: d = D.determinant(); d
2
sage: d.is_unit()
False
Return True if self is a skew-symmetric matrix.
Here, “skew-symmetric matrix” means a square matrix \(A\) satisfying \(A^T = -A\). It does not require that the diagonal entries of \(A\) are \(0\) (although this automatically follows from \(A^T = -A\) when \(2\) is invertible in the ground ring over which the matrix is considered). Skew-symmetric matrices \(A\) whose diagonal entries are \(0\) are said to be “alternating”, and this property is checked by the is_alternating() method.
EXAMPLES:
sage: m = matrix(QQ, [[0,2], [-2,0]])
sage: m.is_skew_symmetric()
True
sage: m = matrix(QQ, [[1,2], [2,1]])
sage: m.is_skew_symmetric()
False
Skew-symmetric is not the same as alternating when \(2\) is a zero-divisor in the ground ring:
sage: n = matrix(Zmod(4), [[0, 1], [-1, 2]])
sage: n.is_skew_symmetric()
True
but yet the diagonal cannot be completely arbitrary in this case:
sage: n = matrix(Zmod(4), [[0, 1], [-1, 3]])
sage: n.is_skew_symmetric()
False
This function takes a square matrix over an ordered integral domain and checks if it is skew-symmetrizable. A matrix \(B\) is skew-symmetrizable iff there exists an invertible diagonal matrix \(D\) such that \(DB\) is skew-symmetric.
Warning
Expects self to be a matrix over an ordered integral domain.
INPUT:
OUTPUT:
EXAMPLES:
sage: matrix([[0,6],[3,0]]).is_skew_symmetrizable(positive=False)
True
sage: matrix([[0,6],[3,0]]).is_skew_symmetrizable(positive=True)
False
sage: M = matrix(4,[0,1,0,0,-1,0,-1,0,0,2,0,1,0,0,-1,0]); M
[ 0 1 0 0]
[-1 0 -1 0]
[ 0 2 0 1]
[ 0 0 -1 0]
sage: M.is_skew_symmetrizable(return_diag=True)
[1, 1, 1/2, 1/2]
sage: M2 = diagonal_matrix([1,1,1/2,1/2])*M; M2
[ 0 1 0 0]
[ -1 0 -1 0]
[ 0 1 0 1/2]
[ 0 0 -1/2 0]
sage: M2.is_skew_symmetric()
True
REFERENCES:
Return True if this is a sparse matrix.
In Sage, being sparse is a property of the underlying representation, not the number of nonzero entries.
EXAMPLES:
sage: matrix(QQ,2,2,range(4)).is_sparse()
False
sage: matrix(QQ,2,2,range(4),sparse=True).is_sparse()
True
Return True precisely if this matrix is square, i.e., has the same number of rows and columns.
EXAMPLES:
sage: matrix(QQ,2,2,range(4)).is_square()
True
sage: matrix(QQ,2,3,range(6)).is_square()
False
Returns True if this is a symmetric matrix.
EXAMPLES:
sage: m=Matrix(QQ,2,range(0,4))
sage: m.is_symmetric()
False
sage: m=Matrix(QQ,2,(1,1,1,1,1,1))
sage: m.is_symmetric()
False
sage: m=Matrix(QQ,1,(2,))
sage: m.is_symmetric()
True
This function takes a square matrix over an ordered integral domain and checks if it is symmetrizable. A matrix \(B\) is symmetrizable iff there exists an invertible diagonal matrix \(D\) such that \(DB\) is symmetric.
Warning
Expects self to be a matrix over an ordered integral domain.
INPUT:
OUTPUT:
EXAMPLES:
sage: matrix([[0,6],[3,0]]).is_symmetrizable(positive=False)
True
sage: matrix([[0,6],[3,0]]).is_symmetrizable(positive=True)
True
sage: matrix([[0,6],[0,0]]).is_symmetrizable(return_diag=True)
False
sage: matrix([2]).is_symmetrizable(positive=True)
True
sage: matrix([[1,2],[3,4]]).is_symmetrizable(return_diag=true)
[1, 2/3]
REFERENCES:
Let \(A\) be this matrix and \(v\) be a free module element. If rows is True, return a matrix whose rows are the entries of the following vectors:
If rows is False, return a matrix whose columns are the entries of the following vectors:
INPUT:
EXAMPLES:
sage: A = matrix(ZZ,2, [1,1,3,5]); A
[1 1]
[3 5]
sage: v = vector([1,0])
sage: A.iterates(v,0)
[]
sage: A.iterates(v,5)
[ 1 0]
[ 1 1]
[ 4 6]
[ 22 34]
[124 192]
Another example:
sage: a = matrix(ZZ,3,range(9)); a
[0 1 2]
[3 4 5]
[6 7 8]
sage: v = vector([1,0,0])
sage: a.iterates(v,4)
[ 1 0 0]
[ 0 1 2]
[ 15 18 21]
[180 234 288]
sage: a.iterates(v,4,rows=False)
[ 1 0 15 180]
[ 0 3 42 558]
[ 0 6 69 936]
Return the linear combination of the columns of self given by the coefficients in the list v.
INPUT:
OUTPUT:
The vector (or free module element) that is a linear combination of the columns of self. If the list of scalars has fewer entries than the number of columns, additional zeros are appended to the list until it has as many entries as the number of columns.
EXAMPLES:
sage: a = matrix(ZZ,2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: a.linear_combination_of_columns([1,1,1])
(3, 12)
sage: a.linear_combination_of_columns([0,0,0])
(0, 0)
sage: a.linear_combination_of_columns([1/2,2/3,3/4])
(13/6, 95/12)
The list v can be anything that is iterable. Perhaps most naturally, a vector may be used.
sage: v = vector(ZZ, [1,2,3])
sage: a.linear_combination_of_columns(v)
(8, 26)
We check that a matrix with no columns behaves properly.
sage: matrix(QQ,2,0).linear_combination_of_columns([])
(0, 0)
The object returned is a vector, or a free module element.
sage: B = matrix(ZZ, 4, 3, range(12))
sage: w = B.linear_combination_of_columns([-1,2,-3])
sage: w
(-4, -10, -16, -22)
sage: w.parent()
Ambient free module of rank 4 over the principal ideal domain Integer Ring
sage: x = B.linear_combination_of_columns([1/2,1/3,1/4])
sage: x
(5/6, 49/12, 22/3, 127/12)
sage: x.parent()
Vector space of dimension 4 over Rational Field
The length of v can be less than the number of columns, but not greater.
sage: A = matrix(QQ,3,5, range(15))
sage: A.linear_combination_of_columns([1,-2,3,-4])
(-8, -18, -28)
sage: A.linear_combination_of_columns([1,2,3,4,5,6])
Traceback (most recent call last):
...
ValueError: length of v must be at most the number of columns of self
Return the linear combination of the rows of self given by the coefficients in the list v.
INPUT:
OUTPUT:
The vector (or free module element) that is a linear combination of the rows of self. If the list of scalars has fewer entries than the number of rows, additional zeros are appended to the list until it has as many entries as the number of rows.
EXAMPLES:
sage: a = matrix(ZZ,2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: a.linear_combination_of_rows([1,2])
(6, 9, 12)
sage: a.linear_combination_of_rows([0,0])
(0, 0, 0)
sage: a.linear_combination_of_rows([1/2,2/3])
(2, 19/6, 13/3)
The list v can be anything that is iterable. Perhaps most naturally, a vector may be used.
sage: v = vector(ZZ, [1,2])
sage: a.linear_combination_of_rows(v)
(6, 9, 12)
We check that a matrix with no rows behaves properly.
sage: matrix(QQ,0,2).linear_combination_of_rows([])
(0, 0)
The object returned is a vector, or a free module element.
sage: B = matrix(ZZ, 4, 3, range(12))
sage: w = B.linear_combination_of_rows([-1,2,-3,4])
sage: w
(24, 26, 28)
sage: w.parent()
Ambient free module of rank 3 over the principal ideal domain Integer Ring
sage: x = B.linear_combination_of_rows([1/2,1/3,1/4,1/5])
sage: x
(43/10, 67/12, 103/15)
sage: x.parent()
Vector space of dimension 3 over Rational Field
The length of v can be less than the number of rows, but not greater.
sage: A = matrix(QQ,3,4,range(12))
sage: A.linear_combination_of_rows([2,3])
(12, 17, 22, 27)
sage: A.linear_combination_of_rows([1,2,3,4])
Traceback (most recent call last):
...
ValueError: length of v must be at most the number of rows of self
List of the elements of self ordered by elements in each row. It is safe to change the returned list.
Warning
This function returns a list of the entries in the matrix self. It does not return a list of the rows of self, so it is different than the output of list(self), which returns [self[0],self[1],...].
EXAMPLES:
sage: R.<x,y> = QQ[]
sage: a = matrix(R,2,[x,y,x*y, y,x,2*x+y]); a
[ x y x*y]
[ y x 2*x + y]
sage: v = a.list(); v
[x, y, x*y, y, x, 2*x + y]
Note that list(a) is different than a.list():
sage: a.list()
[x, y, x*y, y, x, 2*x + y]
sage: list(a)
[(x, y, x*y), (y, x, 2*x + y)]
Notice that changing the returned list does not change a (the list is a copy):
sage: v[0] = 25
sage: a
[ x y x*y]
[ y x 2*x + y]
Return matrix mod \(p\), over the reduced ring.
EXAMPLES:
sage: M = matrix(ZZ, 2, 2, [5, 9, 13, 15])
sage: M.mod(7)
[5 2]
[6 1]
sage: parent(M.mod(7))
Full MatrixSpace of 2 by 2 dense matrices over Ring of integers modulo 7
Return the multiplicative order of this matrix, which must therefore be invertible.
EXAMPLES:
sage: A = matrix(GF(59),3,[10,56,39,53,56,33,58,24,55])
sage: A.multiplicative_order()
580
sage: (A^580).is_one()
True
sage: B = matrix(GF(10007^3,'b'),0)
sage: B.multiplicative_order()
1
sage: C = matrix(GF(2^10,'c'),2,3,[1]*6)
sage: C.multiplicative_order()
Traceback (most recent call last):
...
ArithmeticError: self must be invertible ...
sage: D = matrix(IntegerModRing(6),3,[5,5,3,0,2,5,5,4,0])
sage: D.multiplicative_order()
Traceback (most recent call last):
...
NotImplementedError: ... only ... over finite fields
sage: E = MatrixSpace(GF(11^2,'e'),5).random_element()
sage: (E^E.multiplicative_order()).is_one()
True
REFERENCES:
Mutates self at row and column index k.
Warning
Only makes sense if self is skew-symmetrizable.
INPUT:
EXAMPLES:
Mutation of the B-matrix of the quiver of type \(A_3\):
sage: M = matrix(ZZ,3,[0,1,0,-1,0,-1,0,1,0]); M
[ 0 1 0]
[-1 0 -1]
[ 0 1 0]
sage: M.mutate(0); M
[ 0 -1 0]
[ 1 0 -1]
[ 0 1 0]
sage: M.mutate(1); M
[ 0 1 -1]
[-1 0 1]
[ 1 -1 0]
sage: M = matrix(ZZ,6,[0,1,0,-1,0,-1,0,1,0,1,0,0,0,1,0,0,0,1]); M
[ 0 1 0]
[-1 0 -1]
[ 0 1 0]
[ 1 0 0]
[ 0 1 0]
[ 0 0 1]
sage: M.mutate(0); M
[ 0 -1 0]
[ 1 0 -1]
[ 0 1 0]
[-1 1 0]
[ 0 1 0]
[ 0 0 1]
REFERENCES:
Return the number of columns of this matrix.
EXAMPLES:
sage: M = MatrixSpace(QQ, 2, 3)
sage: A = M([1,2,3, 4,5,6])
sage: A
[1 2 3]
[4 5 6]
sage: A.ncols()
3
sage: A.nrows()
2
AUTHORS:
Return the list of i such that the i-th column of self is NOT a pivot column of the reduced row echelon form of self.
OUTPUT: sorted tuple of (Python) integers
EXAMPLES:
sage: a = matrix(QQ,3,3,range(9)); a
[0 1 2]
[3 4 5]
[6 7 8]
sage: a.echelon_form()
[ 1 0 -1]
[ 0 1 2]
[ 0 0 0]
sage: a.nonpivots()
(2,)
Returns the sorted list of pairs (i,j) such that self[i,j] != 0.
INPUT:
EXAMPLES:
sage: a = matrix(QQ, 2,3, [1,2,0,2,0,0]); a
[1 2 0]
[2 0 0]
sage: a.nonzero_positions()
[(0, 0), (0, 1), (1, 0)]
sage: a.nonzero_positions(copy=False)
[(0, 0), (0, 1), (1, 0)]
sage: a.nonzero_positions(column_order=True)
[(0, 0), (1, 0), (0, 1)]
sage: a = matrix(QQ, 2,3, [1,2,0,2,0,0], sparse=True); a
[1 2 0]
[2 0 0]
sage: a.nonzero_positions()
[(0, 0), (0, 1), (1, 0)]
sage: a.nonzero_positions(copy=False)
[(0, 0), (0, 1), (1, 0)]
sage: a.nonzero_positions(column_order=True)
[(0, 0), (1, 0), (0, 1)]
Return a sorted list of the integers j such that self[j,i] is nonzero, i.e., such that the j-th position of the i-th column is nonzero.
INPUT:
OUTPUT: list
EXAMPLES:
sage: a = matrix(QQ, 3,2, [1,2,0,2,0,0]); a
[1 2]
[0 2]
[0 0]
sage: a.nonzero_positions_in_column(0)
[0]
sage: a.nonzero_positions_in_column(1)
[0, 1]
You’ll get an IndexError, if you select an invalid column:
sage: a.nonzero_positions_in_column(2)
Traceback (most recent call last):
...
IndexError: matrix column index out of range
Return the integers j such that self[i,j] is nonzero, i.e., such that the j-th position of the i-th row is nonzero.
INPUT:
OUTPUT: list
EXAMPLES:
sage: a = matrix(QQ, 3,2, [1,2,0,2,0,0]); a
[1 2]
[0 2]
[0 0]
sage: a.nonzero_positions_in_row(0)
[0, 1]
sage: a.nonzero_positions_in_row(1)
[1]
sage: a.nonzero_positions_in_row(2)
[]
Return the number of rows of this matrix.
EXAMPLES:
sage: M = MatrixSpace(QQ,6,7)
sage: A = M([1,2,3,4,5,6,7, 22,3/4,34,11,7,5,3, 99,65,1/2,2/3,3/5,4/5,5/6, 9,8/9, 9/8,7/6,6/7,76,4, 0,9,8,7,6,5,4, 123,99,91,28,6,1024,1])
sage: A
[ 1 2 3 4 5 6 7]
[ 22 3/4 34 11 7 5 3]
[ 99 65 1/2 2/3 3/5 4/5 5/6]
[ 9 8/9 9/8 7/6 6/7 76 4]
[ 0 9 8 7 6 5 4]
[ 123 99 91 28 6 1024 1]
sage: A.ncols()
7
sage: A.nrows()
6
AUTHORS:
Permute the columns of self by applying the permutation group element permutation.
As a permutation group element acts on integers \(\{1, \hdots, n\}\) the columns are considered as being numbered from 1 for this operation.
INPUT:
EXAMPLE: We create a matrix:
sage: M = matrix(ZZ,[[1,0,0,0,0],[0,2,0,0,0],[0,0,3,0,0],[0,0,0,4,0],[0,0,0,0,5]])
sage: M
[1 0 0 0 0]
[0 2 0 0 0]
[0 0 3 0 0]
[0 0 0 4 0]
[0 0 0 0 5]
Next of all, create a permutation group element and act on M with it:
sage: G = PermutationGroup(['(1,2,3)(4,5)', '(1,2,3,4,5)'])
sage: sigma, tau = G.gens()
sage: sigma
(1,2,3)(4,5)
sage: M.permute_columns(sigma)
sage: M
[0 0 1 0 0]
[2 0 0 0 0]
[0 3 0 0 0]
[0 0 0 0 4]
[0 0 0 5 0]
Permute the rows of self by applying the permutation group element permutation.
As a permutation group element acts on integers \(\{1,\hdots,n\}\) the rows are considered as being numbered from 1 for this operation.
INPUT:
EXAMPLE: We create a matrix:
sage: M = matrix(ZZ,[[1,0,0,0,0],[0,2,0,0,0],[0,0,3,0,0],[0,0,0,4,0],[0,0,0,0,5]])
sage: M
[1 0 0 0 0]
[0 2 0 0 0]
[0 0 3 0 0]
[0 0 0 4 0]
[0 0 0 0 5]
Next of all, create a permutation group element and act on M:
sage: G = PermutationGroup(['(1,2,3)(4,5)', '(1,2,3,4,5)'])
sage: sigma, tau = G.gens()
sage: sigma
(1,2,3)(4,5)
sage: M.permute_rows(sigma)
sage: M
[0 2 0 0 0]
[0 0 3 0 0]
[1 0 0 0 0]
[0 0 0 0 5]
[0 0 0 4 0]
Permute the rows and columns of self by applying the permutation group elements row_permutation and column_permutation respectively.
As a permutation group element acts on integers \(\{1,\hdots,n\}\) the rows and columns are considered as being numbered from 1 for this operation.
INPUT:
OUTPUT:
EXAMPLE: We create a matrix:
sage: M = matrix(ZZ,[[1,0,0,0,0],[0,2,0,0,0],[0,0,3,0,0],[0,0,0,4,0],[0,0,0,0,5]])
sage: M
[1 0 0 0 0]
[0 2 0 0 0]
[0 0 3 0 0]
[0 0 0 4 0]
[0 0 0 0 5]
Next of all, create a permutation group element and act on M:
sage: G = PermutationGroup(['(1,2,3)(4,5)', '(1,2,3,4,5)'])
sage: sigma, tau = G.gens()
sage: sigma
(1,2,3)(4,5)
sage: M.permute_rows_and_columns(sigma,tau)
sage: M
[2 0 0 0 0]
[0 3 0 0 0]
[0 0 0 0 1]
[0 0 0 5 0]
[0 0 4 0 0]
Return the pivot column positions of this matrix.
OUTPUT: a tuple of Python integers: the position of the first nonzero entry in each row of the echelon form.
This returns a tuple so it is immutable; see #10752.
EXAMPLES:
sage: A = matrix(QQ, 2, 2, range(4))
sage: A.pivots()
(0, 1)
TESTS:
We should be able to compute the rank of a matrix whose entries are polynomials over a finite field (trac #5014):
sage: P.<x> = PolynomialRing(GF(17))
sage: m = matrix(P, [ [ 6*x^2 + 8*x + 12, 10*x^2 + 4*x + 11],
... [8*x^2 + 12*x + 15, 8*x^2 + 9*x + 16] ])
sage: m.rank()
2
Replace i-th col of self by s times i-th col of self.
INPUT:
EXAMPLES: We rescale the last column of a matrix over the rational numbers:
sage: a = matrix(QQ,2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: a.rescale_col(2,1/2); a
[ 0 1 1]
[ 3 4 5/2]
sage: R.<x> = QQ[]
We rescale the last column of a matrix over a polynomial ring:
sage: a = matrix(R,2,3,[1,x,x^2,x^3,x^4,x^5]); a
[ 1 x x^2]
[x^3 x^4 x^5]
sage: a.rescale_col(2,1/2); a
[ 1 x 1/2*x^2]
[ x^3 x^4 1/2*x^5]
We try and fail to rescale a matrix over the integers by a non-integer:
sage: a = matrix(ZZ,2,3,[0,1,2, 3,4,4]); a
[0 1 2]
[3 4 4]
sage: a.rescale_col(2,1/2)
Traceback (most recent call last):
...
TypeError: Rescaling column by Rational Field element cannot be done over Integer Ring, use change_ring or with_rescaled_col instead.
To rescale the matrix by 1/2, you must change the base ring to the rationals:
sage: a = a.change_ring(QQ); a
[0 1 2]
[3 4 4]
sage: a.rescale_col(2,1/2); a
[0 1 1]
[3 4 2]
Replace i-th row of self by s times i-th row of self.
INPUT:
EXAMPLES: We rescale the second row of a matrix over the rational numbers:
sage: a = matrix(QQ,3,range(6)); a
[0 1]
[2 3]
[4 5]
sage: a.rescale_row(1,1/2); a
[ 0 1]
[ 1 3/2]
[ 4 5]
We rescale the second row of a matrix over a polynomial ring:
sage: R.<x> = QQ[]
sage: a = matrix(R,3,[1,x,x^2,x^3,x^4,x^5]);a
[ 1 x]
[x^2 x^3]
[x^4 x^5]
sage: a.rescale_row(1,1/2); a
[ 1 x]
[1/2*x^2 1/2*x^3]
[ x^4 x^5]
We try and fail to rescale a matrix over the integers by a non-integer:
sage: a = matrix(ZZ,2,3,[0,1,2, 3,4,4]); a
[0 1 2]
[3 4 4]
sage: a.rescale_row(1,1/2)
Traceback (most recent call last):
...
TypeError: Rescaling row by Rational Field element cannot be done over Integer Ring, use change_ring or with_rescaled_row instead.
To rescale the matrix by 1/2, you must change the base ring to the rationals:
sage: a = a.change_ring(QQ); a
[0 1 2]
[3 4 4]
sage: a.rescale_col(1,1/2); a
[ 0 1/2 2]
[ 3 2 4]
Set column i equal to s times column j.
EXAMPLES: We change the second column to -3 times the first column.
sage: a = matrix(ZZ,2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: a.set_col_to_multiple_of_col(1,0,-3)
sage: a
[ 0 0 2]
[ 3 -9 5]
If we try to multiply a column by a rational number, we get an error message:
sage: a.set_col_to_multiple_of_col(1,0,1/2)
Traceback (most recent call last):
...
TypeError: Multiplying column by Rational Field element cannot be done over Integer Ring, use change_ring or with_col_set_to_multiple_of_col instead.
Call this function to set the matrix as immutable.
Matrices are always mutable by default, i.e., you can change their entries using A[i,j] = x. However, mutable matrices aren’t hashable, so can’t be used as keys in dictionaries, etc. Also, often when implementing a class, you might compute a matrix associated to it, e.g., the matrix of a Hecke operator. If you return this matrix to the user you’re really returning a reference and the user could then change an entry; this could be confusing. Thus you should set such a matrix immutable.
EXAMPLES:
sage: A = Matrix(QQ, 2, 2, range(4))
sage: A.is_mutable()
True
sage: A[0,0] = 10
sage: A
[10 1]
[ 2 3]
Mutable matrices are not hashable, so can’t be used as keys for dictionaries:
sage: hash(A)
Traceback (most recent call last):
...
TypeError: mutable matrices are unhashable
sage: v = {A:1}
Traceback (most recent call last):
...
TypeError: mutable matrices are unhashable
If we make A immutable it suddenly is hashable.
sage: A.set_immutable()
sage: A.is_mutable()
False
sage: A[0,0] = 10
Traceback (most recent call last):
...
ValueError: matrix is immutable; please change a copy instead (i.e., use copy(M) to change a copy of M).
sage: hash(A) #random
12
sage: v = {A:1}; v
{[10 1]
[ 2 3]: 1}
Set row i equal to s times row j.
EXAMPLES: We change the second row to -3 times the first row:
sage: a = matrix(ZZ,2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: a.set_row_to_multiple_of_row(1,0,-3)
sage: a
[ 0 1 2]
[ 0 -3 -6]
If we try to multiply a row by a rational number, we get an error message:
sage: a.set_row_to_multiple_of_row(1,0,1/2)
Traceback (most recent call last):
...
TypeError: Multiplying row by Rational Field element cannot be done over Integer Ring, use change_ring or with_row_set_to_multiple_of_row instead.
Return a nice string representation of the matrix.
INPUT:
rep_mapping - a dictionary or callable used to override the usual representation of elements.
If rep_mapping is a dictionary then keys should be elements of the base ring and values the desired string representation. Values sent in via the other keyword arguments will override values in the dictionary. Use of a dictionary can potentially take a very long time due to the need to hash entries of the matrix. Matrices with entries from QQbar are one example.
If rep_mapping is callable then it will be called with elements of the matrix and must return a string. Simply call repr() on elements which should have the default representation.
zero - string (default: None); if not None use the value of zero as the representation of the zero element.
plus_one - string (default: None); if not None use the value of plus_one as the representation of the one element.
minus_one - string (default: None); if not None use the value of minus_one as the representation of the negative of the one element.
EXAMPLES:
sage: R = PolynomialRing(QQ,6,'z')
sage: a = matrix(2,3, R.gens())
sage: a.__repr__()
'[z0 z1 z2]\n[z3 z4 z5]'
sage: M = matrix([[1,0],[2,-1]])
sage: M.str()
'[ 1 0]\n[ 2 -1]'
sage: M.str(plus_one='+',minus_one='-',zero='.')
'[+ .]\n[2 -]'
sage: M.str({1:"not this one",2:"II"},minus_one="*",plus_one="I")
'[ I 0]\n[II *]'
sage: def print_entry(x):
... if x>0:
... return '+'
... elif x<0:
... return '-'
... else: return '.'
...
sage: M.str(print_entry)
'[+ .]\n[+ -]'
sage: M.str(repr)
'[ 1 0]\n[ 2 -1]'
TESTS:
Prior to Trac #11544 this could take a full minute to run (2011).
sage: A = matrix(QQ, 4, 4, [1, 2, -2, 2, 1, 0, -1, -1, 0, -1, 1, 1, -1, 2, 1/2, 0])
sage: e = A.eigenvalues()[3]
sage: K = (A-e).kernel()
sage: P = K.basis_matrix()
sage: P.str()
'[ 1.000000000000000? + 0.?e-17*I -2.116651487479748? + 0.0255565807096352?*I -0.2585224251020429? + 0.288602340904754?*I -0.4847545623533090? - 1.871890760086142?*I]'
Swap columns c1 and c2 of self.
EXAMPLES: We create a rational matrix:
sage: M = MatrixSpace(QQ,3,3)
sage: A = M([1,9,-7,4/5,4,3,6,4,3])
sage: A
[ 1 9 -7]
[4/5 4 3]
[ 6 4 3]
Since the first column is numbered zero, this swaps the second and third columns:
sage: A.swap_columns(1,2); A
[ 1 -7 9]
[4/5 3 4]
[ 6 3 4]
Swap rows r1 and r2 of self.
EXAMPLES: We create a rational matrix:
sage: M = MatrixSpace(QQ,3,3)
sage: A = M([1,9,-7,4/5,4,3,6,4,3])
sage: A
[ 1 9 -7]
[4/5 4 3]
[ 6 4 3]
Since the first row is numbered zero, this swaps the first and third rows:
sage: A.swap_rows(0,2); A
[ 6 4 3]
[4/5 4 3]
[ 1 9 -7]
Add s times column j to column i, returning new matrix.
EXAMPLES: We add -1 times the third column to the second column of an integer matrix, remembering to start numbering cols at zero:
sage: a = matrix(ZZ,2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: b = a.with_added_multiple_of_column(1,2,-1); b
[ 0 -1 2]
[ 3 -1 5]
The original matrix is unchanged:
sage: a
[0 1 2]
[3 4 5]
Adding a rational multiple is okay, and reassigning a variable is okay:
sage: a = a.with_added_multiple_of_column(0,1,1/3); a
[ 1/3 1 2]
[13/3 4 5]
Add s times row j to row i, returning new matrix.
EXAMPLES: We add -3 times the first row to the second row of an integer matrix, remembering to start numbering rows at zero:
sage: a = matrix(ZZ,2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: b = a.with_added_multiple_of_row(1,0,-3); b
[ 0 1 2]
[ 3 1 -1]
The original matrix is unchanged:
sage: a
[0 1 2]
[3 4 5]
Adding a rational multiple is okay, and reassigning a variable is okay:
sage: a = a.with_added_multiple_of_row(0,1,1/3); a
[ 1 7/3 11/3]
[ 3 4 5]
Set column i equal to s times column j, returning a new matrix.
EXAMPLES: We change the second column to -3 times the first column.
sage: a = matrix(ZZ,2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: b = a.with_col_set_to_multiple_of_col(1,0,-3); b
[ 0 0 2]
[ 3 -9 5]
Note that the original matrix is unchanged:
sage: a
[0 1 2]
[3 4 5]
Adding a rational multiple is okay, and reassigning a variable is okay:
sage: a = a.with_col_set_to_multiple_of_col(1,0,1/2); a
[ 0 0 2]
[ 3 3/2 5]
Return the matrix obtained from permuting the columns of self by applying the permutation group element permutation.
As a permutation group element acts on integers \(\{1,\hdots,n\}\) the columns are considered as being numbered from 1 for this operation.
INPUT:
OUTPUT:
EXAMPLE: We create some matrix:
sage: M = matrix(ZZ,[[1,0,0,0,0],[0,2,0,0,0],[0,0,3,0,0],[0,0,0,4,0],[0,0,0,0,5]])
sage: M
[1 0 0 0 0]
[0 2 0 0 0]
[0 0 3 0 0]
[0 0 0 4 0]
[0 0 0 0 5]
Next of all, create a permutation group element and act on M:
sage: G = PermutationGroup(['(1,2,3)(4,5)', '(1,2,3,4,5)'])
sage: sigma, tau = G.gens()
sage: sigma
(1,2,3)(4,5)
sage: M.with_permuted_columns(sigma)
[0 0 1 0 0]
[2 0 0 0 0]
[0 3 0 0 0]
[0 0 0 0 4]
[0 0 0 5 0]
Return the matrix obtained from permuting the rows of self by applying the permutation group element permutation.
As a permutation group element acts on integers \(\{1,\hdots,n\}\) the rows are considered as being numbered from 1 for this operation.
INPUT:
OUTPUT:
EXAMPLE: We create a matrix:
sage: M = matrix(ZZ,[[1,0,0,0,0],[0,2,0,0,0],[0,0,3,0,0],[0,0,0,4,0],[0,0,0,0,5]])
sage: M
[1 0 0 0 0]
[0 2 0 0 0]
[0 0 3 0 0]
[0 0 0 4 0]
[0 0 0 0 5]
Next of all, create a permutation group element and act on M:
sage: G = PermutationGroup(['(1,2,3)(4,5)', '(1,2,3,4,5)'])
sage: sigma, tau = G.gens()
sage: sigma
(1,2,3)(4,5)
sage: M.with_permuted_rows(sigma)
[0 2 0 0 0]
[0 0 3 0 0]
[1 0 0 0 0]
[0 0 0 0 5]
[0 0 0 4 0]
Return the matrix obtained from permuting the rows and columns of self by applying the permutation group elements row_permutation and column_permutation.
As a permutation group element acts on integers \(\{1,\hdots,n\}\) the rows are considered as being numbered from 1 for this operation.
INPUT:
OUTPUT:
EXAMPLE: We create a matrix:
sage: M = matrix(ZZ,[[1,0,0,0,0],[0,2,0,0,0],[0,0,3,0,0],[0,0,0,4,0],[0,0,0,0,5]])
sage: M
[1 0 0 0 0]
[0 2 0 0 0]
[0 0 3 0 0]
[0 0 0 4 0]
[0 0 0 0 5]
Next of all, create a permutation group element and act on M:
sage: G = PermutationGroup(['(1,2,3)(4,5)', '(1,2,3,4,5)'])
sage: sigma, tau = G.gens()
sage: sigma
(1,2,3)(4,5)
sage: M.with_permuted_rows_and_columns(sigma,tau)
[2 0 0 0 0]
[0 3 0 0 0]
[0 0 0 0 1]
[0 0 0 5 0]
[0 0 4 0 0]
Replaces i-th col of self by s times i-th col of self, returning new matrix.
EXAMPLES: We rescale the last column of a matrix over the integers:
sage: a = matrix(ZZ,2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: b = a.with_rescaled_col(2,-2); b
[ 0 1 -4]
[ 3 4 -10]
The original matrix is unchanged:
sage: a
[0 1 2]
[3 4 5]
Adding a rational multiple is okay, and reassigning a variable is okay:
sage: a = a.with_rescaled_col(1,1/3); a
[ 0 1/3 2]
[ 3 4/3 5]
Replaces i-th row of self by s times i-th row of self, returning new matrix.
EXAMPLES: We rescale the second row of a matrix over the integers:
sage: a = matrix(ZZ,3,2,range(6)); a
[0 1]
[2 3]
[4 5]
sage: b = a.with_rescaled_row(1,-2); b
[ 0 1]
[-4 -6]
[ 4 5]
The original matrix is unchanged:
sage: a
[0 1]
[2 3]
[4 5]
Adding a rational multiple is okay, and reassigning a variable is okay:
sage: a = a.with_rescaled_row(2,1/3); a
[ 0 1]
[ 2 3]
[4/3 5/3]
Set row i equal to s times row j, returning a new matrix.
EXAMPLES: We change the second row to -3 times the first row:
sage: a = matrix(ZZ,2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: b = a.with_row_set_to_multiple_of_row(1,0,-3); b
[ 0 1 2]
[ 0 -3 -6]
Note that the original matrix is unchanged:
sage: a
[0 1 2]
[3 4 5]
Adding a rational multiple is okay, and reassigning a variable is okay:
sage: a = a.with_row_set_to_multiple_of_row(1,0,1/2); a
[ 0 1 2]
[ 0 1/2 1]
Swap columns c1 and c2 of self and return a new matrix.
INPUT:
OUTPUT:
A new matrix, identical to self except that columns c1 and c2 are swapped.
EXAMPLES:
Remember that columns are numbered starting from zero.
sage: A = matrix(QQ, 4, range(20))
sage: A.with_swapped_columns(1, 2)
[ 0 2 1 3 4]
[ 5 7 6 8 9]
[10 12 11 13 14]
[15 17 16 18 19]
Trying to swap a column with itself will succeed, but still return a new matrix.
sage: A = matrix(QQ, 4, range(20))
sage: B = A.with_swapped_columns(2, 2)
sage: A == B
True
sage: A is B
False
The column specifications are checked.
sage: A = matrix(4, range(20))
sage: A.with_swapped_columns(-1, 2)
Traceback (most recent call last):
...
IndexError: matrix column index out of range
sage: A.with_swapped_columns(2, 5)
Traceback (most recent call last):
...
IndexError: matrix column index out of range
Swap rows r1 and r2 of self and return a new matrix.
INPUT:
OUTPUT:
A new matrix, identical to self except that rows r1 and r2 are swapped.
EXAMPLES:
Remember that rows are numbered starting from zero.
sage: A = matrix(QQ, 4, range(20))
sage: A.with_swapped_rows(1, 2)
[ 0 1 2 3 4]
[10 11 12 13 14]
[ 5 6 7 8 9]
[15 16 17 18 19]
Trying to swap a row with itself will succeed, but still return a new matrix.
sage: A = matrix(QQ, 4, range(20))
sage: B = A.with_swapped_rows(2, 2)
sage: A == B
True
sage: A is B
False
The row specifications are checked.
sage: A = matrix(4, range(20))
sage: A.with_swapped_rows(-1, 2)
Traceback (most recent call last):
...
IndexError: matrix row index out of range
sage: A.with_swapped_rows(2, 5)
Traceback (most recent call last):
...
IndexError: matrix row index out of range
Sets the global variable max_cols (which is used in deciding how to output a matrix).
EXAMPLES:
sage: from sage.matrix.matrix0 import set_max_cols
sage: set_max_cols(50)
Sets the global variable max_rows (which is used in deciding how to output a matrix).
EXAMPLES:
sage: from sage.matrix.matrix0 import set_max_rows
sage: set_max_rows(20)
Unpickle a matrix. This is only used internally by Sage. Users should never call this function directly.
EXAMPLES: We illustrating saving and loading several different types of matrices.
OVER \(\ZZ\):
sage: A = matrix(ZZ,2,range(4))
sage: loads(dumps(A)) # indirect doctest
[0 1]
[2 3]
Sparse OVER \(\QQ\):
Dense over \(\QQ[x,y]\):
Dense over finite field.