Creation of Matrices

This section describes the elementary constructs provided for creating a matrix or vector. For each of the following functions, the parent of the result will be as follows:

(a)
If the result is a vector then its parent will be the appropriate R-space (of type ModTupRng or ModTupFld).
(b)
If the result is a square matrix then its parent will be the appropriate matrix algebra (of type AlgMatElt).
(c)
If the result is a non-square matrix then its parent will be the appropriate R-matrix space (of type ModMatRng or ModMatFld).

A matrix or a vector may also be created by coercing a sequence of ring elements into the appropriate parent matrix structure. There is also a virtual type Mtrx and all matrix types inherit from Mtrx. While writing package intrinsics, an argument should be declared to be of type Mtrx if it is a general matrix.

Contents

General Matrix Construction

Matrix(R, m, n, Q) : Rng, RngIntElt, RngIntElt, [ RngElt ] -> Mtrx
Matrix(R, m, n, Q) : Rng, RngIntElt, RngIntElt, [ <RngIntElt, RngIntElt, RngElt> ] -> Mtrx
Matrix(R, m, n, Q) : Rng, RngIntElt, RngIntElt, [ [ RngElt ] ] -> Mtrx
Given a ring R, integers m, n≥0 and a sequence Q, return the m x n matrix over R whose entries are those specified by Q, coerced into R. Either of m and n may be 0, in which case Q must have length 0 (and may even be null), and the m x n zero matrix over R is returned. There are several possibilities for Q:
(a)
The sequence Q may be a sequence of length mn containing elements of a ring S, in which case the entries are given in row-major order. In this case, the function is equivalent to MatrixRing(R, n)!Q if m=n and RMatrixSpace(R, m, n)!Q otherwise.
(b)
The sequence Q may be a sequence of tuples, each of the form <i, j, x>, where 1≤i≤m, 1≤j≤n, and x∈S for some ring S. Such a tuple specifies that the (i, j)-th entry of the matrix is x. If an entry position is not given then its value is zero, while if an entry position is repeated then the last value overrides any previous value(s). This case is useful for creating sparse matrices.
(c)
The sequence Q may be a sequence of m sequences, each of length n and having entries in a ring S, in which case the rows of the matrix are specified by the inner sequences.
(d)
The sequence Q may be a sequence of m vectors, each of length n and having entries in a ring S, in which case the rows of the matrix are specified by the vectors.

Example Mat_Create (H27E1)

This example demonstrates simple ways of creating matrices using the general Matrix(R, m, n, Q) function.

(a) Defining a 2 x 2 matrix over Z:

> X := Matrix(IntegerRing(), 2, 2, [1,2, 3,4]);
> X;
[1 2]
[3 4]
> Parent(X);
Full Matrix Algebra of degree 2 over Integer Ring

(b) Defining a 2 x 3 matrix over GF(23):

> X := Matrix(GF(23), 2, 3, [1,-2,3, 4,100,-6]);
> X;
[ 1 21  3]
[ 4  8 17]
> Parent(X);
Full KMatrixSpace of 2 by 3 matrices over GF(23)

(c) Defining a sparse 5 x 10 matrix over Q:

> X := Matrix(RationalField(), 5, 10, [<1,2,23>, <3,7,11>, <5,10,-1>]);
> X;
[ 0 23  0  0  0  0  0  0  0  0]
[ 0  0  0  0  0  0  0  0  0  0]
[ 0  0  0  0  0  0 11  0  0  0]
[ 0  0  0  0  0  0  0  0  0  0]
[ 0  0  0  0  0  0  0  0  0 -1]
> Parent(X);
Full KMatrixSpace of 5 by 10 matrices over Rational Field

(c) Defining a sparse 10 x 10 matrix over GF(101):

> X := Matrix(GF(101), 10, 10, [<2*i-1, 2*j-1, i*j>: i, j in [1..5]]);
> X;
[  1   0   2   0   3   0   4   0   5   0]
[  0   0   0   0   0   0   0   0   0   0]
[  2   0   4   0   6   0   8   0  10   0]
[  0   0   0   0   0   0   0   0   0   0]
[  3   0   6   0   9   0  12   0  15   0]
[  0   0   0   0   0   0   0   0   0   0]
[  4   0   8   0  12   0  16   0  20   0]
[  0   0   0   0   0   0   0   0   0   0]
[  5   0  10   0  15   0  20   0  25   0]
[  0   0   0   0   0   0   0   0   0   0]
> Parent(X);
Full Matrix Algebra of degree 10 over GF(101)

