Base class for matrices, part 1¶
For design documentation see sage.matrix.docs
.

class
sage.matrix.matrix1.
Matrix
¶ Bases:
sage.matrix.matrix0.Matrix

augment
(right, subdivide=False)¶ Returns a new matrix formed by appending the matrix (or vector)
right
on the right side ofself
.INPUT:
right
 a matrix, vector or free module element, whose dimensions are compatible withself
.subdivide
 default:False
 request the resulting matrix to have a new subdivision, separatingself
fromright
.
OUTPUT:
A new matrix formed by appending
right
onto the right side ofself
. Ifright
is a vector (or free module element) then in this context it is appropriate to consider it as a column vector. (The code first converts a vector to a 1column matrix.)If
subdivide
isTrue
then any column subdivisions for the two matrices are preserved, and a new subdivision is added betweenself
andright
. If the row divisions are identical, then they are preserved, otherwise they are discarded. Whensubdivide
isFalse
there is no subdivision information in the result.Warning
If
subdivide
isTrue
then unequal row subdivisions will be discarded, since it would be ambiguous how to interpret them. If the subdivision behavior is not what you need, you can manage subdivisions yourself with methods likeget_subdivisions()
andsubdivide()
. You might also findblock_matrix()
orblock_diagonal_matrix()
useful and simpler in some instances.EXAMPLES:
Augmenting with a matrix.
sage: A = matrix(QQ, 3, range(12)) sage: B = matrix(QQ, 3, range(9)) sage: A.augment(B) [ 0 1 2 3 0 1 2] [ 4 5 6 7 3 4 5] [ 8 9 10 11 6 7 8]
Augmenting with a vector.
sage: A = matrix(QQ, 2, [0, 2, 4, 6, 8, 10]) sage: v = vector(QQ, 2, [100, 200]) sage: A.augment(v) [ 0 2 4 100] [ 6 8 10 200]
Errors are raised if the sizes are incompatible.
sage: A = matrix(RR, [[1, 2],[3, 4]]) sage: B = matrix(RR, [[10, 20], [30, 40], [50, 60]]) sage: A.augment(B) Traceback (most recent call last): ... TypeError: number of rows must be the same, 2 != 3 sage: v = vector(RR, [100, 200, 300]) sage: A.augment(v) Traceback (most recent call last): ... TypeError: number of rows must be the same, 2 != 3
Setting
subdivide
toTrue
will, in its simplest form, add a subdivision betweenself
andright
.sage: A = matrix(QQ, 3, range(12)) sage: B = matrix(QQ, 3, range(15)) sage: A.augment(B, subdivide=True) [ 0 1 2 3 0 1 2 3 4] [ 4 5 6 7 5 6 7 8 9] [ 8 9 10 1110 11 12 13 14]
Column subdivisions are preserved by augmentation, and enriched, if subdivisions are requested. (So multiple augmentations can be recorded.)
sage: A = matrix(QQ, 3, range(6)) sage: A.subdivide(None, [1]) sage: B = matrix(QQ, 3, range(9)) sage: B.subdivide(None, [2]) sage: A.augment(B, subdivide=True) [010 12] [233 45] [456 78]
Row subdivisions can be preserved, but only if they are identical. Otherwise, this information is discarded and must be managed separately.
sage: A = matrix(QQ, 3, range(6)) sage: A.subdivide([1,3], None) sage: B = matrix(QQ, 3, range(9)) sage: B.subdivide([1,3], None) sage: A.augment(B, subdivide=True) [0 10 1 2] [+] [2 33 4 5] [4 56 7 8] [+] sage: A.subdivide([1,2], None) sage: A.augment(B, subdivide=True) [0 10 1 2] [2 33 4 5] [4 56 7 8]
The result retains the base ring of
self
by coercing the elements ofright
into the base ring ofself
.sage: A = matrix(QQ, 2, [1,2]) sage: B = matrix(RR, 2, [sin(1.1), sin(2.2)]) sage: C = A.augment(B); C [ 1 183017397/205358938] [ 2 106580492/131825561] sage: C.parent() Full MatrixSpace of 2 by 2 dense matrices over Rational Field sage: D = B.augment(A); D [0.89120736006... 1.00000000000000] [0.80849640381... 2.00000000000000] sage: D.parent() Full MatrixSpace of 2 by 2 dense matrices over Real Field with 53 bits of precision
Sometimes it is not possible to coerce into the base ring of
self
. A solution is to change the base ring ofself
to a more expansive ring. Here we mix the rationals with a ring of polynomials with rational coefficients.sage: R.<y> = PolynomialRing(QQ) sage: A = matrix(QQ, 1, [1,2]) sage: B = matrix(R, 1, [y, y^2]) sage: C = B.augment(A); C [ y y^2 1 2] sage: C.parent() Full MatrixSpace of 1 by 4 dense matrices over Univariate Polynomial Ring in y over Rational Field sage: D = A.augment(B) Traceback (most recent call last): ... TypeError: not a constant polynomial sage: E = A.change_ring(R) sage: F = E.augment(B); F [ 1 2 y y^2] sage: F.parent() Full MatrixSpace of 1 by 4 dense matrices over Univariate Polynomial Ring in y over Rational Field
AUTHORS:
 Naqi Jaffery (20060124): examples
 Rob Beezer (20101207): vector argument, docstring, subdivisions

