32.1 Matrix Spaces

Module: sage.matrix.matrix_space

Matrix Spaces.

You can create any space Mat$ _{n\times m}(R)$ of either dense or sparse matrices with given number of rows and columns over any commutative or noncommutative ring.

sage: MS = MatrixSpace(QQ,6,6,sparse=True); MS
Full MatrixSpace of 6 by 6 sparse matrices over Rational Field
sage: MS.base_ring()
Rational Field
sage: MS = MatrixSpace(ZZ,3,5,sparse=False); MS
Full MatrixSpace of 3 by 5 dense matrices over Integer Ring

TESTS:

sage: matrix(RR,2,2,sparse=True)
[0.000000000000000 0.000000000000000]
[0.000000000000000 0.000000000000000]
sage: matrix(GF(11),2,2,sparse=True)
[0 0]
[0 0]

Module-level Functions

MatrixSpace( base_ring, nrows, [ncols=None], [sparse=False])

Create with the command

MatrixSpace(base_ring , nrows [, ncols] [, sparse])

The default value of the optional argument sparse is False. The default value of the optional argument ncols is nrows.

Input:

base_ring
- a ring
nrows
- int, the number of rows
ncols
- (default nrows) int, the number of columns
sparse
- (default false) whether or not matrices are given a sparse representation
Output: The unique space of all nrows x ncols matrices over base_ring.

sage: MS = MatrixSpace(RationalField(),2)
sage: MS.base_ring()
Rational Field
sage: MS.dimension()
4
sage: MS.dims()
(2, 2)
sage: B = MS.basis()
sage: B
[
[1 0]
[0 0],
[0 1]
[0 0],
[0 0]
[1 0],
[0 0]
[0 1]
]
sage: B[0]
[1 0]
[0 0]
sage: B[1]
[0 1]
[0 0]
sage: B[2]
[0 0]
[1 0]
sage: B[3]
[0 0]
[0 1]
sage: A = MS.matrix([1,2,3,4])
sage: A
[1 2]
[3 4]
sage: MS2 = MatrixSpace(RationalField(),2,3)
sage: B = MS2.matrix([1,2,3,4,5,6])
sage: A*B
[ 9 12 15]
[19 26 33]

sage: M = MatrixSpace(ZZ, 10)
sage: M
Full MatrixSpace of 10 by 10 dense matrices over Integer Ring
sage: loads(M.dumps()) == M
True

dict_to_list( entries, nrows, ncols)

Given a dictionary of coordinate tuples, return the list given by reading off the nrows*ncols matrix in row order.

EXAMLES:

sage: from sage.matrix.matrix_space import dict_to_list
sage: d = {}
sage: d[(0,0)] = 1
sage: d[(1,1)] = 2
sage: dict_to_list(d, 2, 2)
[1, 0, 0, 2]
sage: dict_to_list(d, 2, 3)
[1, 0, 0, 0, 2, 0]

is_MatrixSpace( x)

returns true if self is an instance of MatrixSpace returns false if self is not an instance of MatrixSpace

sage: MS = MatrixSpace(QQ,2)
sage: A = MS.random_element()
sage: is_MatrixSpace(MS)
True
sage: is_MatrixSpace(A)
False
sage: is_MatrixSpace(5)
False

list_to_dict( entries, nrows, ncols, [rows=True])

Given a list of entries, create a dictionary whose keys are coordinate tuples and values are the entries.

sage: from sage.matrix.matrix_space import list_to_dict
sage: d = list_to_dict([1,2,3,4],2,2)
sage: d[(0,1)]
2
sage: d = list_to_dict([1,2,3,4],2,2,rows=False)
sage: d[(0,1)]
3

Class: MatrixSpace_generic

class MatrixSpace_generic
The space of all nrows x ncols matrices over base_ring.

sage: MatrixSpace(ZZ,10,5)
Full MatrixSpace of 10 by 5 dense matrices over Integer Ring
sage: MatrixSpace(ZZ,10,2^33)
Traceback (most recent call last):                                   #
32-bit
...                                                                  #
32-bit
ValueError: number of rows and columns must be less than 2^32 (on a 32-bit
computer -- use a 64-bit computer for bigger matrices)    # 32-bit
Full MatrixSpace of 10 by 8589934592 dense matrices over Integer Ring   #
64-bit
MatrixSpace_generic( self, base_ring, nrows, [ncols=None], [sparse=False])

Functions: base_extend,$ \,$ basis,$ \,$ change_ring,$ \,$ column_space,$ \,$ construction,$ \,$ dimension,$ \,$ dims,$ \,$ gen,$ \,$ get_action_impl,$ \,$ identity_matrix,$ \,$ is_dense,$ \,$ is_sparse,$ \,$ matrix,$ \,$ matrix_space,$ \,$ ncols,$ \,$ ngens,$ \,$ nrows,$ \,$ random_element,$ \,$ row_space,$ \,$ zero_matrix