Shortcuts

The following functions are "shortcut" versions of the previous general creation function, where some of the arguments are omitted since they can be inferred by Magma.

Matrix(m, n, Q) : RngIntElt, RngIntElt, [ RngElt ] -> Mtrx
Given integers m, n≥0 and a sequence Q of length mn containing elements of a ring R, return the m x n matrix over R whose entries are the entries of Q, in row-major order. Either of m and n may be 0, in which case Q must have length 0 and some universe R. This function is equivalent to MatrixRing(Universe(Q), n)!Q if m=n and RMatrixSpace(Universe(Q), m, n)!Q otherwise.
Matrix(m, n, Q) : RngIntElt, RngIntElt, [ [ RngElt ] ] -> Mtrx
Given integers m and n, and a sequence Q consisting of m sequences, each of length n and having entries in a ring R, return the m x n matrix over R whose rows are given by the inner sequences of Q.
Matrix(Q) : [ Mtrx ] -> Mtrx
Given a sequence Q of m vectors, each of length n over a ring R, return the m x n matrix over R whose rows are the entries of Q.
Matrix(R, n, Q) : Rng, RngIntElt, [ RngElt ] -> Mtrx
Given a ring R, an integer n≥0 and a sequence Q of length l containing elements of a ring S, such that n divides l, return the (l/n) x n matrix over R whose entries are the entries of Q, coerced into R, in row-major order. The argument n may be 0, in which case Q must have length 0 (and may even be null), in which case the 0 x 0 matrix over R is returned. This function is equivalent to MatrixRing(R, n)!Q if l=n2 and RMatrixSpace(R, #Q div n, n)!Q otherwise.
Matrix(n, Q) : RngIntElt, [ RngElt ] -> Mtrx
Given an integer n≥0 and a sequence Q of length l containing elements of a ring R, such that n divides l, return the (l/n) x n matrix over R whose entries are the entries of Q, in row-major order. The argument n may be 0, in which case Q must have length 0 and some universe R, in which case the 0 x 0 matrix over R is returned. This function is equivalent to MatrixRing(Universe(Q), n)!Q if l=n2 and RMatrixSpace(Universe(Q), #Q div n, n)!Q otherwise.
Matrix(Q) : [ [ RngElt ] ] -> Mtrx
Given a sequence Q consisting of m sequences, each of length n and having entries in a ring R, return the m x n matrix over R whose rows are given by the inner sequences of Q.
Matrix(R, Q) : Rng, [ [ RngElt ] ] -> Mtrx
Given a sequence Q consisting of m sequences, each of length n and having entries in a ring S, return the m x n matrix over R whose rows are given by the inner sequences of Q, with the entries coerced into R.

Example Mat_ShortCuts (H27E2)

The first matrix in the previous example may be created thus:
> X := Matrix(2, [1,2, 3,4]);
> X;
[1 2]
[3 4]
> X := Matrix([[1,2], [3,4]]);
> X;
[1 2]
[3 4]
The second matrix in the previous example may be created thus:
> X := Matrix(GF(23), 3, [1,-2,3, 4,100,-6]);
> X;
[ 1 21  3]
[ 4  8 17]
> Parent(X);
Full KMatrixSpace of 2 by 3 matrices over GF(23)
> X := Matrix(GF(23), [[1,-2,3], [4,100,-6]]);
> X;
[ 1 21  3]
[ 4  8 17]
> X := Matrix([[GF(23)|1,-2,3], [4,100,-6]]);
> X;
[ 1 21  3]
[ 4  8 17]

Construction of Structured Matrices

ZeroMatrix(R, m, n) : Rng, RngIntElt, RngIntElt -> Mtrx
Given a ring R and integers m, n≥0, return the m x n zero matrix over R.
ScalarMatrix(n, s) : RngIntElt, RngElt -> Mtrx
Given an integer n≥0 and an element s of a ring R, return the n x n scalar matrix over R which has s on the diagonal and zeros elsewhere. The argument n may be 0, in which case the 0 x 0 matrix over R is returned. This function is equivalent to MatrixRing(Parent(s), n)!s.
ScalarMatrix(R, n, s) : Rng, RngIntElt, RngElt -> Mtrx
Given a ring R, an integer n≥0 and an element s of a ring S, return the n x n scalar matrix over R which has s, coerced into R, on the diagonal and zeros elsewhere. n may be 0, in which case in which case the 0 x 0 matrix over R is returned. This function is equivalent to MatrixRing(R, n)!s.
DiagonalMatrix(R, n, Q) : Rng, RngIntElt, [ RngElt ] -> Mtrx
Given a ring R, an integer n≥0 and a sequence Q of n ring elements, return the n x n diagonal matrix over R whose diagonal entries correspond to the entries of Q, coerced into R.
DiagonalMatrix(R, Q) : Rng, [ RngElt ] -> Mtrx
Given a ring R and a sequence Q of n ring elements, return the n x n diagonal matrix over R whose diagonal entries correspond to the entries of Q, coerced into R.
DiagonalMatrix(Q) : [ RngElt ] -> Mtrx
Given a sequence Q of n elements from a ring R, return the n x n diagonal matrix over R whose diagonal entries correspond to the entries of Q.
Matrix(A) : Mtrx -> Mtrx
Given a matrix A of any type, return the same matrix but having as parent the appropriate matrix algebra if A is square, or the appropriate R-matrix space otherwise. This is useful, for example, if it is desired to convert a matrix group element or a square R-matrix space element to be an element of a general matrix algebra.
LowerTriangularMatrix(Q) : [ RngElt ] -> Mtrx
Given a sequence Q of length l containing elements of a ring R, such that l=((n + 1) choose 2) = n(n + 1)/2 for some integer n (so l is a triangular number), return the n x n lower-triangular matrix F over R such that the entries of Q describe the lower triangular part of F, in row major order.
LowerTriangularMatrix(R, Q) : Rng, [ RngElt ] -> Mtrx
Given a ring R and a sequence Q of length l containing elements of a ring S, such that l=((n + 1) choose 2) = n(n + 1)/2 for some integer n (so l is a triangular number), return the n x n lower-triangular matrix F over R such that the entries of Q, coerced into R, describe the lower triangular part of F, in row major order.
UpperTriangularMatrix(Q) : [ RngElt ] -> Mtrx
Given a sequence Q of length l containing elements of a ring R, such that l=((n + 1) choose 2) = n(n + 1)/2 for some integer n (so l is a triangular number), return the n x n upper-triangular matrix F over R such that the entries of Q describe the upper triangular part of F, in row major order.
UpperTriangularMatrix(R, Q) : Rng, [ RngElt ] -> Mtrx
Given a ring R and a sequence Q of length l containing elements of a ring S, such that l=((n + 1) choose 2) = n(n + 1)/2 for some integer n (so l is a triangular number), return the n x n upper-triangular matrix F over R such that the entries of Q, coerced into R, describe the upper triangular part of F, in row major order.
SymmetricMatrix(Q) : [ RngElt ] -> Mtrx
Given a sequence Q of length l containing elements of a ring R, such that l=((n + 1) choose 2) = n(n + 1)/2 for some integer n (so l is a triangular number), return the n x n symmetric matrix F over R such that the entries of Q describe the lower triangular part of F, in row major order. This function allows the creation of symmetric matrices without the need to specify the redundant upper triangular part.
SymmetricMatrix(R, Q) : Rng, [ RngElt ] -> Mtrx
Given a ring R and a sequence Q of length l containing elements of a ring S, such that l=((n + 1) choose 2) = n(n + 1)/2 for some integer n (so l is a triangular number), return the n x n symmetric matrix F over R such that the entries of Q, coerced into R, describe the lower triangular part of F, in row major order. This function allows the creation of symmetric matrices without the need to specify the redundant upper triangular part.
AntisymmetricMatrix(Q) : [ RngElt ] -> Mtrx
Given a sequence Q of length l containing elements of a ring R, such that l=((n) choose 2) = n(n - 1)/2 for some integer n (so l is a triangular number), return the n x n antisymmetric matrix F over R such that the entries of Q describe the proper lower triangular part of F, in row major order. The diagonal of F is zero and the proper upper triangular part of F is the negation of the proper lower triangular part of F.
AntisymmetricMatrix(R, Q) : Rng, [ RngElt ] -> Mtrx
Given a ring R and a sequence Q of length l containing elements of a ring S, such that l=((n) choose 2) = n(n - 1)/2 for some integer n (so l is a triangular number), return the n x n antisymmetric matrix F over R such that the entries of Q, coerced into R, describe the proper lower triangular part of F, in row major order.
PermutationMatrix(R, Q) : Rng, [ RngIntElt ] -> Mtrx
Given a ring R and a sequence Q of length n, such that Q is a permutation of [1, 2, ..., n], return the n by n permutation matrix over R corresponding Q.
PermutationMatrix(R, x) : Rng, GrpPermElt -> Mtrx
Given a ring R and a permutation x of degree n, return the n by n permutation matrix over R corresponding x.

Example Mat_Shortcuts (H27E3)

This example demonstrates ways of creating special matrices.

(a) Defining a 3 x 3 scalar matrix over Z:

> S := ScalarMatrix(3, -4);
> S;
[-4  0  0]
[ 0 -4  0]
[ 0  0 -4]
> Parent(S);
Full Matrix Algebra of degree 3 over Integer Ring

(b) Defining a 3 x 3 diagonal matrix over GF(23):

> D := DiagonalMatrix(GF(23), [1, 2, -3]);
> D;
[ 1  0  0]
[ 0  2  0]
[ 0  0 20]
> Parent(D);
Full Matrix Algebra of degree 3 over GF(23)

(c) Defining a 3 x 3 symmetric matrix over Q:

> S := SymmetricMatrix([1, 1/2,3, 1,3,4]);
> S;
[  1 1/2   1]
[1/2   3   3]
[  1   3   4]
> Parent(S);
Full Matrix Algebra of degree 3 over Rational Field

(d) Defining n x n lower- and upper-triangular matrices for various n:

> low := func<n | LowerTriangularMatrix([i: i in [1 .. Binomial(n + 1, 2)]])>;
> up := func<n | UpperTriangularMatrix([i: i in [1 .. Binomial(n + 1, 2)]])>;
> sym := func<n | SymmetricMatrix([i: i in [1 .. Binomial(n + 1, 2)]])>;
> low(3);
[1 0 0]
[2 3 0]
[4 5 6]
> up(3);
[1 2 3]
[0 4 5]
[0 0 6]
> sym(3);
[1 2 4]
[2 3 5]
[4 5 6]
> up(6);
[ 1  2  3  4  5  6]
[ 0  7  8  9 10 11]
[ 0  0 12 13 14 15]
[ 0  0  0 16 17 18]
[ 0  0  0  0 19 20]
[ 0  0  0  0  0 21]

Construction of Random Matrices

RandomMatrix(R, m, n) : Rng, RngIntElt, RngIntElt -> Mtrx
Given a finite ring R and positive integers m and n, construct a random m x n matrix over R.
RandomUnimodularMatrix(n, M) : RngIntElt, RngIntElt -> Mtrx
Given positive integers M and n, construct a random integral n x n matrix having determinant 1 or -1. Most entries will lie in the range [ - M, M].
RandomSLnZ(n, k, l) : RngIntElt, RngIntElt, RngIntElt -> AlgMatElt
A random element of SLn(Z), obtained by multiplying l random matrices of the form I + E, where E has exactly one nonzero entry, which is off the diagonal and has absolute value at most k.
RandomGLnZ(n, k, l) : RngIntElt, RngIntElt, RngIntElt -> AlgMatElt
A random element of GLn(Z), obtained in a similar way to RandomSLnZ.
RandomSymplecticMatrix(g, m) : RngIntElt, RngIntElt -> Mtrx
Given positive integers n and m, construct a (somewhat) random 2n x 2n symplectic matrix over the integers. The entries will have the same order of magnitude as m.

Creating Vectors

Vector(n, Q) : RngIntElt, [ RngElt ] -> ModTupRngElt
Given an integer n and a sequence Q of length n containing elements of a ring R, return the vector of length n whose entries are the entries of Q. The integer n may be 0, in which case Q must have length 0 and some universe R. This function is equivalent to RSpace(Universe(Q), n)!Q.
Vector(Q) : [ RngElt ] -> ModTupRngElt
Given a sequence Q of length l containing elements of a ring R, return the vector of length l whose entries are the entries of Q. The argument Q may have length 0 if it has a universe R (i.e., it may not be null). This function is equivalent to RSpace(Universe(Q), #Q)!Q.
Vector(R, n, Q) : Rng, RngIntElt, [ RngElt ] -> ModTupRngElt
Given a ring R, an integer n, and a sequence Q of length n containing elements of a ring S, return the vector of length n whose entries are the entries of Q, coerced into R. The integer n may be 0, in which case Q must have length 0 (and may even be null). This function is equivalent to RSpace(R, n)!Q.
Vector(R, Q) : Rng, [ RngElt ] -> ModTupRngElt
Given a ring R and a sequence Q of length l containing elements of a ring S, return the vector of length l whose entries are the entries of Q, coerced into R. The argument Q may have length 0 and may be null. This function is equivalent to RSpace(R, #Q)!Q.
V2.28, 13 July 2023