block_matrix?

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.