# Submodules and Quotient Modules

## Construction

### `sub<M | L>: ModRng, List -> ModRng`

Given an $A$-module $M$, construct the submodule $N$ generated by the elements of $M$ specified by the list $L$. Each term $L_i$ of the list $L$ must be an expression defining an object of one of the following types:

**(a)**
A sequence of $n$ elements of $R$ defining an element of $M$;

**(b)**
A set or sequence whose terms are elements of $M$;

**(c)**
A submodule of $M$;

**(d)**
A set or sequence whose terms are submodules of $M$.

The generators stored for $N$ consist of the elements specified by terms $L_i$ together with the stored generators for submodules specified by terms of $L_i$. Repetitions of an element and occurrences of the zero element are removed (unless $N$ is trivial).

The constructor returns the submodule $N$ as an $A$-module together with the inclusion homomorphism $f : N \rightarrow M$.

### `ImageWithBasis(X, M): ModMatRngElt, ModRng -> ModRng`

```magma
Check: BoolElt                    Default: true
```

Given a basis matrix $X$ for a $A$-submodule of the $A$-module $M$, return the submodule $N$ of $M$ such that the morphism of $N$ into $M$ is $X$.

### `Morphism(M, N): ModRng, ModRng -> ModMatRngElt`

If the $A$-module $M$ was created as a submodule of the module $N$, return the inclusion homomorphism $\phi : M \rightarrow N$ as an element of ${\operatorname{Hom}}_A(M, N)$. Thus, $\phi$ gives the correspondence between elements of $M$ (represented with respect to the standard basis of $M$) and elements for $N$.

### `Example: Submodule (ex-260f18)`

We construct a submodule of the permutation module for $L(3, 4)$ in its representation of degree $21$.

```magma
> G := PSL(3, 4);
> M := PermutationModule(G, GF(2));
> M;
GModule M of dimension 21 over GF(2)
> x := M![0,0,0,1,0,1,0,0,0,1,1,0,0,0,1,0,1,1,0,0,1];
> N := sub< M | x >;
> N:Maximal;
GModule N of dimension 9 over GF(2)
Generators of acting algebra:

[1 0 0 0 1 0 1 0 1]
[0 1 0 1 1 1 0 0 0]
[0 0 1 1 1 1 1 0 1]
[0 0 0 0 0 1 1 0 0]
[0 0 0 1 0 0 1 0 0]
[0 0 0 0 1 0 1 0 0]
[0 0 0 1 1 1 0 0 0]
[0 0 0 0 1 1 0 0 1]
[0 0 0 1 0 1 0 1 1]

[0 0 0 0 0 1 0 1 1]
[1 0 0 0 0 0 0 0 1]
[0 1 1 0 0 1 0 0 1]
[0 0 0 0 0 1 0 0 0]
[0 0 1 0 0 1 0 0 0]
[0 0 1 0 1 1 0 0 1]
[0 0 1 1 0 0 0 0 1]
[0 0 1 0 0 0 0 0 1]
[0 0 0 0 0 0 1 0 0]

```

Note that as a ${\bf F}_{2}$-module $V$ has dimension $1$, while as a $K[G]$-module it has dimension $9$. The submodule $N$ is defined on a reduced basis so we use `Morphism` to see $N$ embedded in $M$.

```magma
> phi := Morphism(N, M);
> [ phi(x) : x in Basis(N) ];
[
    M: (1 0 0 0 0 0 0 0 0 1 1 1 1 0 0 0 1 0 1 0 1),
    M: (0 1 0 0 0 0 0 0 0 1 0 0 0 1 0 0 1 1 1 1 1),
    M: (0 0 1 0 0 0 0 0 0 1 0 1 1 0 1 0 1 1 0 1 0),
    M: (0 0 0 1 0 0 0 0 0 0 1 0 1 1 0 1 0 1 1 0 1),
    M: (0 0 0 0 1 0 0 0 0 1 1 0 1 1 1 0 0 0 0 1 1),
    M: (0 0 0 0 0 1 0 0 0 1 0 0 1 1 1 1 1 0 1 0 0),
    M: (0 0 0 0 0 0 1 0 0 0 1 0 0 1 1 1 1 1 0 1 0),
    M: (0 0 0 0 0 0 0 1 0 0 0 1 0 0 1 1 1 1 1 0 1),
    M: (0 0 0 0 0 0 0 0 1 1 1 1 0 0 0 1 0 1 0 1 1)
]

```

## Membership and Equality

The operators described below refer to the underlying vector space.

### `u in M: ModRngElt, ModRng -> BoolElt`

Returns `true` if the element $u$ lies in the $A$-module $M$.

### `N subset M: ModRng, ModRng -> BoolElt`

Returns `true` if the $A$-module $N$ is contained in the $A$-module $M$.

### `N eq M: ModRng, ModRng -> BoolElt`

Returns `true` if the $A$-modules $N$ and $M$ are equal, where $N$ and $M$ are contained in a common $A$-module.

## Operations on Submodules

### `M + N: ModRng, ModRng -> ModRng`

Sum of the submodules $M$ and $N$, where $M$ and $N$ belong to a a common $A$-module.

### `M meet N: ModRng, ModRng -> ModRng`

Intersection of the submodules $M$ and $N$, where $M$ and $N$ belong to a common $A$-module.

## Quotient Modules

### `quo<M | L>: ModRng, List -> ModRng`

Given an $A$-module $M$, construct the quotient module $P = M/N$ as an $A$-module, where $N$ is the submodule generated by the elements of $M$ specified by the list $L$. Each term $L_i$ of the list $L$ must be an expression defining an object of one of the following types:

**(a)**
A sequence of $n$ elements of $R$ defining an element of $M$;

**(b)**
A set or sequence whose terms are elements of $M$;

**(c)**
A submodule of $M$;

**(d)**
A set or sequence whose terms are submodules of $M$.

The generators constructed for $N$ consist of the elements specified by terms $L_i$ together with the stored generators for submodules specified by terms of $L_i$. The constructor returns the quotient module $P$ as an $A$-module together with the natural homomorphism $f : M \rightarrow P$.

### `Morphism(M, N): ModRng, ModRng -> ModMatRngElt`

If the $A$-module $N$ was created as a quotient module of the module $M$, return the natural homomorphism $\phi : M \rightarrow N$ as an element of ${\operatorname{Hom}}_R(M, N)$. Thus $\phi$ gives the correspondence between elements of $M$ and elements of $N$ (represented with respect to the standard basis for $N$).

### `Example: Quotient Module (ex-26899c)`

We construct a quotient module of the permutation module for $L(3, 4)$ considered above.

```magma
> G := PSL(3, 4);
> M := PermutationModule(G, GF(2));
> x := M![0,0,0,1,0,1,0,0,0,1,1,0,0,0,1,0,1,1,0,0,1];
> N := sub< M | x >;
> N;
GModule N of dimension 9 over GF(2)
> Q, phi := quo< M | x >;
> Q;
GModule Q of dimension 12 over GF(2)

```

We locate the kernel of the epimorphism $\phi$ and check that it is the same as $N$.

```magma
> K :=  Kernel(phi);
GModule Ker of dimension 9 over GF(2)
> K eq N;
true

```

Given an element $x$ in the codomain $Q$ of the epimorphism $\phi$, the value returned as the preimage of $x$ is a representative element of the coset of the kernel that is the actual preimage of $x$. Since we are working in a module over a finite field, we can explicitly construct the full preimage `PreIm` of $x$.

```magma
> x := Q![0,0,0,1,1,0,0,0,0,1,0,0];
> PreIm := { x@@phi + k : k in K };
> #PreIm;
512

```