block_sum
(other)¶ Return the block matrix that has self and other on the diagonal:
[ self 0 ] [ 0 other ]
EXAMPLES:
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
(i, from_list=False)¶ 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
 integerfrom_list
 bool (default: False); if true, returns thei
’th element ofself.columns()
(seecolumns()
), 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.
EXAMPLES:
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 rightmost column:
sage: a.column(1) (2, 5)

columns
(copy=True)¶ 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 a sparse matrix, columns are returned as sparse vectors, otherwise returned vectors are dense.EXAMPLES:
sage: matrix(3, [1..9]).columns() [(1, 4, 7), (2, 5, 8), (3, 6, 9)] sage: matrix(RR, 2, [sqrt(2), pi, exp(1), 0]).columns() [(1.41421356237310, 2.71828182845905), (3.14159265358979, 0.000000000000000)] sage: matrix(RR, 0, 2, []).columns() [(), ()] sage: matrix(RR, 2, 0, []).columns() [] sage: m = matrix(RR, 3, 3, {(1,2): pi, (2, 2): 1, (0,1): sqrt(2)}) sage: parent(m.columns()[0]) Sparse vector space of dimension 3 over Real Field with 53 bits of precision
Sparse matrices produce sparse columns.
sage: A = matrix(QQ, 2, range(4), sparse=True) sage: v = A.columns()[0] sage: v.is_sparse() True

delete_columns
(dcols, check=True)¶ Return the matrix constructed from deleting the columns with indices in the
dcols
list.INPUT:
dcols
 list of indices of columns to be deleted from self.check
 checks whether any index indcols
is out of range. Defaults toTrue
.
See also
The methods
delete_rows()
andmatrix_from_columns()
are related.EXAMPLES:
sage: A = Matrix(3,4,range(12)); A [ 0 1 2 3] [ 4 5 6 7] [ 8 9 10 11] sage: A.delete_columns([0,2]) [ 1 3] [ 5 7] [ 9 11]
dcols
can be a tuple. But only the underlying set of indices matters.sage: A.delete_columns((2,0,2)) [ 1 3] [ 5 7] [ 9 11]
The default is to check whether any index in
dcols
is out of range.sage: A.delete_columns([1,2,4]) Traceback (most recent call last): ... IndexError: [1, 4] contains invalid indices sage: A.delete_columns([1,2,4], check=False) [ 0 1 3] [ 4 5 7] [ 8 9 11]
AUTHORS:
 Wai Yan Pong (20120305)

delete_rows
(drows, check=True)¶ Return the matrix constructed from deleting the rows with indices in the
drows
list.INPUT:
drows
 list of indices of rows to be deleted from self.check
 checks whether any index indrows
is out of range. Defaults toTrue
.
See also
The methods
delete_columns()
andmatrix_from_rows()
are related.EXAMPLES:
sage: A = Matrix(4,3,range(12)); A [ 0 1 2] [ 3 4 5] [ 6 7 8] [ 9 10 11] sage: A.delete_rows([0,2]) [ 3 4 5] [ 9 10 11]
drows
can be a tuple. But only the underlying set of indices matters.sage: A.delete_rows((2,0,2)) [ 3 4 5] [ 9 10 11]
The default is to check whether the any index in
drows
is out of range.sage: A.delete_rows([1,2,4]) Traceback (most recent call last): ... IndexError: [1, 4] contains invalid indices sage: A.delete_rows([1,2,4], check=False) [ 0 1 2] [ 3 4 5] [ 9 10 11]