base_extend( self, R)

Return base extension of this matrix space to R.

Input:

R
- ring

Output: a matrix space

sage: Mat(ZZ,3,5).base_extend(QQ)
Full MatrixSpace of 3 by 5 dense matrices over Rational Field
sage: Mat(QQ,3,5).base_extend(GF(7))
Traceback (most recent call last):
...
TypeError: no base extension defined

basis( self)

Returns a basis for this matrix space.

WARNING: This will of course compute every generator of this matrix space. So for large matrices, this could take a long time, waste a massive amount of memory (for dense matrices), and is likely not very useful. Don't use this on large matrix spaces.

sage: Mat(ZZ,2,2).basis()
[
[1 0]
[0 0],
[0 1]
[0 0],
[0 0]
[1 0],
[0 0]
[0 1]
]

change_ring( self, R)

Return matrix space over R with otherwise same parameters as self.

Input:

R
- ring

Output: a matrix space

sage: Mat(QQ,3,5).change_ring(GF(7))
Full MatrixSpace of 3 by 5 dense matrices over Finite Field of size 7

column_space( self)

Return the module spanned by all columns of matrices in this matrix space. This is a free module of rank the number of columns. It will be sparse or dense as this matrix space is sparse or dense.

sage: M = Mat(GF(9,'a'),20,5,sparse=True); M.column_space()
Sparse vector space of dimension 20 over Finite Field in a of size 3^2

dimension( self)

Returns (m rows) * (n cols) of self as Integer

sage: MS = MatrixSpace(ZZ,4,6)
sage: u = MS.dimension()
sage: u - 24 == 0
True

dims( self)

Returns (m row, n col) representation of self dimension

sage: MS = MatrixSpace(ZZ,4,6)
sage: MS.dims()
(4, 6)

gen( self, n)

Return the n-th generator of this matrix space.

This doesn't compute all basis matrices, so it is reasonably intelligent.

sage: M = Mat(GF(7),10000,5); M.ngens()
50000
sage: a = M.10
sage: a[:4]
[0 0 0 0 0]
[0 0 0 0 0]
[1 0 0 0 0]
[0 0 0 0 0]

identity_matrix( self)

Create an identity matrix in self. (Must be a space of square matrices).

sage: MS1 = MatrixSpace(ZZ,4)
sage: MS2 = MatrixSpace(QQ,3,4)
sage: I = MS1.identity_matrix()
sage: I
[1 0 0 0]
[0 1 0 0]
[0 0 1 0]
[0 0 0 1]
sage: Er = MS2.identity_matrix()
Traceback (most recent call last):
...
TypeError: self must be a space of square matrices

is_dense( self)

Returns True if matrices in self are dense and False otherwise.

sage: Mat(RDF,2,3).is_sparse()
False
sage: Mat(RR,123456,22,sparse=True).is_sparse()
True

is_sparse( self)

Returns True if matrices in self are sparse and False otherwise.

sage: Mat(GF(2011),10000).is_sparse()
False
sage: Mat(GF(2011),10000,sparse=True).is_sparse()
True

matrix( self, [x=0], [coerce=True], [copy=True], [rows=True])

Create a matrix in self. The entries can be specified either as a single list of length nrows*ncols, or as a list of lists.

sage: M = MatrixSpace(ZZ, 2)
sage: M.matrix([[1,0],[0,-1]])
[ 1  0]
[ 0 -1]
sage: M.matrix([1,0,0,-1])
[ 1  0]
[ 0 -1]
sage: M.matrix([1,2,3,4])
[1 2]
[3 4]
sage: M.matrix([1,2,3,4],rows=False)
[1 3]
[2 4]

matrix_space( self, [nrows=None], [ncols=None], [sparse=False])

Return the matrix space with given number of rows, columns and sparcity over the same base ring as self, and defaults the same as self.

sage: M = Mat(GF(7),100,200)
sage: M.matrix_space(5000)
Full MatrixSpace of 5000 by 200 dense matrices over Finite Field of size 7
sage: M.matrix_space(ncols=5000)
Full MatrixSpace of 100 by 5000 dense matrices over Finite Field of size 7
sage: M.matrix_space(sparse=True)
Full MatrixSpace of 100 by 200 sparse matrices over Finite Field of size 7

ncols( self)

Return the number of columns of matrices in this space.

sage: M = Mat(ZZ['x'],200000,500000,sparse=True)
sage: M.ncols()
500000

ngens( self)

Return the number of generators of this matrix space, which is the number of entries in the matrices in this space.

sage: M = Mat(GF(7),100,200); M.ngens()
20000

nrows( self)

