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]
- class sage.matrix.matrix0.Matrix#
Bases:
sage.structure.element.Matrix
A generic matrix.
The
Matrix
class is the base class for all matrix classes. To create aMatrix
, first create aMatrixSpace
, then coerce a list of elements into theMatrixSpace
. See the documentation ofMatrixSpace
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) <class '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]
- act_on_polynomial(f)#
Return the polynomial f(self*x).
INPUT:
self
- an nxn matrixf
- a polynomial in n variables x=(x1,…,xn)
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_multiple_of_column(i, j, s, start_row=0)#
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,SR.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_multiple_of_row(i, j, s, start_col=0)#
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,SR.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.
- add_to_entry(i, j, elt)#
Add
elt
to the entry at position(i, j)
.EXAMPLES:
sage: m = matrix(QQ['x,y'], 2, 2) sage: m.add_to_entry(0, 1, 2) sage: m [0 2] [0 0]
- anticommutator(other)#
Return the anticommutator
self
andother
.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
- base_ring()#
Return the base ring of the matrix.
EXAMPLES:
sage: m=matrix(QQ,2,[1,2,3,4]) sage: m.base_ring() Rational Field
- change_ring(ring)#
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]
- commutator(other)#
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
- dict(copy=True)#
Dictionary of the elements of
self
with keys pairs(i,j)
and values the nonzero entries ofself
.INPUT:
copy
– (default:True
) make a copy of thedict
corresponding toself
If
copy=True
, then is safe to change the returned dictionary. Otherwise, this can cause undesired behavior by mutating thedict
.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, 0): x, (0, 1): y, (1, 2): 2*x + y}
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]
- dimensions()#
Return 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:
Benjamin Lundell (2012-02-09): examples
- inverse_of_unit(algorithm=None)#
Return the inverse of this matrix in the same matrix space.
The matrix must be invertible on the base ring. Otherwise, an
ArithmeticError
is raised.The computation goes through the matrix of cofactors and avoids division. In particular the base ring does not need to have a fraction field.
INPUT:
algorithm
– (default:None
) eitherNone
or"df"
(for division free)
EXAMPLES:
sage: R.<a,b,c,d> = ZZ[] sage: RR = R.quotient(a*d-b*c-1) sage: a,b,c,d = RR.gens() sage: m = matrix(2, [a,b,c,d]) sage: n = m.inverse_of_unit() sage: m * n [1 0] [0 1] sage: matrix(RR, 2, 1, [a,b]).inverse_of_unit() Traceback (most recent call last): ... ArithmeticError: self must be a square matrix sage: matrix(RR, 1, 1, [2]).inverse_of_unit() Traceback (most recent call last): ... NotImplementedError: Lifting of multivariate polynomials over non-fields is not implemented. sage: R = ZZ.cartesian_product(ZZ) sage: m = matrix(R, 2, [R((2,1)), R((1,1)), R((1,1)), R((1,2))]) sage: m * m.inverse_of_unit() [(1, 1) (0, 0)] [(0, 0) (1, 1)]
Tests for trac ticket #28570:
sage: P = posets.TamariLattice(7) sage: M = P._hasse_diagram._leq_matrix sage: M.inverse_of_unit() # this was very slow, now 1s 429 x 429 sparse matrix over Integer Ring... sage: m = matrix(Zmod(2**2), 1, 1, [1], sparse=True) sage: mi = ~m; mi [1] sage: mi.parent() Full MatrixSpace of 1 by 1 sparse matrices over Ring of integers modulo 4
- is_alternating()#
Return
True
ifself
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
- is_dense()#
Return 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
- is_hermitian()#
Return
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, andFalse
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
orCC
. For matrices with approximate entries, the rings of double-precision floating-point numbers,RDF
andCDF
, are a better choice since thesage.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
- is_immutable()#
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
- is_invertible()#
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]
- is_mutable()#
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
- is_singular()#
Return
True
ifself
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()
andis_singular()
are logical opposites. However, it is an error to applyis_singular()
to a matrix that is not square, whileis_invertible()
will always returnFalse
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
- is_skew_hermitian()#
Return
True
if the matrix is equal to the negative of its conjugate transpose.OUTPUT:
True
if the matrix is square and equal to the negative of its conjugate transpose, andFalse
otherwise.Note that if conjugation has no effect on elements of the base ring (such as for integers), then the
is_skew_symmetric()
method is equivalent and faster.This routine is for matrices over exact rings and so may not work properly for matrices over
RR
orCC
. For matrices with approximate entries, the rings of double-precision floating-point numbers,RDF
andCDF
, are a better choice since thesage.matrix.matrix_double_dense.Matrix_double_dense.is_skew_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, [[0, -1], ....: [1, 0]]) sage: A.is_skew_hermitian() True
A matrix that is nearly skew-Hermitian, but for a non-real diagonal entry.
sage: A = matrix(QQbar, [[ -I, -1, 1-I], ....: [ 1, 1, -1], ....: [-1-I, 1, -I]]) sage: A.is_skew_hermitian() False sage: A[1,1] = -I sage: A.is_skew_hermitian() True
Rectangular matrices are never skew-Hermitian.
sage: A = matrix(QQbar, 3, 4) sage: A.is_skew_hermitian() False
A square, empty matrix is trivially Hermitian.
sage: A = matrix(QQ, 0, 0) sage: A.is_skew_hermitian() True
- is_skew_symmetric()#
Return
True
ifself
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
- is_skew_symmetrizable(return_diag=False, positive=True)#
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:
return_diag
– bool(default:False) if True andself
is skew-symmetrizable the diagonal entries of the matrix \(D\) are returned.positive
– bool(default:True) if True, the condition that \(D\) has positive entries is added.
OUTPUT:
True – if
self
is skew-symmetrizable andreturn_diag
is Falsethe diagonal entries of a matrix \(D\) such that \(DB\) is skew-symmetric – iff
self
is skew-symmetrizable andreturn_diag
is TrueFalse – iff
self
is not skew-symmetrizable
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:
- is_sparse()#
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
- is_square()#
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
- is_symmetric()#
Return True if this is a symmetric matrix.
A symmetric matrix is necessarily square.
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
- is_symmetrizable(return_diag=False, positive=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:
return_diag
– bool(default:False) if True andself
is symmetrizable the diagonal entries of the matrix \(D\) are returned.positive
– bool(default:True) if True, the condition that \(D\) has positive entries is added.
OUTPUT:
True – if
self
is symmetrizable andreturn_diag
is Falsethe diagonal entries of a matrix \(D\) such that \(DB\) is symmetric – iff
self
is symmetrizable andreturn_diag
is TrueFalse – iff
self
is not symmetrizable
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:
- is_unit()#
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]
- items()#
Return an iterable of
((i,j), value)
elements.This may (but is not guaranteed to) suppress zero values.
EXAMPLES:
sage: a = matrix(QQ['x,y'], 2, range(6), sparse=True); a [0 1 2] [3 4 5] sage: list(a.items()) [((0, 1), 1), ((0, 2), 2), ((1, 0), 3), ((1, 1), 4), ((1, 2), 5)]
- iterates(v, n, rows=True)#
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:
\[v, v A, v A^2, \dots, v A^{n-1}.\]If rows is False, return a matrix whose columns are the entries of the following vectors:
\[v, Av, A^2 v, \dots, A^{n-1} v.\]INPUT:
v
- free module elementn
- nonnegative integer
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]
- linear_combination_of_columns(v)#
Return the linear combination of the columns of
self
given by the coefficients in the listv
.INPUT:
v
- a list of scalars. The length can be less than the number of columns ofself
but not greater.
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
- linear_combination_of_rows(v)#
Return the linear combination of the rows of
self
given by the coefficients in the listv
.INPUT:
v
- a list of scalars. The length can be less than the number of rows ofself
but not greater.
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()#
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 ofself
, so it is different than the output oflist(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]
- mod(p)#
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
- monomial_coefficients(copy=True)#
Dictionary of the elements of
self
with keys pairs(i,j)
and values the nonzero entries ofself
.INPUT:
copy
– (default:True
) make a copy of thedict
corresponding toself
If
copy=True
, then is safe to change the returned dictionary. Otherwise, this can cause undesired behavior by mutating thedict
.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, 0): x, (0, 1): y, (1, 2): 2*x + y}
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]
- multiplicative_order()#
Return the multiplicative order of this matrix, which must therefore be invertible.
Only implemented over finite fields and over \(\ZZ\).
EXAMPLES:
Over finite fields:
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: M = MatrixSpace(GF(11^2,'e'),5) sage: E = M.random_element() sage: while E.det() == 0: ....: E = M.random_element() sage: (E^E.multiplicative_order()).is_one() True
Over \(\ZZ\):
sage: m = matrix(ZZ,2,2,[-1,1,-1,0]) sage: m.multiplicative_order() 3 sage: m = posets.ChainPoset(6).coxeter_transformation() sage: m.multiplicative_order() 7 sage: P = posets.TamariLattice(4).coxeter_transformation() sage: P.multiplicative_order() 10 sage: M = matrix(ZZ, 2, 2, [1, 1, 0, 1]) sage: M.multiplicative_order() +Infinity sage: for k in range(600): ....: m = SL2Z.random_element() ....: o = m.multiplicative_order() ....: if o != Infinity and m**o != SL2Z.one(): ....: raise RuntimeError sage: m24 = matrix.companion(cyclotomic_polynomial(24)) sage: def val(i, j): ....: if i < j: ....: return 0 ....: elif i == j: ....: return 1 ....: else: ....: return ZZ.random_element(-100,100) sage: rnd = matrix(ZZ, 8, 8, val) sage: (rnd * m24 * rnd.inverse_of_unit()).multiplicative_order() 24
REFERENCES:
- mutate(k)#
Mutates
self
at row and column indexk
.Warning
Only makes sense if
self
is skew-symmetrizable.INPUT:
k
– integer at which row/columnself
is mutated.
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:
- ncols()#
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:
Naqi Jaffery (2006-01-24): examples
- nonpivots()#
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,)
- nonzero_positions(copy=True, column_order=False)#
Return the sorted list of pairs
(i,j)
such thatself[i,j] != 0
.INPUT:
copy
– (default:True
) it is safe to change the resulting list (unless you give the optioncopy=False
)column_order
– (default:False
) IfTrue
, returns the list of pairs(i,j)
such thatself[i,j] != 0
, but sorted by columns, i.e., columnj=0
entries occur first, then columnj=1
entries, etc.
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)]
- nonzero_positions_in_column(i)#
Return a sorted list of the integers
j
such thatself[j,i]
is nonzero, i.e., such that thej
-th position of thei
-th column is nonzero.INPUT:
i
– an integer
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 will 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
- nonzero_positions_in_row(i)#
Return the integers
j
such thatself[i,j]
is nonzero, i.e., such that thej
-th position of thei
-th row is nonzero.INPUT:
i
– an integer
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) []
- nrows()#
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:
Naqi Jaffery (2006-01-24): examples
- permute_columns(permutation)#
Permute the columns of
self
by applying the permutation group elementpermutation
.As permutation group elements act on integers \(\{1,\dots,n\}\), columns are considered numbered from 1 for this operation.
INPUT:
permutation
– aPermutationGroupElement
.
EXAMPLES: 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_rows(permutation)#
Permute the rows of
self
by applying the permutation group elementpermutation
.As permutation group elements act on integers \(\{1,\dots,n\}\), rows are considered numbered from 1 for this operation.
INPUT:
permutation
– aPermutationGroupElement
EXAMPLES: 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_rows_and_columns(row_permutation, column_permutation)#
Permute the rows and columns of
self
by applying the permutation group elementsrow_permutation
andcolumn_permutation
respectively.As permutation group elements act on integers \(\{1,\dots,n\}\), rows and columns are considered numbered from 1 for this operation.
INPUT:
row_permutation
– aPermutationGroupElement
column_permutation
– aPermutationGroupElement
OUTPUT:
A matrix.
EXAMPLES: 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]
- pivots()#
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 trac ticket #10752.
EXAMPLES:
sage: A = matrix(QQ, 2, 2, range(4)) sage: A.pivots() (0, 1)
- rank()#
Return the rank of this matrix.
EXAMPLES:
sage: m = matrix(GF(7),5,range(25)) sage: m.rank() 2
Rank is not implemented over the integers modulo a composite yet.:
sage: m = matrix(Integers(4), 2, [2,2,2,2]) sage: m.rank() Traceback (most recent call last): ... NotImplementedError: Echelon form not implemented over 'Ring of integers modulo 4'.
- rescale_col(i, s, start_row=0)#
Replace i-th col of self by s times i-th col of self.
INPUT:
i
- ith columns
- scalarstart_row
- only rescale entries at this row and lower
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]
- rescale_row(i, s, start_col=0)#
Replace i-th row of self by s times i-th row of self.
INPUT:
i
- ith rows
- scalarstart_col
- only rescale entries at this column and to the right
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]
- reverse_rows_and_columns()#
Reverse the row order and column order of this matrix.
This method transforms a matrix \(m_{i,j}\) with \(0 \leq i < nrows\) and \(0 \leq j < ncols\) into \(m_{nrows - i - 1, ncols - j - 1}\).
EXAMPLES:
sage: m = matrix(ZZ, 2, 2, range(4)) sage: m.reverse_rows_and_columns() sage: m [3 2] [1 0] sage: m = matrix(ZZ, 2, 3, range(6), sparse=True) sage: m.reverse_rows_and_columns() sage: m [5 4 3] [2 1 0] sage: m = matrix(ZZ, 3, 2, range(6), sparse=True) sage: m.reverse_rows_and_columns() sage: m [5 4] [3 2] [1 0] sage: m.reverse_rows_and_columns() sage: m [0 1] [2 3] [4 5] sage: m = matrix(QQ, 3, 2, [1/i for i in range(1,7)]) sage: m.reverse_rows_and_columns() sage: m [1/6 1/5] [1/4 1/3] [1/2 1] sage: R.<x,y> = ZZ['x,y'] sage: m = matrix(R, 3, 3, lambda i,j: x**i*y**j, sparse=True) sage: m.reverse_rows_and_columns() sage: m [x^2*y^2 x^2*y x^2] [ x*y^2 x*y x] [ y^2 y 1]
If the matrix is immutable, the method raises an error:
sage: m = matrix(ZZ, 2, [1, 3, -2, 4]) sage: m.set_immutable() sage: m.reverse_rows_and_columns() 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).
- set_col_to_multiple_of_col(i, j, s)#
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.
- set_immutable()#
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_to_multiple_of_row(i, j, s)#
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.
- str(rep_mapping=None, zero=None, plus_one=None, minus_one=None, unicode=False, shape=None, character_art=False)#
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 fromQQbar
are one example.If
rep_mapping
is callable then it will be called with elements of the matrix and must return a string. Simply callrepr()
on elements which should have the default representation.zero
- string (default:None
); if notNone
use the value ofzero
as the representation of the zero element.plus_one
- string (default:None
); if notNone
use the value ofplus_one
as the representation of the one element.minus_one
- string (default:None
); if notNone
use the value ofminus_one
as the representation of the negative of the one element.unicode
- boolean (default:False
). Whether to use Unicode symbols instead of ASCII symbols for brackets and subdivision lines.shape
- one of"square"
or"round"
(default:None
). Switches between round and square brackets. The default depends on the setting of theunicode
keyword argument. For Unicode symbols, the default is round brackets in accordance with the TeX rendering, while the ASCII rendering defaults to square brackets.character_art
– boolean (default:False
); ifTrue
, the result will be of typeAsciiArt
orUnicodeArt
which support line breaking of wide matrices that exceed the window width
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]' sage: M = matrix([[1,2,3],[4,5,6],[7,8,9]]) sage: M.subdivide(None, 2) sage: print(M.str(unicode=True)) ⎛1 2│3⎞ ⎜4 5│6⎟ ⎝7 8│9⎠ sage: M.subdivide([0,1,1,3], [0,2,3,3]) sage: print(M.str(unicode=True, shape="square")) ⎡┼───┼─┼┼⎤ ⎢│1 2│3││⎥ ⎢┼───┼─┼┼⎥ ⎢┼───┼─┼┼⎥ ⎢│4 5│6││⎥ ⎢│7 8│9││⎥ ⎣┼───┼─┼┼⎦
If
character_art
is set, the lines of large matrices are wrapped in a readable way:sage: set_random_seed(0) sage: matrix.random(RDF, 3, 5).str(unicode=True, character_art=True) ⎛ -0.27440062056807446 0.5031965950979831 -0.001975438590219314 ⎜ -0.05461130074681608 -0.033673314214051286 -0.9401270875197381 ⎝ 0.19906256610645512 0.3242250183948632 0.6026443545751128 -0.9467802263760512 0.5056889961514748⎞ -0.35104242112828943 0.5084492941557279⎟ -0.9541798283979341 -0.8948790563276592⎠
The number of floating point digits to display is controlled by
matrix.options.precision
and can also be set by the IPython magic%precision
. This does not affect the internal precision of the represented data, but only the textual display of matrices:sage: matrix.options.precision = 4 sage: A = matrix(RR, [[1/3, 200/3], [-3, 1e6]]); A [ 0.3333 66.67] [ -3.000 1.000E+6] sage: unicode_art(A) ⎛ 0.3333 66.67⎞ ⎝ -3.000 1.000E+6⎠ sage: matrix.options.precision = None sage: A [ 0.333333333333333 66.6666666666667] [ -3.00000000000000 1.00000000000000e6]
- swap_columns(c1, c2)#
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, r2)#
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]
- with_added_multiple_of_column(i, j, s, start_row=0)#
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]
- with_added_multiple_of_row(i, j, s, start_col=0)#
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]
- with_col_set_to_multiple_of_col(i, j, s)#
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]
- with_permuted_columns(permutation)#
Return the matrix obtained from permuting the columns of
self
by applying the permutation group elementpermutation
.As permutation group elements act on integers \(\{1,\dots,n\}\), columns are considered numbered from 1 for this operation.
INPUT:
permutation
, aPermutationGroupElement
OUTPUT:
A matrix.
EXAMPLES: 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]
- with_permuted_rows(permutation)#
Return the matrix obtained from permuting the rows of
self
by applying the permutation group elementpermutation
.As permutation group elements act on integers \(\{1,\dots,n\}\), rows are considered numbered from 1 for this operation.
INPUT:
permutation
– aPermutationGroupElement
OUTPUT:
A matrix.
EXAMPLES: 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]
- with_permuted_rows_and_columns(row_permutation, column_permutation)#
Return the matrix obtained from permuting the rows and columns of
self
by applying the permutation group elementsrow_permutation
andcolumn_permutation
.As permutation group elements act on integers \(\{1,\dots,n\}\), rows and columns are considered numbered from 1 for this operation.
INPUT:
row_permutation
– aPermutationGroupElement
column_permutation
– aPermutationGroupElement
OUTPUT:
A matrix.
EXAMPLES: 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]
- with_rescaled_col(i, s, start_row=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]
- with_rescaled_row(i, s, start_col=0)#
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]
- with_row_set_to_multiple_of_row(i, j, s)#
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]
- with_swapped_columns(c1, c2)#
Swap columns
c1
andc2
ofself
and return a new matrix.INPUT:
c1
,c2
- integers specifying columns ofself
to interchange
OUTPUT:
A new matrix, identical to
self
except that columnsc1
andc2
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
- with_swapped_rows(r1, r2)#
Swap rows
r1
andr2
ofself
and return a new matrix.INPUT:
r1
,r2
- integers specifying rows ofself
to interchange
OUTPUT:
A new matrix, identical to
self
except that rowsr1
andr2
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
- sage.matrix.matrix0.set_max_cols(n)#
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) doctest:...: DeprecationWarning: 'set_max_cols' is replaced by 'matrix.options.max_cols' See https://trac.sagemath.org/30552 for details.
- sage.matrix.matrix0.set_max_rows(n)#
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) doctest:...: DeprecationWarning: 'set_max_rows' is replaced by 'matrix.options.max_rows' See https://trac.sagemath.org/30552 for details.
- sage.matrix.matrix0.unpickle(cls, parent, immutability, cache, data, version)#
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.