dense_columns
(copy=True)¶ Return list of the dense columns of self.
INPUT:
copy
 (default: True) if True, return a copy so you can modify it safely
EXAMPLES:
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.
EXAMPLES:
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 True sage: B.dense_matrix() is B True 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
(copy=True)¶ Return list of the dense rows of self.
INPUT:
copy
 (default: True) if True, return a copy so you can modify it safely (note that the individual vectors in the copy should not be modified since they are mutable!)
EXAMPLES:
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
()¶ Return lift of self to the covering ring of the base ring R, which is by definition the ring returned by calling cover_ring() on R, or just R itself if the cover_ring method is not defined.
EXAMPLES:
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
The field QQ doesn’t have a cover_ring method:
sage: hasattr(QQ, 'cover_ring') False
So lifting a matrix over QQ gives back the same exact matrix.
sage: B = matrix(QQ, 2, [1..4]) sage: B.lift() [1 2] [3 4] sage: B.lift() is B True

lift_centered
()¶ Apply the lift_centered method to every entry of self.
OUTPUT:
If self is a matrix over the Integers mod \(n\), this method returns the unique matrix \(m\) such that \(m\) is congruent to self mod \(n\) and for every entry \(m[i,j]\) we have \(n/2 < m[i,j] \leq n/2\). If the coefficient ring does not have a cover_ring method, return self.
EXAMPLES:
sage: M = Matrix(Integers(8), 2, 4, range(8)) ; M [0 1 2 3] [4 5 6 7] sage: L = M.lift_centered(); L [ 0 1 2 3] [ 4 3 2 1] sage: parent(L) Full MatrixSpace of 2 by 4 dense matrices over Integer Ring
The returned matrix is congruent to M modulo 8.:
sage: L.mod(8) [0 1 2 3] [4 5 6 7]
The field QQ doesn’t have a cover_ring method:
sage: hasattr(QQ, 'cover_ring') False
So lifting a matrix over QQ gives back the same exact matrix.
sage: B = matrix(QQ, 2, [1..4]) sage: B.lift_centered() [1 2] [3 4] sage: B.lift_centered() is B True

matrix_from_columns
(columns)¶ Return the matrix constructed from self using columns with indices in the columns list.
EXAMPLES:
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
(rows)¶ Return the matrix constructed from self using rows with indices in the rows list.
EXAMPLES:
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
(rows, columns)¶ Return the matrix constructed from self from the given rows and columns.
EXAMPLES:
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]
AUTHORS:
 Jaap Spies (20060218)
 Didier Deshommes: some Pyrex speedups implemented

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).
EXAMPLES:
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

matrix_space
(nrows=None, ncols=None, sparse=None)¶ Return the ambient matrix space of self.
INPUT:
nrows
,ncols
 (optional) number of rows and columns in returned matrix space.sparse
 whether the returned matrix space uses sparse or dense matrices.
EXAMPLES:
sage: m = matrix(3, [1..9]) sage: m.matrix_space() Full MatrixSpace of 3 by 3 dense matrices over Integer Ring sage: m.matrix_space(ncols=2) Full MatrixSpace of 3 by 2 dense matrices over Integer Ring sage: m.matrix_space(1) Full MatrixSpace of 1 by 3 dense matrices over Integer Ring sage: m.matrix_space(1, 2, True) Full MatrixSpace of 1 by 2 sparse matrices over Integer Ring sage: M = MatrixSpace(QQ, 3, implementation='generic') sage: m = M.an_element() sage: m.matrix_space() Full MatrixSpace of 3 by 3 dense matrices over Rational Field (using Matrix_generic_dense) sage: m.matrix_space(nrows=2, ncols=12) Full MatrixSpace of 2 by 12 dense matrices over Rational Field (using Matrix_generic_dense) sage: m.matrix_space(nrows=2, sparse=True) Full MatrixSpace of 2 by 3 sparse matrices over Rational Field

new_matrix
(nrows=None, ncols=None, entries=None, coerce=True, copy=True, sparse=None)¶ Create a matrix in the parent of this matrix with the given number of rows, columns, etc. The default parameters are the same as for self.
INPUT:
These three variables get sent to
matrix_space()
:nrows
,ncols
 number of rows and columns in returned matrix. If not specified, defaults toNone
