# 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}}$:

```magma
> 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 \times 3$ matrix over ${\bf F}_{23}$:

```magma
> 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 \times 10$ matrix over ${\mathbb{Q}}$:

```magma
> 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 \times 10$ matrix over ${\bf F}_{101}$:

```magma
> 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\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:

```magma
> 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:

```magma
> 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\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}}$:

```magma
> 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 \times 3$ diagonal matrix over ${\bf F}_{23}$:

```magma
> 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 \times 3$ symmetric matrix over ${\mathbb{Q}}$:

```magma
> 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 \times n$ lower- and upper-triangular matrices for various $n$:

```magma
> 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\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`.