Return the number of rows of matrices in this space.

sage: M = Mat(ZZ,200000,500000)
sage: M.nrows()
200000

random_element( self, [density=1])

Input:

density
- integer (default: 1) rough measure of the proportion of nonzero entries in the random matrix
*args, **kwds
- rest of parameters may be passed to the random_element function of the base ring. ("may be", since this function calls the randomize function on the zero matrix, which need not call the random_element function of the base ring at all in general.)

sage: Mat(ZZ,2,5).random_element()
[ -8   2   0   0   1]
[ -1   2   1 -95  -1]
sage: Mat(QQ,2,5).random_element(density=0.5)
[  2   0   0   0   1]
[  0   0   0 1/2   0]
sage: Mat(QQ,3,sparse=True).random_element()
[  -1  1/3    1]
[   0   -1    0]
[  -1    1 -1/4]
sage: Mat(GF(9,'a'),3,sparse=True).random_element()
[      1       2       1]
[2*a + 1       a       2]
[      2 2*a + 2       1]

row_space( self)

Return the module spanned by all rows of matrices in this matrix space. This is a free module of rank the number of rows. It will be sparse or dense as this matrix space is sparse or dense.

sage: M = Mat(ZZ,20,5,sparse=False); M.row_space()
Ambient free module of rank 5 over the principal ideal domain Integer Ring

zero_matrix( self)

Return the zero matrix.

Special Functions: __call__,$ \,$ __cmp__,$ \,$ __init__,$ \,$ __iter__,$ \,$ __reduce__,$ \,$ _coerce_impl,$ \,$ _get_matrix_class,$ \,$ _latex_,$ \,$ _magma_init_,$ \,$ _repr_

__call__( self, [entries=0], [coerce=True], [copy=True], [rows=None])

sage: k = GF(7); G = MatrixGroup([matrix(k,2,[1,1,0,1]), matrix(k,2,[1,0,0,2])])
sage: g = G.0
sage: MatrixSpace(k,2)(g)
[1 1]
[0 1]

sage: MS = MatrixSpace(ZZ,2,4)
sage: M2 = MS(range(8)); M2
[0 1 2 3]
[4 5 6 7]
sage: M2.columns()
[(0, 4), (1, 5), (2, 6), (3, 7)]
sage: MS(M2.columns())
[0 1 2 3]
[4 5 6 7]
sage: M2 == MS(M2.columns())
True
sage: M2 == MS(M2.rows())
True

sage: MS = MatrixSpace(ZZ,2,4, sparse=True)
sage: M2 = MS(range(8)); M2
[0 1 2 3]
[4 5 6 7]
sage: M2.columns()
[(0, 4), (1, 5), (2, 6), (3, 7)]
sage: MS(M2.columns())
[0 1 2 3]
[4 5 6 7]
sage: M2 == MS(M2.columns())
True
sage: M2 == MS(M2.rows())
True

sage: MS = MatrixSpace(ZZ,2,2)
sage: MS([1,2,3,4])
[1 2]
[3 4]
sage: MS([1,2,3,4], rows=True)
[1 2]
[3 4]
sage: MS([1,2,3,4], rows=False)
[1 3]
[2 4]

sage: MS = MatrixSpace(ZZ,2,2, sparse=True)
sage: MS([1,2,3,4])
[1 2]
[3 4]
sage: MS([1,2,3,4], rows=True)
[1 2]
[3 4]
sage: MS([1,2,3,4], rows=False)
[1 3]
[2 4]

__cmp__( self, other)

Compare this matrix space with other. Sparse and dense matrix spaces with otherwise the same parameters are considered equal.

If other is not a matrix space, return something arbitrary but deterministic. Otherwise, compare based on base ring, then on number of rows and columns.

sage: Mat(ZZ,1000) == Mat(QQ,1000)
False
sage: Mat(ZZ,10) == Mat(ZZ,10)
True
sage: Mat(ZZ,10, sparse=False) == Mat(ZZ,10, sparse=True)
True

__iter__( self)

Returns a generator object which iterates through the elements of self. The order in which the elements are generated is based on a 'weight' of a matrix which is the number of iterations on the base ring that are required to reach that matrix.

The ordering is similar to a degree negative lexicographic order in monomials in a multivariate polynomial ring.

Consider the case of 2 x 2 matrices over GF(5).

sage: list( GF(5) )
[0, 1, 2, 3, 4]
sage: MS = MatrixSpace(GF(5), 2, 2)
sage: l = list(MS)

Then, consider the following matrices:

sage: A = MS([2,1,0,1]); A
[2 1]
[0 1]
sage: B = MS([1,2,1,0]); B
[1 2]
[1 0]
sage: C = MS([1,2,0,0]); C
[1 2]
[0 0]