and will give a matrix of the same size as self.sparse
 whether returned matrix is sparse or not. Defaults to same value as self.
The remaining three variables (
coerce
,entries
, andcopy
) are used bysage.matrix.matrix_space.MatrixSpace()
to construct the new matrix.Warning
This function called with no arguments returns the zero matrix of the same dimension and sparseness of self.
EXAMPLES:
sage: A = matrix(ZZ,2,2,[1,2,3,4]); A [1 2] [3 4] sage: A.new_matrix() [0 0] [0 0] sage: A.new_matrix(1,1) [0] sage: A.new_matrix(3,3).parent() Full MatrixSpace of 3 by 3 dense matrices over Integer Ring
sage: A = matrix(RR,2,3,[1.1,2.2,3.3,4.4,5.5,6.6]); A [1.10000000000000 2.20000000000000 3.30000000000000] [4.40000000000000 5.50000000000000 6.60000000000000] sage: A.new_matrix() [0.000000000000000 0.000000000000000 0.000000000000000] [0.000000000000000 0.000000000000000 0.000000000000000] sage: A.new_matrix().parent() Full MatrixSpace of 2 by 3 dense matrices over Real Field with 53 bits of precision
sage: M = MatrixSpace(ZZ, 2, 3, implementation='generic') sage: m = M.an_element() sage: m.new_matrix().parent() Full MatrixSpace of 2 by 3 dense matrices over Integer Ring (using Matrix_generic_dense) sage: m.new_matrix(3,3).parent() Full MatrixSpace of 3 by 3 dense matrices over Integer Ring (using Matrix_generic_dense) sage: m.new_matrix(3,3, sparse=True).parent() Full MatrixSpace of 3 by 3 sparse matrices over Integer Ring

numpy
(dtype=None)¶ Return the Numpy matrix associated to this matrix.
INPUT:
dtype
 The desired datatype for the array. If not given, then the type will be determined as the minimum type required to hold the objects in the sequence.
EXAMPLES:
sage: a = matrix(3,range(12)) sage: a.numpy() array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11]]) 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: sorted(numpy.typecodes.items()) [('All', '?bhilqpBHILQPefdgFDGSUVOMm'), ('AllFloat', 'efdgFDG'), ('AllInteger', 'bBhHiIlLqQpP'), ('Character', 'c'), ('Complex', 'FDG'), ('Datetime', 'Mm'), ('Float', 'efdg'), ('Integer', 'bhilqp'), ('UnsignedInteger', 'BHILQP')]
Alternatively, numpy automatically calls this function (via the magic
__array__()
method) to convert Sage matrices to numpy arrays:sage: import numpy sage: b=numpy.array(a); b array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11]]) sage: b.dtype dtype('int32') # 32bit dtype('int64') # 64bit sage: b.shape (3, 4)

row
(i, from_list=False)¶ 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
 integerfrom_list
 bool (default: False); if true, returns thei
’th element ofself.rows()
(seerows()
), 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.
EXAMPLES:
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)

rows
(copy=True)¶ 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 a sparse matrix, rows are returned as sparse vectors, otherwise returned vectors are dense.EXAMPLES:
sage: matrix(3, [1..9]).rows() [(1, 2, 3), (4, 5, 6), (7, 8, 9)] sage: matrix(RR, 2, [sqrt(2), pi, exp(1), 0]).rows() [(1.41421356237310, 3.14159265358979), (2.71828182845905, 0.000000000000000)] sage: matrix(RR, 0, 2, []).rows() [] sage: matrix(RR, 2, 0, []).rows() [(), ()] sage: m = matrix(RR, 3, 3, {(1,2): pi, (2, 2): 1, (0,1): sqrt(2)}) sage: parent(m.rows()[0]) Sparse vector space of dimension 3 over Real Field with 53 bits of precision
Sparse matrices produce sparse rows.
sage: A = matrix(QQ, 2, range(4), sparse=True) sage: v = A.rows()[0] sage: v.is_sparse() True

set_column
(col, v)¶ Sets the entries of column
col
to the entries ofv
.INPUT:
col
 index of column to be set.v
 a list or vector of the new entries.
