32.6 Base class for matrices, part 1

Module: sage.matrix.matrix1

Base class for matrices, part 1

For design documentation see matrix/docs.py.

Class: Matrix

class Matrix

Functions: adjoint,$ \,$ augment,$ \,$ block_sum,$ \,$ column,$ \,$ columns,$ \,$ dense_columns,$ \,$ dense_matrix,$ \,$ dense_rows,$ \,$ lift,$ \,$ matrix_from_columns,$ \,$ matrix_from_rows,$ \,$ matrix_from_rows_and_columns,$ \,$ matrix_over_field,$ \,$ matrix_space,$ \,$ new_matrix,$ \,$ numpy,$ \,$ row,$ \,$ rows,$ \,$ set_column,$ \,$ set_row,$ \,$ sparse_columns,$ \,$ sparse_matrix,$ \,$ sparse_rows,$ \,$ stack,$ \,$ submatrix

adjoint( )

Returns the adjoint matrix of self (matrix of cofactors).

Input:

M
- a square matrix

Output:
N
- the adjoint matrix, such that N * M = M * N = M.parent(M.det())

ALGORITHM: Use PARI

sage: M = Matrix(ZZ,2,2,[5,2,3,4]) ; M
[5 2]
[3 4]
sage: N = M.adjoint() ; N
[ 4 -2]
[-3  5]
sage: M * N
[14  0]
[ 0 14]
sage: N * M
[14  0]
[ 0 14]
sage: M = Matrix(QQ,2,2,[5/3,2/56,33/13,41/10]) ; M
[  5/3  1/28]
[33/13 41/10]
sage: N = M.adjoint() ; N
[ 41/10  -1/28]
[-33/13    5/3]
sage: M * N
[7363/1092         0]
[        0 7363/1092]

TODO: Only implemented for matrices over ZZ or QQ PARI can deal with more general base rings

augment( )

Return the augmented matrix of the form [self | other].

sage: M = MatrixSpace(QQ,2,2)
sage: A = M([1,2, 3,4])
sage: A
[1 2]
[3 4]
sage: N = MatrixSpace(QQ,2,1)
sage: B = N([9,8])
sage: B
[9]
[8]
sage: A.augment(B)
[1 2 9]
[3 4 8]
sage: B.augment(A)
[9 1 2]
[8 3 4]
sage: M = MatrixSpace(QQ,3,4)
sage: A = M([1,2,3,4, 0,9,8,7, 2/3,3/4,4/5,9/8])
sage: A
[  1   2   3   4]
[  0   9   8   7]
[2/3 3/4 4/5 9/8]
sage: N = MatrixSpace(QQ,3,2)
sage: B = N([1,2, 3,4, 4,5])
sage: B
[1 2]
[3 4]
[4 5]
sage: A.augment(B)
[  1   2   3   4   1   2]
[  0   9   8   7   3   4]
[2/3 3/4 4/5 9/8   4   5]
sage: B.augment(A)
[  1   2   1   2   3   4]
[  3   4   0   9   8   7]
[  4   5 2/3 3/4 4/5 9/8]

Author: Naqi Jaffery (2006-01-24): examples

block_sum( )

Return the block matrix that has self and other on the diagonal: [self | 0 ] [ 0 | other ]

sage: A = matrix(QQ[['t']], 2, range(1, 5))
sage: A.block_sum(100*A)
[  1   2   0   0]
[  3   4   0   0]
[  0   0 100 200]
[  0   0 300 400]

column( )

Return the i-th column of this matrix as a vector.

This column is a dense vector if and only if the matrix is a dense matrix.

Input:

i
- integer
from_list
- bool (default: False); if true, returns the ith element of self.columns(), which may be faster, but requires building a list of all columns the first time it is called after an entry of the matrix is changed.

