# Submodules and Quotient Modules

The following functions allow the construction of submodules and quotient modules and access to essential properties.

## Creation

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

Given a module $M$ over a ring $R$, return the submodule of $M$ (with the same quotient relations as $M$) generated by the elements of $M$ specified by the list $L$. Each term of the list $L$ must be an expression defining an object of one of the following types:

**(a)**
An element of $M$;

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

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

**(d)**
A set or sequence of submodules of $M$. A morphism is stored from the resulting submodule $S$ into $M$, such that $S.i$ is mapped to the $i$-th generator given in the above list.

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

Given a module $M$ over a ring $R$, return the quotient module of $M$ by the elements of $M$ specified by the list $L$. Each term of the list $L$ must be an expression defining an object of one of the following types:

**(a)**
An element of $M$;

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

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

**(d)**
A set or sequence of submodules of $M$. A morphism is stored from $M$ onto the resulting quotient module $Q$.

### `Morphism(M, N): ModMPol, ModMPol -> ModMPolHom`

Given modules $M$ and $N$, related by a chain of stored sub and quo morphisms as mentioned above, returns the resulting morphism matrix map from $M$ to $N$. If no known sub/quo relationship chain exists between $M$ and $N$ then an error is returned.

### `Submodule(I): RngMPol -> ModMPol`

Given an ideal $I$ of a polynomial ring $R$, return the submodule of $R^1$ generated by $I$.

### `QuotientModule(I): RngMPol -> ModMPol`

Given an ideal $I$ of a polynomial ring $R$, return the quotient module $R^1/I$.

### `GradedModule(I): RngMPol -> ModMPol`

Given a homogeneous ideal $I$ of a ring $R$, return the graded quotient module $R^1/I$.

## Module Bases

The following functions allow one to manipulate the bases of modules. Note that a Gröbner basis for a module will be automatically generated when necessary; the `Groebner` procedure just allows explicit immediate construction of the Gröbner basis.

### `Basis(M): ModMPol -> RngMPolElt`

Given a module $M$, return the current basis (whether it has been converted to a Gröbner basis or not) of $M$.

### `BasisElement(M, i): ModMPol, RngIntElt -> RngMPolElt`

Given a module $M$ together with an integer $i$, return the $i$-th element of the current basis of $M$. Note that this is *not* the same as $M.i$.

### `BasisMatrix(M): ModMPol -> ModMatRngElt`

Given a module $M$, return the basis matrix of $M$, which is a $k$ by $r$ matrix over $R$, where $k$ is the length of the basis of $M$ and $r$ is the degree of $M$.

### `Groebner(M): ModMPol`

(Procedure.) Explicitly force a Gröbner basis for the module $M$ to be constructed.

### `Example: Sub Quo Embedded (ex-df76cb)`

We construct simple submodules and quotient modules of an embedded module and consider some of their basic properties.

```magma
> R<x, y, z> := PolynomialRing(RationalField(), 3);
> M := EModule(R, 3);
> S := sub<M | [1, x, x^2+y], [z, y, x*y^2+1],
>              [y, z, x+z]>;
> Groebner(S);
> S;
Embedded Submodule of R^3
Order: Module TOP: Lexicographical
Groebner basis:
[ -x*z + y^2 + y, x*y^2 - x*y + z,         y^3 + z],
[  x*y - y*z - 1,   x*z - x - z^2,        -y - z^2],
[              y,               z,           x + z],
[        y^3 - z,       y^2*z - y,       y^2*z - 1]
> a := M ! [y, z, x+z];
> a;
[y, z, x + z]
> a in S;
true
> BasisElement(S, 1);
[-x*z + y^2 + y, x*y^2 - x*y + z, y^3 + z]
> Q := quo<M | [x, y, z]>;
> Q;
Embedded Module R^3/<relations>
Order: Module TOP: Lexicographical
Relations (Groebner basis):
[x, y, z]
> a := Q![x, y, 0];
> b := Q![0, 0, z];
> a;
[0, 0, -z]
> b;
[0, 0, z]
> a+b;
[0, 0, 0]
> Q ! [x,y,z];
[0, 0, 0]
> QQ := quo<Q | [x^2, 0, y+z]>;
> QQ;
Embedded Module R^3/<relations>
Order: Module TOP: Lexicographical
Relations (Groebner basis):
[          0,         x*y, x*z - y - z],
[          x,           y,           z]
> SL := Localization(S);
> SL;
Embedded Submodule of R^3 (local)
Order: Module TOP: Local Lexicographical
Basis:
[        1,         x,   x^2 + y],
[        z,         y, 1 + x*y^2],
[        y,         z,     x + z]

```

### `Example: Sub Quo Reduced (ex-c177b3)`

We construct simple submodules and quotient modules of a reduced module and consider some of their basic properties.

```magma
> R<x,y,z> := PolynomialRing(RationalField(), 3);
> M := RModule(R, 3);
> S := sub<M | [1, x, x^2+y], [z, y, x*y^2+1]>;
> M;
Free Reduced Module R^3
> S;
Reduced Module R^2/<relations>
> Morphism(S, M);
Module homomorphism (2 by 3)
Ambient matrix:
[        1         x   x^2 + y]
[        z         y x*y^2 + 1]
> RelationMatrix(S);
Matrix with 0 rows and 2 columns
> S;
Free Reduced Module R^2
> M.1;
[1, 0, 0]
> M!S.1;
[1, x, x^2 + y]
> M!S.2;
[z, y, x*y^2 + 1]
> M.1 in S;
false
> Q := quo<M | [1, x^2, y]>;
> Q;
Free Reduced Module R^2
> RelationMatrix(Q);
Matrix with 0 rows and 2 columns
> Morphism(M, Q);
Module homomorphism (3 by 2)
Ambient matrix:
[-x^2   -y]
[   1    0]
[   0    1]
> Morphism(S, Q);
Module homomorphism (2 by 2)
Ambient matrix:
[       -x^2 + x             x^2]
[     -x^2*z + y x*y^2 - y*z + 1]
> Q!M.1;
[-x^2, -y]
> M!Q.1;
[0, 1, 0]
> M!Q.2;
[0, 0, 1]
> Q!M!Q.2;
[0, 1]

```