OUTPUT:
Changes the matrix inplace, so there is no output.
EXAMPLES:
New entries may be contained in a vector.:
sage: A = matrix(QQ, 5, range(25)) sage: u = vector(QQ, [0, 1, 2, 3, 4]) sage: A.set_column(2, u) sage: A [ 0 1 0 3 4] [ 5 6 1 8 9] [10 11 2 13 14] [15 16 3 18 19] [20 21 4 23 24]
New entries may be in any sort of list.:
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]

set_row
(row, v)¶ Sets the entries of row
row
to the entries ofv
.INPUT:
row
 index of row to be set.v
 a list or vector of the new entries.
OUTPUT:
Changes the matrix inplace, so there is no output.
EXAMPLES:
New entries may be contained in a vector.:
sage: A = matrix(QQ, 5, range(25)) sage: u = vector(QQ, [0, 1, 2, 3, 4]) sage: A.set_row(2, u) sage: A [ 0 1 2 3 4] [ 5 6 7 8 9] [ 0 1 2 3 4] [15 16 17 18 19] [20 21 22 23 24]
New entries may be in any sort of list.:
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]

sparse_columns
(copy=True)¶ Return a list of the columns of
self
as sparse vectors (or free module elements).INPUT:
copy
 (default: True) if True, return a copy so you can modify it safely
EXAMPLES:
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.
EXAMPLES:
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 == B True sage: B.sparse_matrix() is B True 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
(copy=True)¶ Return a list of the rows of
self
as sparse vectors (or free module elements).INPUT:
copy
 (default: True) if True, return a copy so you can modify it safely
EXAMPLES:
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
(bottom, subdivide=False)¶ Return a new matrix formed by appending the matrix (or vector)
bottom
belowself
:[ self ] [ bottom ]
INPUT:
bottom
 a matrix, vector or free module element, whose dimensions are compatible withself
.subdivide
 default:False
 request the resulting matrix to have a new subdivision, separatingself
