# Lattice of Submodules

Let $M$ be an $A$-module. Magma can construct the lattice $L$ of all submodules of $M$ if this is not too large. Various properties of the lattice $L$ may then be examined. The elements of $L$ are called *submodule-lattice elements* and are numbered from 1 to $n$ where $n$ is the cardinality of $L$. Once the lattice has been constructed, the result of various lattice operations, such as meet and intersection, are available without the need for any module-theoretic calculation. Certain information about $M$ and its submodules may then be obtained by analyzing $L$. Given an element of $L$, one can easily create the submodule $N$ of $M$ corresponding to it and one can also create the element of $L$ corresponding to any submodule of $M$. The functions is this section apply only in the case in which $A$ is an algebra over a finite field.

## Creating Lattices

### `SubmoduleLattice(M): ModRng -> SubModLat, BoolElt`

```magma
Limit           : RngIntElt                    Default: 0
CodimensionLimit: RngIntElt                    Default: 
```

Given a $K[G]$-module $M$ defined over $F_q$, construct the lattice $L$ of submodules of $M$. If the parameter `Limit` is set to $n$, at most $n$ submodules are calculated, and the second return value indicates whether the returned lattice $L$ is the full lattice of submodules of $M$.

### `SubmoduleLatticeAbort(M, n): ModRng, RngIntElt -> BoolElt, SubModLat`

Given a $K[G]$-module $M$ defined over $F_q$ and a positive integer $n$, construct the lattice $L$ of submodules of $M$, provided that the number of submodules does not exceed $n$. In this case the value `true` and the lattice $L$ are returned. If $M$ has more than $n$ submodules, the function aborts and returns the value `false`.

### `SetVerbose("SubmoduleLattice", i): MonStgElt, RngIntElt`

Control verbose printing for the submodule lattice algorithm. The level $i$ can be 2 for maximal printing or 1 for moderate printing. The algorithm works down a composition series of the module and a summary is printed for each level.

### `Submodules(M): ModRng -> [ModRng]`

```magma
CodimensionLimit: RngIntElt                    Default: Dimension(M)
```

Given a $K[G]$-module $M$ defined over $F_q$, return a sequence containing all the submodules of $M$ sorted by dimension.

### `Example: Create Lattice (ex-05bd83)`

We create the lattice of submodules for the $A$-module ${\bf F}_{3}[{\mathbb{Z}}_6]$ with level 1 verbose printing turned on.

```magma
> M := PermutationModule(CyclicGroup(6), GF(3));
> SetVerbose("SubmoduleLattice", 1);
> L := SubmoduleLattice(M);
Submodule Lattice; Dimension: 6, Composition length: 6
Starting level 4; Current number of modules: 2
Starting level 3; Current number of modules: 3
Starting level 2; Current number of modules: 6
Starting level 1; Current number of modules: 9
Starting level 0; Current number of modules: 12
Change basis time: 0.010
Jacobson radical time: 0.060
Complement time: 0.070
Total time: 0.250
> #L;
16

```

## Operations on Lattices

In the following, $L$ is the lattice of submodules for a module $M$.

### `# L: SubModLat -> RngIntElt`

The cardinality of $L$, i.e. the number of submodules of $M$.

### `L ! i: SubModLat, RngIntElt -> SubModLatElt`

Create the $i$-th element of the lattice $L$. The number $i$ is insignificant (i.e. the elements of $L$ are not numbered in any special way), but this allows one to uniquely identify each element of the lattice $L$.

### `L ! S: SubModLat, ModRng -> SubModLatElt`

Create the element of the lattice $L$ corresponding to the submodule $S$ of $M$.

### `Bottom(L): SubModLat -> SubModLatElt`

Create the bottom of the lattice $L$, i.e. the element of $L$ corresponding to the zero-submodule of $M$. If the lattice was created with a limit on the number of submodules and the lattice is partial, the bottom of the lattice may not be the zero submodule.

### `Random(L): SubModLat -> SubModLatElt`

Create a random element of $L$.

### `Top(L): SubModLat -> SubModLatElt`

Create the top of the lattice $L$, i.e. the element of $L$ corresponding to $M$.

## Operations on Lattice Elements