sage: a = matrix(2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: a.column(1)
(1, 4)

If the column is negative, it wraps around, just like with list indexing, e.g., -1 gives the right-most column:

sage: a.column(-1)
(2, 5)

TESTS:

sage: a = matrix(2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: a.column(3)
Traceback (most recent call last):
...
IndexError: column index out of range
sage: a.column(-4)
Traceback (most recent call last):
...
IndexError: column index out of range

columns( )

Return a list of the columns of self.

Input:

copy
- (default: True) if True, return a copy of the list of columns, which is safe to change.

If self is sparse, returns columns as sparse vectors, and if self is dense returns them as dense vectors.

dense_columns( )

Return list of the dense columns of self.

Input:

copy
- (default: True) if True, return a copy so you can modify it safely

An example over the integers:

sage: a = matrix(3,3,range(9)); a
[0 1 2]
[3 4 5]
[6 7 8]
sage: a.dense_columns()
[(0, 3, 6), (1, 4, 7), (2, 5, 8)]

We do an example over a polynomial ring:

sage: R.<x> = QQ[ ]
sage: a = matrix(R, 2, [x,x^2, 2/3*x,1+x^5]); a
[      x     x^2]
[  2/3*x x^5 + 1]
sage: a.dense_columns()
[(x, 2/3*x), (x^2, x^5 + 1)]
sage: a = matrix(R, 2, [x,x^2, 2/3*x,1+x^5], sparse=True)
sage: c = a.dense_columns(); c
[(x, 2/3*x), (x^2, x^5 + 1)]
sage: parent(c[1])
Ambient free module of rank 2 over the principal ideal domain Univariate
Polynomial Ring in x over Rational Field

dense_matrix( )

If this matrix is sparse, return a dense matrix with the same entries. If this matrix is dense, return this matrix (not a copy).

NOTE: The definition of"dense" and "sparse" in SAGE have nothing to do with the number of nonzero entries. Sparse and dense are properties of the underlying representation of the matrix.

sage: A = MatrixSpace(QQ,2, sparse=True)([1,2,0,1])
sage: A.is_sparse()
True
sage: B = A.dense_matrix()
sage: B.is_sparse()
False
sage: A*B
[1 4]
[0 1]
sage: A.parent()
Full MatrixSpace of 2 by 2 sparse matrices over Rational Field
sage: B.parent()
Full MatrixSpace of 2 by 2 dense matrices over Rational Field

In SAGE, the product of a sparse and a dense matrix is always dense:

sage: (A*B).parent()
Full MatrixSpace of 2 by 2 dense matrices over Rational Field
sage: (B*A).parent()
Full MatrixSpace of 2 by 2 dense matrices over Rational Field

dense_rows( )

Return list of the dense rows of self.

Input:

copy
- (default: True) if True, return a copy so you can modify it safely

sage: m = matrix(3, range(9)); m
[0 1 2]
[3 4 5]
[6 7 8]
sage: v = m.dense_rows(); v
[(0, 1, 2), (3, 4, 5), (6, 7, 8)]
sage: v is m.dense_rows()
False
sage: m.dense_rows(copy=False) is m.dense_rows(copy=False)
True
sage: m[0,0] = 10
sage: m.dense_rows()
[(10, 1, 2), (3, 4, 5), (6, 7, 8)]

lift( )

sage: M = Matrix(Integers(7), 2, 2, [5, 9, 13, 15]) ; M
[5 2]
[6 1]
sage: M.lift()
[5 2]
[6 1]
sage: parent(M.lift())
Full MatrixSpace of 2 by 2 dense matrices over Integer Ring

matrix_from_columns( )

Return the matrix constructed from self using columns with indices in the columns list.

sage: M = MatrixSpace(Integers(8),3,3)
sage: A = M(range(9)); A
[0 1 2]
[3 4 5]
[6 7 0]
sage: A.matrix_from_columns([2,1])
[2 1]
[5 4]
[0 7]

matrix_from_rows( )

Return the matrix constructed from self using rows with indices in the rows list.

sage: M = MatrixSpace(Integers(8),3,3)
sage: A = M(range(9)); A
[0 1 2]
[3 4 5]
[6 7 0]
sage: A.matrix_from_rows([2,1])
[6 7 0]
[3 4 5]

matrix_from_rows_and_columns( )

Return the matrix constructed from self from the given rows and columns.

sage: M = MatrixSpace(Integers(8),3,3)
sage: A = M(range(9)); A
[0 1 2]
[3 4 5]
[6 7 0]
sage: A.matrix_from_rows_and_columns([1], [0,2])
[3 5]
sage: A.matrix_from_rows_and_columns([1,2], [1,2])
[4 5]
[7 0]

Note that row and column indices can be reordered or repeated:

sage: A.matrix_from_rows_and_columns([2,1], [2,1])
[0 7]
[5 4]

For example here we take from row 1 columns 2 then 0 twice, and do this 3 times.

sage: A.matrix_from_rows_and_columns([1,1,1],[2,0,0])
[5 3 3]
[5 3 3]
[5 3 3]

Author Log:

matrix_over_field( )

Return copy of this matrix, but with entries viewed as elements of the fraction field of the base ring (assuming it is defined).

sage: A = MatrixSpace(IntegerRing(),2)([1,2,3,4])
sage: B = A.matrix_over_field()
sage: B
[1 2]
[3 4]
sage: B.parent()
Full MatrixSpace of 2 by 2 dense matrices over Rational Field

new_matrix( )

Create a matrix in the parent of this space with the given number of rows, columns, etc. The default parameters are the same as for self.

WARNING: This function called with no arguments returns the 0 matrix by default.

numpy( )

Return the Numpy matrix associated to this matrix.

Input: dtype - The desired data-type for the array. If not given, then the type will be determined as the minimum type required to hold the objects in the sequence.

sage: a = matrix(3,range(12))
sage: a.numpy()
array([[0, 1, 2, 3],
       [4, 5, 6, 7],
       [8, 9, 10, 11]], dtype=object)
sage: a.numpy('f')
array([[  0.,   1.,   2.,   3.],
       [  4.,   5.,   6.,   7.],
       [  8.,   9.,  10.,  11.]], dtype=float32)
sage: a.numpy('d')
array([[  0.,   1.,   2.,   3.],
       [  4.,   5.,   6.,   7.],
       [  8.,   9.,  10.,  11.]])
sage: a.numpy('B')
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]], dtype=uint8)

