# Accessing and Modifying a Matrix

## Indexing

### `a[i]: AlgMatElt, RngIntElt -> ModTupElt`

Given an element $a$ belonging to the matrix algebra $R$ over the ring $S$, return the $i$-th row of $a$ as an element of the natural $S$-module associated with $R$.

### `a[i] := u: AlgMatElt, RngIntElt, RngElt -> AlgMatElt`

Given an element $a$ belonging to the matrix algebra $R$ over the ring $S$, an integer $i$ in the range $[1, n]$ and an element $u$ of the natural $S$-module associated with $R$, replace the $i$-th row of $a$ by the vector $u$.

### `a[i, j]: AlgMatElt, RngIntElt, RngIntElt -> RngElt`

Given an element $a$ belonging to the matrix algebra $R$ over the ring $S$, return the $(i,j)$-th entry of $a$ as an element of $S$.

### `a[i, j] := t: AlgMatElt, RngIntElt, RngIntElt, RngElt -> AlgMatElt`

Given an element $a$ belonging to the matrix algebra $R$ over the ring $S$, integers $i$ and $j$ in the range $[1, n]$, and an element $t$ of $S$, replace the $(i,j)$-th entry of $a$ by $t$.

### `ElementToSequence(a): AlgMatElt -> [ RngElt ]`

### `Eltseq(a): AlgMatElt -> [ RngElt ]`

Given an element $a$ of the matrix algebra $R$ over $S$, where $a = (a_{ij})$, $1 \leq i$, $j \leq n$, return $a$ as the sequence of elements of $S$:

$$
[a_{11}, \ldots, a_{1n}, a_{21},\ldots, a_{2n}, \ldots, a_{n1},\ldots, a_{nn}].
$$

## Extracting and Inserting Blocks

### `Submatrix(a, i, j, p, q): Mtrx, RngIntElt, RngIntElt, RngIntElt, RngIntElt -> Mtrx`

### `ExtractBlock(a, i, j, p, q): Mtrx, RngIntElt, RngIntElt, RngIntElt, RngIntElt -> Mtrx`

Given a matrix $a$ belonging to a subalgebra of $M_n(S)$ and integers $i$, $j$, $p$ and $q$ satisfying the conditions, $1 \le i + p \le m$, $1 \le j + q \le n$, create the matrix $b$ consisting of the $p\times q$ submatrix of $a$ whose first entry is the $(i,j)$-th entry of $a$. If $p \ne q$, the matrix $b$ is created as an element of ${\operatorname{Hom}}(P, Q)$, where Rank$(P) = p$, Rank$(Q) = q$. Otherwise it is created as an element of $M_p(S)$.

### `InsertBlock(~a, b, i, j): Mtrx, Mtrx, RngIntElt, RngIntElt -> Mtrx`

(Procedure.) Given that the matrix $a$ belongs to a subalgebra of $M_n(S)$ and the $p\times q$ matrix $b$ is also over $S$, the integers $i$, $j$, $p$ and $q$ must satisfy the conditions, $1 \le i + p \le m$, $1 \le j + q \le n$. This procedure modifies $a$ so that the $p\times q$ block beginning at the $(i,j)$-th entry of $a$ is replaced by $b$.

## Joining Matrices

### `HorizontalJoin(X, Y): Mtrx, Mtrx -> Mtrx`

Given matrices $X$ with $r$ rows and $c$ columns, and $Y$ with $r$ rows and $d$ columns, both over the same coefficient ring $R$, return the matrix over $R$ with $r$ rows and $(c+d)$ columns obtained by joining $X$ and $Y$ horizontally (placing $Y$ to the right of $X$).

### `HorizontalJoin(Q): [ ModMatRngElt ] -> ModMatRngElt`

Given a sequence $Q$ of matrices, each having the same number of rows and being over the same coefficient ring $R$, return the matrix over $R$ obtained by joining the elements of $Q$ horizontally in order.

### `VerticalJoin(X, Y): ModMatRngElt, ModMatRngElt -> ModMatRngElt`

Given matrices $X$ with $r$ rows and $c$ columns and $Y$ with $s$ rows and $c$ columns, both over the same coefficient ring $R$, return the matrix with $(r+s)$ rows and $c$ columns over $R$ obtained by joining $X$ and $Y$ vertically (placing $Y$ underneath $X$).

### `VerticalJoin(Q): [ ModMatRngElt ] -> ModMatRngElt`

Given a sequence $Q$ of matrices, each having the same number of columns and being over the same coefficient ring $R$, return the matrix over $R$ obtained by joining the elements of $Q$ vertically in order.

### `DiagonalJoin(X, Y): ModMatRngElt, ModMatRngElt -> ModMatRngElt`

Given matrices $X$ with $a$ rows and $b$ columns and $Y$ with $c$ rows and $d$ columns, both over the same coefficient ring $R$, return the matrix with $(a+c)$ rows and $(b+d)$ columns over $R$ obtained by joining $X$ and $Y$ diagonally (placing $Y$ diagonally to the right of and underneath $X$, with zero blocks above and below the diagonal).

### `DiagonalJoin(Q): [ ModMatRngElt ] -> ModMatRngElt`

Given a sequence $Q$ of matrices, each being over the same coefficient ring $R$, return the matrix over $R$ obtained by joining the elements of $Q$ diagonally in order.

## Row and Column Operations

For the following operations, $a$ is an element of a subring of the matrix algebra $M_n(S)$, $u$ is a non-zero element of $S$, and $i$ and $j$ are integers in the range $[1, n]$. Each of the operations described here acts on the matrix in place, and is therefore implemented as a procedure.

### `SwapRows(~a, i, j): AlgMatElt, RngIntElt, RngIntElt`

Mutate the matrix $a$ by interchanging rows $i$ and $j$.

### `MultiplyRow(~a, u, j): AlgMatElt, RngElt, RngIntElt`

Mutate the matrix $a$ by multiplying row $j$ by the scalar $u$.

### `AddRow(~a, u, i, j): AlgMatElt, RngElt, RngIntElt, RngIntElt`

Mutate the matrix $a$ by adding $u$ times row $i$ to row $j$.

### `SwapColumns(~a, i, j): AlgMatElt, RngIntElt, RngIntElt`

Mutate the matrix $a$ by interchanging columns $i$ and $j$.

### `MultiplyColumn(~a, u, i): AlgMatElt, RngElt, RngIntElt`

Mutate the matrix $a$ by multiplying column $i$ by the scalar $u$.

### `AddColumn(~a, u, i, j): AlgMatElt, RngElt, RngIntElt, RngIntElt`

Mutate the matrix $a$ by adding $u$ times column $i$ to column $j$.