A appears before B since the weight of one of A's entries exceeds the weight of the corresponding entry in B earliest in the list.

sage: l.index(A)
41
sage: l.index(B)
46

However, A would come after the matrix C since C has a lower weight than A.

sage: l.index(A)
41
sage: l.index(C)
19

The weights of matrices over other base rings are not as obvious. For example, the weight of

sage: MS = MatrixSpace(ZZ, 2, 2)
sage: MS([-1,0,0,0])
[-1  0]
[ 0  0]

is 2 since

sage: i = iter(ZZ)
sage: i.next()
0
sage: i.next()
1
sage: i.next()
-1

Some more examples:

            sage: MS = MatrixSpace(GF(2),2)
            sage: a = list(MS)
            sage: len(a)
            16
            sage: for m in a: print m, '
-'
            [0 0]
            [0 0] 
            -
            [1 0]
            [0 0] 
            -
            [0 1]
            [0 0] 
            -
            [0 0]
            [1 0] 
            -
            [0 0]
            [0 1] 
            -
            [1 1]
            [0 0] 
            -           
            [1 0]
            [1 0] 
            -
            [1 0]
            [0 1] 
            -
            [0 1]
            [1 0] 
            -
            [0 1]
            [0 1] 
            -
            [0 0]
            [1 1] 
            -
            [1 1]
            [1 0] 
            -
            [1 1]
            [0 1] 
            -
            [1 0]
            [1 1] 
            -
            [0 1]
            [1 1] 
            -
            [1 1]
            [1 1] 
            -

sage: MS = MatrixSpace(GF(2),2, 3)
sage: a = list(MS)
sage: len(a)
64
sage: a[0]
[0 0 0]
[0 0 0]

sage: MS = MatrixSpace(ZZ, 2, 3)
sage: i = iter(MS)
sage: a = [ i.next() for _ in range(6) ]
sage: a[0]
[0 0 0]
[0 0 0]
sage: a[4]
[0 0 0]
[1 0 0]

For degenerate cases, where either the number of rows or columns (or both) are zero, then the single element of the space is returned.

sage: list( MatrixSpace(GF(2), 2, 0) )
[[]]
sage: list( MatrixSpace(GF(2), 0, 2) )
[[]]
sage: list( MatrixSpace(GF(2), 0, 0) )
[[]]

If the base ring does not support iteration (for example, with the reals), then the matrix space over that ring does not support iteration either.

sage: MS = MatrixSpace(RR, 2)
sage: a = list(MS)
Traceback (most recent call last):
...
NotImplementedError: object does not support iteration

__reduce__( self)

sage: A = Mat(ZZ,5,7,sparse=True)
sage: A
Full MatrixSpace of 5 by 7 sparse matrices over Integer Ring
sage: loads(dumps(A)) == A
True

_coerce_impl( self, x)

sage: MS1 = MatrixSpace(QQ,3)
sage: MS2 = MatrixSpace(ZZ,4,5,true)
sage: A = MS1(range(9))
sage: D = MS2(range(20))
sage: MS1._coerce_(A)
[0 1 2]
[3 4 5]
[6 7 8]
sage: MS2._coerce_(D)
[ 0  1  2  3  4]
[ 5  6  7  8  9]
[10 11 12 13 14]
[15 16 17 18 19]

_get_matrix_class( self)

Returns the class of self

sage: MS1 = MatrixSpace(QQ,4)
sage: MS2 = MatrixSpace(ZZ,4,5,true)
sage: MS1._get_matrix_class()
<type 'sage.matrix.matrix_rational_dense.Matrix_rational_dense'>
sage: MS2._get_matrix_class()
<type 'sage.matrix.matrix_integer_sparse.Matrix_integer_sparse'>
sage: type(matrix(SR, 2, 2, 0))
<type 'sage.matrix.matrix_symbolic_dense.Matrix_symbolic_dense'>

_latex_( self)

Returns the latex representation of a MatrixSpace

sage: MS3 = MatrixSpace(QQ,6,6,true)
sage: latex(MS3)
\mbox{\rm Mat}_{6\times 6}(\mathbf{Q})

_magma_init_( self)

We first coerce a square matrix.

sage: magma(MatrixSpace(QQ,3))                      # optional
Full Matrix Algebra of degree 3 over Rational Field

sage: magma(MatrixSpace(Integers(8),2,3))           # optional
Full RMatrixSpace of 2 by 3 matrices over IntegerRing(8)

_repr_( self)

Returns the string representation of a MatrixSpace

sage: MS = MatrixSpace(ZZ,2,4,true)
sage: repr(MS)
'Full MatrixSpace of 2 by 4 sparse matrices over Integer Ring'
sage: MS
Full MatrixSpace of 2 by 4 sparse matrices over Integer Ring

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