Type numpy.typecodes for a list of the possible typecodes:

sage: import numpy
sage: numpy.typecodes
{'All': '?bhilqpBHILQPfdgFDGSUVO', 'AllInteger': 'bBhHiIlLqQpP',
'AllFloat': 'fdgFDG', 'UnsignedInteger': 'BHILQP', 'Float': 'fdg',
'Character': 'S1', 'Complex': 'FDG', 'Integer': 'bhilqp'}

row( )

Return the i-th row of this matrix as a vector.

This row is a dense vector if and only if the matrix is a dense matrix.

Input:

i
- integer
from_list
- bool (default: False); if true, returns the ith element of self.rows(), which may be faster, but requires building a list of all rows the first time it is called after an entry of the matrix is changed.

sage: a = matrix(2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: a.row(0)
(0, 1, 2)
sage: a.row(1)
(3, 4, 5)
sage: a.row(-1)  # last row
(3, 4, 5)

TESTS:

sage: a = matrix(2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: a.row(2)
Traceback (most recent call last):
...
IndexError: row index out of range
sage: a.row(-3)
Traceback (most recent call last):
...
IndexError: row index out of range

rows( )

Return a list of the rows of self.

Input:

copy
- (default: True) if True, return a copy of the list of rows, which is safe to change.

If self is sparse, returns rows as sparse vectors, and if self is dense returns them as dense vectors.

set_column( )

Sets the entries of column col in self to be the entries of v.

sage: A = matrix([[1,2],[3,4]]); A
[1 2]
[3 4]
sage: A.set_column(0, [0,0]); A
[0 2]
[0 4]
sage: A.set_column(1, [0,0]); A
[0 0]
[0 0]
sage: A.set_column(2, [0,0]); A
Traceback (most recent call last):
...
IndexError: matrix index out of range

sage: A.set_column(0, [0,0,0])
Traceback (most recent call last):
...
ValueError: v must be of length 2

set_row( )

Sets the entries of row row in self to be the entries of v.

sage: A = matrix([[1,2],[3,4]]); A
[1 2]
[3 4]
sage: A.set_row(0, [0,0]); A
[0 0]
[3 4]
sage: A.set_row(1, [0,0]); A
[0 0]
[0 0]
sage: A.set_row(2, [0,0]); A
Traceback (most recent call last):
...
IndexError: matrix index out of range

sage: A.set_row(0, [0,0,0])
Traceback (most recent call last):
...
ValueError: v must be of length 2

sparse_columns( )

Return list of the sparse columns of self.

Input:

copy
- (default: True) if True, return a copy so you can modify it safely

sage: a = matrix(2,3,range(6)); a
[0 1 2]
[3 4 5]
sage: v = a.sparse_columns(); v
[(0, 3), (1, 4), (2, 5)]
sage: v[1].is_sparse()
True

sparse_matrix( )

If this matrix is dense, return a sparse matrix with the same entries. If this matrix is sparse, return this matrix (not a copy).

NOTE: The definition of "dense" and "sparse" in SAGE have nothing to do with the number of nonzero entries. Sparse and dense are properties of the underlying representation of the matrix.

sage: A = MatrixSpace(QQ,2, sparse=False)([1,2,0,1])
sage: A.is_sparse()
False
sage: B = A.sparse_matrix()
sage: B.is_sparse()
True
sage: A
[1 2]
[0 1]
sage: B
[1 2]
[0 1]
sage: A*B
[1 4]
[0 1]
sage: A.parent()
Full MatrixSpace of 2 by 2 dense matrices over Rational Field
sage: B.parent()
Full MatrixSpace of 2 by 2 sparse matrices over Rational Field
sage: (A*B).parent()
Full MatrixSpace of 2 by 2 dense matrices over Rational Field
sage: (B*A).parent()
Full MatrixSpace of 2 by 2 dense matrices over Rational Field

sparse_rows( )

Return list of the sparse rows of self.

Input:

copy
- (default: True) if True, return a copy so you can modify it safely

sage: m = Mat(ZZ,3,3,sparse=True)(range(9)); m
[0 1 2]
[3 4 5]
[6 7 8]
sage: v = m.sparse_rows(); v
[(0, 1, 2), (3, 4, 5), (6, 7, 8)]
sage: m.sparse_rows(copy=False) is m.sparse_rows(copy=False)
True
sage: v[1].is_sparse()
True
sage: m[0,0] = 10
sage: m.sparse_rows()
[(10, 1, 2), (3, 4, 5), (6, 7, 8)]

stack( )

Return the augmented matrix self on top of other: [ self ] [ other ]

sage: M = Matrix(QQ, 2, 3, range(6))
sage: N = Matrix(QQ, 1, 3, [10,11,12])
sage: M.stack(N)
[ 0  1  2]
[ 3  4  5]
[10 11 12]

Special Functions: _gap_init_,$ \,$ _magma_,$ \,$ _maple_init_,$ \,$ _mathematica_init_,$ \,$ _maxima_init_,$ \,$ _pari_init_,$ \,$ _singular_

_gap_init_( )

Returns a string defining a gap representation of self

sage: A = MatrixSpace(QQ,3,3)([0,1,2,3,4,5,6,7,8])
sage: g=gap(A)
sage: g
[ [ 0, 1, 2 ], [ 3, 4, 5 ], [ 6, 7, 8 ] ]
sage: g.CharacteristicPolynomial()
x_1^3-12*x_1^2-18*x_1
sage: A = MatrixSpace(CyclotomicField(4),2,2)([0,1,2,3])
sage: g=gap(A)
sage: g
[ [ !0, !1 ], [ !2, !3 ] ]
sage: g.IsMatrix()
true

_magma_( )

Return copy of this matrix in the given magma session.

We first coerce a square matrix.

sage: A = MatrixSpace(QQ,3)([1,2,3,4/3,5/3,6/4,7,8,9])
sage: B = magma(A); B                       # optional
[  1   2   3]
[4/3 5/3 3/2]
[  7   8   9]
sage: B.Type()                              # optional
AlgMatElt
sage: B.Parent()                            # optional
Full Matrix Algebra of degree 3 over Rational Field

We coerce a non-square matrix over $ \mathbf{Z}/8\mathbf{Z}$ .

sage: A = MatrixSpace(Integers(8),2,3)([-1,2,3,4,4,-2])   
sage: B = magma(A); B                       # optional
[7 2 3]
[4 4 6]
sage: B.Type()                              # optional
ModMatRngElt
sage: B.Parent()                            # optional
Full RMatrixSpace of 2 by 3 matrices over IntegerRing(8)

sage: R.<x,y> = QQ[]
sage: A = MatrixSpace(R,2,2)([x+y,x-1,y+5,x*y]) 
sage: B = magma(A); B                       # optional
[x + y x - 1]
[y + 5   x*y]

sage: R.<x,y> = ZZ[]
sage: A = MatrixSpace(R,2,2)([x+y,x-1,y+5,x*y]) 
sage: B = magma(A); B                       # optional
[x + y x - 1]
[y + 5   x*y]

We coerce a matrix over a cyclotomic field, where the generator must be named during the coercion.

sage: K = CyclotomicField(9) ; z = K.0
sage: M = matrix(K,3,3,[0,1,3,z,z**4,z-1,z**17,1,0])
sage: M
[                 0                  1                  3]
[             zeta9            zeta9^4          zeta9 - 1]
[-zeta9^5 - zeta9^2                  1                  0]
sage: magma(M)                             # optional -- requires magma
[                   0                    1                    3]
[              zeta_9             zeta_9^4           zeta_9 - 1]
[-zeta_9^5 - zeta_9^2                    1                    0]
sage: magma(M**2) == magma(M)**2           # optional -- requires magma
True

_maple_init_( )

sage: M = matrix(ZZ,2,range(4))             #optional
sage: maple(M)                              #optional
Matrix(2, 2, [[0,1],[2,3]])

sage: M = matrix(QQ,3,[1,2,3,4/3,5/3,6/4,7,8,9])    #optional
sage: maple(M)                                      #optional
Matrix(3, 3, [[1,2,3],[4/3,5/3,3/2],[7,8,9]])

sage: P.<x> = ZZ[]                          #optional
sage: M = matrix(P, 2, [-9*x^2-2*x+2, x-1, x^2+8*x, -3*x^2+5]) #optional
sage: maple(M)                             #optional
Matrix(2, 2, [[-9*x^2-2*x+2,x-1],[x^2+8*x,-3*x^2+5]])

_mathematica_init_( )

Return Mathematica string representation of this matrix.

sage: A = MatrixSpace(QQ,3)([1,2,3,4/3,5/3,6/4,7,8,9])
sage: g = mathematica(A); g                  # optional
{{1, 2, 3}, {4/3, 5/3, 3/2}, {7, 8, 9}}
sage: A._mathematica_init_()
'{{1/1, 2/1, 3/1}, {4/3, 5/3, 3/2}, {7/1, 8/1, 9/1}}'

sage: A = matrix([[1,2],[3,4]])
sage: g = mathematica(A); g                  # optional
{{1, 2}, {3, 4}}

sage: a = matrix([[pi, sin(x)], [cos(x), 1/e]]); a
[    pi sin(x)]
[cos(x)   e^-1]
sage: a._mathematica_init_()
'{{Pi, Sin[x]}, {Cos[x], (E) ^ (-1)}}'

_maxima_init_( )

Return string representation of this matrix in maxima.

sage: m = matrix(3,range(9)); m
[0 1 2]
[3 4 5]
[6 7 8]
sage: m._maxima_init_()
'matrix([0,1,2],[3,4,5],[6,7,8])'
sage: a = maxima(m); a
matrix([0,1,2],[3,4,5],[6,7,8])
sage: a.charpoly('x').expand()
-x^3+12*x^2+18*x
sage: m.charpoly()
x^3 - 12*x^2 - 18*x

_pari_init_( )

sage: R.<x> = QQ['x']
sage: a = matrix(R,2,[x+1,2/3,  x^2/2, 1+x^3]); a
[  x + 1     2/3]
[1/2*x^2 x^3 + 1]
sage: b = pari(a); b
[x + 1, 2/3; 1/2*x^2, x^3 + 1]
sage: a.determinant()
x^4 + x^3 - 1/3*x^2 + x + 1
sage: b.matdet()
x^4 + x^3 - 1/3*x^2 + x + 1

_singular_( )

Tries to coerce this matrix to a singular matrix.

See About this document... for information on suggesting changes.