frombottom
.
OUTPUT:
A new matrix formed by appending
bottom
beneathself
. Ifbottom
is a vector (or free module element) then in this context it is appropriate to consider it as a row vector. (The code first converts a vector to a 1row matrix.)If
subdivide
isTrue
then any row subdivisions for the two matrices are preserved, and a new subdivision is added betweenself
andbottom
. If the column divisions are identical, then they are preserved, otherwise they are discarded. Whensubdivide
isFalse
there is no subdivision information in the result.Warning
If
subdivide
isTrue
then unequal column subdivisions will be discarded, since it would be ambiguous how to interpret them. If the subdivision behavior is not what you need, you can manage subdivisions yourself with methods likesubdivisions()
andsubdivide()
. You might also findblock_matrix()
orblock_diagonal_matrix()
useful and simpler in some instances.EXAMPLES:
Stacking with a matrix.
sage: A = matrix(QQ, 4, 3, range(12)) sage: B = matrix(QQ, 3, 3, range(9)) sage: A.stack(B) [ 0 1 2] [ 3 4 5] [ 6 7 8] [ 9 10 11] [ 0 1 2] [ 3 4 5] [ 6 7 8]
Stacking with a vector.
sage: A = matrix(QQ, 3, 2, [0, 2, 4, 6, 8, 10]) sage: v = vector(QQ, 2, [100, 200]) sage: A.stack(v) [ 0 2] [ 4 6] [ 8 10] [100 200]
Errors are raised if the sizes are incompatible.
sage: A = matrix(RR, [[1, 2],[3, 4]]) sage: B = matrix(RR, [[10, 20, 30], [40, 50, 60]]) sage: A.stack(B) Traceback (most recent call last): ... TypeError: number of columns must be the same, not 2 and 3 sage: v = vector(RR, [100, 200, 300]) sage: A.stack(v) Traceback (most recent call last): ... TypeError: number of columns must be the same, not 2 and 3
Setting
subdivide
toTrue
will, in its simplest form, add a subdivision betweenself
andbottom
.sage: A = matrix(QQ, 2, 5, range(10)) sage: B = matrix(QQ, 3, 5, range(15)) sage: A.stack(B, subdivide=True) [ 0 1 2 3 4] [ 5 6 7 8 9] [] [ 0 1 2 3 4] [ 5 6 7 8 9] [10 11 12 13 14]
Row subdivisions are preserved by stacking, and enriched, if subdivisions are requested. (So multiple stackings can be recorded.)
sage: A = matrix(QQ, 2, 4, range(8)) sage: A.subdivide([1], None) sage: B = matrix(QQ, 3, 4, range(12)) sage: B.subdivide([2], None) sage: A.stack(B, subdivide=True) [ 0 1 2 3] [] [ 4 5 6 7] [] [ 0 1 2 3] [ 4 5 6 7] [] [ 8 9 10 11]
Column subdivisions can be preserved, but only if they are identical. Otherwise, this information is discarded and must be managed separately.
sage: A = matrix(QQ, 2, 5, range(10)) sage: A.subdivide(None, [2,4]) sage: B = matrix(QQ, 3, 5, range(15)) sage: B.subdivide(None, [2,4]) sage: A.stack(B, subdivide=True) [ 0 1 2 3 4] [ 5 6 7 8 9] [++] [ 0 1 2 3 4] [ 5 6 7 8 9] [10 1112 1314] sage: A.subdivide(None, [1,2]) sage: A.stack(B, subdivide=True) [ 0 1 2 3 4] [ 5 6 7 8 9] [] [ 0 1 2 3 4] [ 5 6 7 8 9] [10 11 12 13 14]
The base ring of the result is the common parent for the base rings of
self
andbottom
. In particular, the parent forA.stack(B)
andB.stack(A)
should be equal:sage: A = matrix(QQ, 1, 2, [1,2]) sage: B = matrix(RR, 1, 2, [sin(1.1), sin(2.2)]) sage: C = A.stack(B); C [ 1.00000000000000 2.00000000000000] [0.891207360061435 0.808496403819590] sage: C.parent() Full MatrixSpace of 2 by 2 dense matrices over Real Field with 53 bits of precision sage: D = B.stack(A); D [0.891207360061435 0.808496403819590] [ 1.00000000000000 2.00000000000000] sage: D.parent() Full MatrixSpace of 2 by 2 dense matrices over Real Field with 53 bits of precision
sage: R.<y> = PolynomialRing(ZZ) sage: A = matrix(QQ, 1, 2, [1, 2/3]) sage: B = matrix(R, 1, 2, [y, y^2]) sage: C = A.stack(B); C [ 1 2/3] [ y y^2] sage: C.parent() Full MatrixSpace of 2 by 2 dense matrices over Univariate Polynomial Ring in y over Rational Field
Stacking a dense matrix atop a sparse one returns a sparse matrix:
sage: M = Matrix(ZZ, 2, 3, range(6), sparse=False) sage: N = diagonal_matrix([10,11,12], sparse=True) sage: P = M.stack(N); P [ 0 1 2] [ 3 4 5] [10 0 0] [ 0 11 0] [ 0 0 12] sage: P.is_sparse() True sage: P = N.stack(M); P [10 0 0] [ 0 11 0] [ 0 0 12] [ 0 1 2] [ 3 4 5] sage: P.is_sparse() True
One can stack matrices over different rings (trac ticket #16399).
sage: M = Matrix(ZZ, 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] sage: N.stack(M) [10 11 12] [ 0 1 2] [ 3 4 5]
AUTHORS:
 Rob Beezer (20110319): rewritten to mirror code for
augment()
 Jeroen Demeyer (20150106): refactor, see trac ticket #16399.
Put all boilerplate in one place (here) and put the actual
typedependent implementation in
_stack_impl
.

submatrix
(row=0, col=0, nrows=1, ncols=1)¶ Return the matrix constructed from self using the specified range of rows and columns.
INPUT:
row
,col
 index of the starting row and column. Indices start at zero.nrows
,ncols
 (optional) number of rows and columns to take. If not provided, take all rows below and all columns to the right of the starting entry.
See also
The functions
matrix_from_rows()
,matrix_from_columns()
, andmatrix_from_rows_and_columns()
allow one to select arbitrary subsets of rows and/or columns.EXAMPLES:
Take the \(3 \times 3\) submatrix starting from entry (1,1) in a \(4 \times 4\) matrix:
sage: m = matrix(4, [1..16]) sage: m.submatrix(1, 1) [ 6 7 8] [10 11 12] [14 15 16]
Same thing, except take only two rows:
sage: m.submatrix(1, 1, 2) [ 6 7 8] [10 11 12]
And now take only one column:
sage: m.submatrix(1, 1, 2, 1) [ 6] [10]
You can take zero rows or columns if you want:
sage: m.submatrix(1, 1, 0) [] sage: parent(m.submatrix(1, 1, 0)) Full MatrixSpace of 0 by 3 dense matrices over Integer Ring
