File: /ext/sage/sage-8.6_1804/local/lib/python2.7/site-packages/sage/matrix/special.py
Signature : block_matrix(*args, **kwds)
Docstring :
This function is available as block_matrix(...) and
matrix.block(...).
Return a larger matrix made by concatenating submatrices (rows
first, then columns). For example, the matrix
[ A B ]
[ C D ]
is made up of submatrices A, B, C, and D.
INPUT:
The block_matrix command takes a list of submatrices to add as
blocks, optionally preceded by a ring and the number of block rows
and block columns, and returns a matrix.
The submatrices can be specified as a list of matrices (using
"nrows" and "ncols" to determine their layout), or a list of lists
of matrices, where each list forms a row.
* "ring" - the base ring
* "nrows" - the number of block rows
* "ncols" - the number of block cols
* "sub_matrices" - matrices (see below for syntax)
* "subdivide" - boolean, whether or not to add subdivision
information to the matrix
* "sparse" - boolean, whether to make the resulting matrix sparse
EXAMPLES:
sage: A = matrix(QQ, 2, 2, [3,9,6,10])
sage: block_matrix([ [A, -A], [~A, 100*A] ])
[ 3 9| -3 -9]
[ 6 10| -6 -10]
[-----------+-----------]
[-5/12 3/8| 300 900]
[ 1/4 -1/8| 600 1000]
If the number of submatrices in each row is the same, you can
specify the submatrices as a single list too:
sage: block_matrix(2, 2, [ A, A, A, A ])
[ 3 9| 3 9]
[ 6 10| 6 10]
[-----+-----]
[ 3 9| 3 9]
[ 6 10| 6 10]
One can use constant entries:
sage: block_matrix([ [1, A], [0, 1] ])
[ 1 0| 3 9]
[ 0 1| 6 10]
[-----+-----]
[ 0 0| 1 0]
[ 0 0| 0 1]
A zero entry may represent any square or non-square zero matrix:
sage: B = matrix(QQ, 1, 1, [ 1 ] )
sage: C = matrix(QQ, 2, 2, [ 2, 3, 4, 5 ] )
sage: block_matrix([ [B, 0], [0, C] ])
[1|0 0]
[-+---]
[0|2 3]
[0|4 5]
One can specify the number of rows or columns as keywords too:
sage: block_matrix([A, -A, ~A, 100*A], ncols=4)
[ 3 9| -3 -9|-5/12 3/8| 300 900]
[ 6 10| -6 -10| 1/4 -1/8| 600 1000]
sage: block_matrix([A, -A, ~A, 100*A], nrows=1)
[ 3 9| -3 -9|-5/12 3/8| 300 900]
[ 6 10| -6 -10| 1/4 -1/8| 600 1000]
It handles base rings nicely too:
sage: R.<x> = ZZ['x']
sage: block_matrix(2, 2, [1/2, A, 0, x-1])
[ 1/2 0| 3 9]
[ 0 1/2| 6 10]
[-----------+-----------]
[ 0 0|x - 1 0]
[ 0 0| 0 x - 1]
sage: block_matrix(2, 2, [1/2, A, 0, x-1]).parent()
Full MatrixSpace of 4 by 4 dense matrices over Univariate Polynomial Ring in x over Rational Field
Subdivisions are optional. If they are disabled, the columns need
not line up:
sage: B = matrix(QQ, 2, 3, range(6))
sage: block_matrix([ [~A, B], [B, ~A] ], subdivide=False)
[-5/12 3/8 0 1 2]
[ 1/4 -1/8 3 4 5]
[ 0 1 2 -5/12 3/8]
[ 3 4 5 1/4 -1/8]
Without subdivisions it also deduces dimensions for scalars if
possible:
sage: C = matrix(ZZ, 1, 2, range(2))
sage: block_matrix([ [ C, 0 ], [ 3, 4 ], [ 5, 6, C ] ], subdivide=False )
[0 1 0 0]
[3 0 4 0]
[0 3 0 4]
[5 6 0 1]
If all submatrices are sparse (unless there are none at all), the
result will be a sparse matrix. Otherwise it will be dense by
default. The "sparse" keyword can be used to override this:
sage: A = Matrix(ZZ, 2, 2, [0, 1, 0, 0], sparse=True)
sage: block_matrix([ [ A ], [ A ] ]).parent()
Full MatrixSpace of 4 by 2 sparse matrices over Integer Ring
sage: block_matrix([ [ A ], [ A ] ], sparse=False).parent()
Full MatrixSpace of 4 by 2 dense matrices over Integer Ring
Consecutive zero submatrices are consolidated.
sage: B = matrix(2, range(4))
sage: C = matrix(2, 8, range(16))
sage: block_matrix(2, [[B,0,0,B],[C]], subdivide=False)
[ 0 1 0 0 0 0 0 1]
[ 2 3 0 0 0 0 2 3]
[ 0 1 2 3 4 5 6 7]
[ 8 9 10 11 12 13 14 15]
Ambiguity is not tolerated.
sage: B = matrix(2, range(4))
sage: C = matrix(2, 8, range(16))
sage: block_matrix(2, [[B,0,B,0],[C]], subdivide=False)
Traceback (most recent call last):
...
ValueError: insufficient information to determine submatrix widths
Historically, giving only a flat list of submatrices, whose number
was a perfect square, would create a new matrix by laying out the
submatrices in a square grid. This behavior is now deprecated.
sage: A = matrix(2, 3, range(6))
sage: B = matrix(3, 3, range(9))
sage: block_matrix([A, A, B, B])
doctest:...: DeprecationWarning: invocation of block_matrix with just a list whose length is a perfect square is deprecated. See the documentation for details.
[0 1 2|0 1 2]
[3 4 5|3 4 5]
[-----+-----]
[0 1 2|0 1 2]
[3 4 5|3 4 5]
[6 7 8|6 7 8]
Historically, a flat list of matrices whose number is not a perfect
square, with no specification of the number of rows or columns,
would raise an error. This behavior continues, but could be removed
when the deprecation above is completed.
sage: A = matrix(2, 3, range(6))
sage: B = matrix(3, 3, range(9))
sage: block_matrix([A, A, A, B, B, B])
Traceback (most recent call last):
...
ValueError: must specify nrows or ncols for non-square block matrix.