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.

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\ge 0\) and a sequence \(Q\), return the \(m\times 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\times 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\leq i\leq m\), \(1\leq j\leq n\), and \(x\in 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: Create (ex-79e602)

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

(a) Defining a \(2 \times 2\) matrix over \({\mathbb{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

Run in calculatorCopy input

(b) Defining a \(2 \times 3\) matrix over \({\bf F}_{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)

Run in calculatorCopy input

(c) Defining a sparse \(5 \times 10\) matrix over \({\mathbb{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

Run in calculatorCopy input

(c) Defining a sparse \(10 \times 10\) matrix over \({\bf F}_{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)

Run in calculatorCopy input

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\ge 0\) and a sequence \(Q\) of length \(mn\) containing elements of a ring \(R\), return the \(m\times 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\times 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\times 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\ge 0\) and a sequence \(Q\) of length \(l\) containing elements of a ring \(S\), such that \(n\) divides \(l\), return the \((l/n)\times 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 \times 0\) matrix over \(R\) is returned. This function is equivalent to MatrixRing(R, n)!Q if \(l=n^2\) and RMatrixSpace(R, #Q div n, n)!Q otherwise.

Matrix(n, Q): RngIntElt, [ RngElt ] -> Mtrx

Given an integer \(n\ge 0\) and a sequence \(Q\) of length \(l\) containing elements of a ring \(R\), such that \(n\) divides \(l\), return the \((l/n)\times 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 \times 0\) matrix over \(R\) is returned. This function is equivalent to MatrixRing(Universe(Q), n)!Q if \(l=n^2\) 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\times 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\times n\) matrix over \(R\) whose rows are given by the inner sequences of \(Q\), with the entries coerced into \(R\).

Example: Short Cuts (ex-cb789b)

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]

Run in calculatorCopy input

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]

Run in calculatorCopy input

Construction of Structured Matrices

ZeroMatrix(R, m, n): Rng, RngIntElt, RngIntElt -> Mtrx

Given a ring \(R\) and integers \(m,n\ge 0\), return the \(m\times n\) zero matrix over \(R\).

IdentityMatrix(R, n): Rng, RngIntElt -> Mtrx

Given a ring \(R\) and integer \(n\ge 0\), return the \(n\times n\) identity matrix over \(R\).

ScalarMatrix(n, s): RngIntElt, RngElt -> Mtrx

Given an integer \(n\ge 0\) and an element \(s\) of a ring \(R\), return the \(n \times 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 \times 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\ge 0\) and an element \(s\) of a ring \(S\), return the \(n \times n\) scalar matrix over \(R\) which has \(s\), coerced into \(R\), on the diagonal and zeros elsewhere. The argument \(n\) may be 0, in which case the \(0 \times 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\ge 0\) and a sequence \(Q\) of \(n\) ring elements, return the \(n \times 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 \times 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 \times 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 \times 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 \times 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 \times 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 \times 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 \times 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 \times 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 \times 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 \times 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,\dots,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: Shortcuts (ex-c66a52)

This example demonstrates ways of creating special matrices.

(a) Defining a \(3 \times 3\) scalar matrix over \({\mathbb{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

Run in calculatorCopy input

(b) Defining a \(3 \times 3\) diagonal matrix over \({\bf F}_{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)

Run in calculatorCopy input

(c) Defining a \(3 \times 3\) symmetric matrix over \({\mathbb{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

Run in calculatorCopy input

(d) Defining \(n \times 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]

Run in calculatorCopy input

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\times n\) matrix over \(R\).

RandomUnimodularMatrix(n, M): RngIntElt, RngIntElt -> Mtrx

Given positive integers \(M\) and \(n\), construct a random integral \(n \times 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 \(SL_n({\mathbb{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 \(GL_n({\mathbb{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 \times 2n\) symplectic matrix over the integers. The entries will have the same order of magnitude as \(m\).

RandomSymmetricMatrix(R, n): Rng, RngIntElt -> AlgMatElt

RandomSymmetricMatrix(R, n, M): RngOrd, RngIntElt, RngIntElt -> AlgMatElt

Generate a random symmetric matrix of dimension \(n\) over the ring \(R\), where each coordinate is in \([-M,M]\).

RandomPositiveDefiniteSymmetricMatrix(n, M): RngIntElt, RngIntElt -> AlgMatElt

Generates a random positive definite symmetric matrix over the integers of dimension \(n\), with entries in \([-M,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.