In the following, $L$ is the lattice of submodules for a module $M$. Elements of $L$ are identified with the integers $[1..\#L]$ but not in any particular order.

### `IntegerRing() ! e: RngInt, SubModLatElt -> RngIntElt`

The integer corresponding to lattice element $e$.

### `e + f: SubModLatElt, SubModLatElt -> SubModLatElt`

The sum of lattice elements $e$ and $f$, i.e. the lattice element corresponding to the sum of the modules corresponding to $e$ and $f$.

### `e meet f: SubModLatElt, SubModLatElt -> SubModLatElt`

The intersection of lattice elements $e$ and $f$.

### `e eq f: SubModLatElt, SubModLatElt -> SubModLatElt`

Returns `true` if and only if lattice elements $e$ and $f$ are equal.

### `e subset f: SubModLatElt, SubModLatElt -> SubModLatElt`

Returns `true` if and only if $e$ is under $f$ in the lattice $L$, i.e. the submodule corresponding to $e$ is a submodule of the submodule corresponding to $f$.

### `MaximalSubmodules(e): SubModLatElt -> { SubModLatElt }`

The maximal submodules of $e$, returned as a set of lattice elements.

### `MinimalSupermodules(e): SubModLatElt -> { SubModLatElt }`

The minimal supermodules of $e$, returned as a set of lattice elements.

### `Module(e): SubModLatElt -> ModRng`

The submodule of $M$ corresponding to the element $e$ of the lattice $L$.

## Properties of Lattice Elements

### `Dimension(e): SubModLatElt -> RngIntElt`

The dimension of the submodule of $M$ corresponding to $e$.

### `JacobsonRadical(e): SubModLatElt -> SubModLatElt`

The Jacobson radical of $e$, i.e. the lattice element corresponding to the Jacobson radical of the submodule corresponding to $e$.

### `Morphism(e): SubModLatElt -> ModMatRngElt`

The morphism from the module corresponding to $e$ to $M$.

### `Example: Lattice Ops (ex-42abf7)`

We create the lattice of submodules for the $A$-module ${\bf F}_{3}[{\mathbb{Z}}_6]$.

```magma
> SetSeed(1);
> M := PermutationModule(CyclicGroup(6), GF(3));
> L := SubmoduleLattice(M);
> #L;
16
> T := Top(L);
> B := Bottom(L);
> T;
16
> B;
1
> // Check that element of L corresponding to M is T
> L ! M;
1
> (L ! M) eq T;
true
> // Check that module corresponding to B is zero-submodule of M
> Module(B);
GModule of dimension 0 with base ring GF(3)

```

We next find the minimal supermodules (immediate parents) of $B$ in $L$ and then determine the actual $A$-submodules to which they correspond.

```magma
> S := MinimalSupermodules(B);
> S;
{ 2, 3 }
> Module(L ! 2);
GModule of dimension 1 with base ring GF(3)
> Module(L ! 3);
GModule of dimension 1 with base ring GF(3)
> Dimension(L ! 2);
1
> Morphism(L ! 2);
[1 1 1 1 1 1]
> Morphism(L ! 3);
[1 2 1 2 1 2]
> // Set A to the sum of these elements
> A := L!2 + L!3;
> A;
5;
> // Note that A has dimension 2 and its morphism is the sum of the previous
> Dimension(A);
2
> Morphism(A);
[1 0 1 0 1 0]
[0 1 0 1 0 1]
> MaximalSubmodules(A);
{ 2, 3}
> S!2 subset A;
true

```

We now find the maximal submodules of $L$, and examine one, $S$, in detail.

```magma
> MaximalSubmodules(T);
{ 14, 15 }
> A := L ! 14;
> Dimension(A);
5
> Morphism(A);
[1 0 0 0 0 1]
[0 1 0 0 0 2]
[0 0 1 0 0 1]
[0 0 0 1 0 2]
[0 0 0 0 1 1]
> S := Module(A);
> S;
GModule S of dimension 5 with base ring GF(3)

```

Finally, we compute the Jacobson radical of $S$ directly, and also obtain it from the lattice, checking that the two methods match.

```magma
> J := JacobsonRadical(S);
> J;
GModule J of dimension 3 with base ring GF(3)
> L ! J;
8
> JacobsonRadical(A);
8

```