---
title: "Lattice of Submodules"
canonical: "https://docs.magma-maths.org/v2.30-1/RepresentationTheory/ModulesOverAnAlgebraAndGroupRepresentations/submodule-lattice.html"
source: "https://docs.magma-maths.org/v2.30-1/RepresentationTheory/ModulesOverAnAlgebraAndGroupRepresentations/submodule-lattice.md"
part: "Representation Theory"
chapter: "Modules over an Algebra and Group Representations"
breadcrumbs:
  - {"title": "Magma Handbook", "source": "https://docs.magma-maths.org/v2.30-1/index.md"}
  - {"title": "Representation Theory", "source": "https://docs.magma-maths.org/v2.30-1/RepresentationTheory/index-representation-theory.md"}
  - {"title": "Modules over an Algebra and Group Representations", "source": "https://docs.magma-maths.org/v2.30-1/RepresentationTheory/ModulesOverAnAlgebraAndGroupRepresentations/index-modules-over-an-algebra-and-group-representations.md"}
prev: {"title": "Constructing All Irreducible $K[G]$-Modules", "source": "https://docs.magma-maths.org/v2.30-1/RepresentationTheory/ModulesOverAnAlgebraAndGroupRepresentations/constructing-all-irred.md"}
next: {"title": "Homomorphisms", "source": "https://docs.magma-maths.org/v2.30-1/RepresentationTheory/ModulesOverAnAlgebraAndGroupRepresentations/homomorphism.md"}
intrinsics:
  - {"name": "SubmoduleLattice", "signature": "SubmoduleLattice(M): ModRng -> SubModLat, BoolElt"}
  - {"name": "SubmoduleLatticeAbort", "signature": "SubmoduleLatticeAbort(M, n): ModRng, RngIntElt -> BoolElt, SubModLat"}
  - {"name": "SetVerbose", "signature": "SetVerbose(\"SubmoduleLattice\", i): MonStgElt, RngIntElt"}
  - {"name": "Submodules", "signature": "Submodules(M): ModRng -> [ModRng]"}
  - {"name": "#", "signature": "# L: SubModLat -> RngIntElt"}
  - {"name": "!", "signature": "L ! i: SubModLat, RngIntElt -> SubModLatElt"}
  - {"name": "!", "signature": "L ! S: SubModLat, ModRng -> SubModLatElt"}
  - {"name": "Bottom", "signature": "Bottom(L): SubModLat -> SubModLatElt"}
  - {"name": "Random", "signature": "Random(L): SubModLat -> SubModLatElt"}
  - {"name": "Top", "signature": "Top(L): SubModLat -> SubModLatElt"}
  - {"name": "!", "signature": "IntegerRing() ! e: RngInt, SubModLatElt -> RngIntElt"}
  - {"name": "+", "signature": "e + f: SubModLatElt, SubModLatElt -> SubModLatElt"}
  - {"name": "meet", "signature": "e meet f: SubModLatElt, SubModLatElt -> SubModLatElt"}
  - {"name": "eq", "signature": "e eq f: SubModLatElt, SubModLatElt -> SubModLatElt"}
  - {"name": "subset", "signature": "e subset f: SubModLatElt, SubModLatElt -> SubModLatElt"}
  - {"name": "MaximalSubmodules", "signature": "MaximalSubmodules(e): SubModLatElt -> { SubModLatElt }"}
  - {"name": "MinimalSupermodules", "signature": "MinimalSupermodules(e): SubModLatElt -> { SubModLatElt }"}
  - {"name": "Module", "signature": "Module(e): SubModLatElt -> ModRng"}
  - {"name": "Dimension", "signature": "Dimension(e): SubModLatElt -> RngIntElt"}
  - {"name": "JacobsonRadical", "signature": "JacobsonRadical(e): SubModLatElt -> SubModLatElt"}
  - {"name": "Morphism", "signature": "Morphism(e): SubModLatElt -> ModMatRngElt"}
examples:
  - "ex-05bd83"
  - "ex-42abf7"
---

# 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

<a id="function-submodulelattice-modrng"></a>
### `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$.

<a id="function-submodulelatticeabort-modrng-rngintelt"></a>
### `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`.

<a id="procedure-setverbose-monstgelt-rngintelt-submodulelattice"></a>
### `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.

<a id="function-repthy-submodules"></a>
### `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.

<a id="example-ex-05bd83"></a>
### `Example: Creating a Submodule 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$.

<a id="operation-operation-submodlat-rngintelt"></a>
### `# L: SubModLat -> RngIntElt`

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

<a id="operation-op-submodlat-rngintelt"></a>
### `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$.

<a id="operation-op-submodlat-modrng"></a>
### `L ! S: SubModLat, ModRng -> SubModLatElt`

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

<a id="function-bottom-submodlat"></a>
### `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.

<a id="function-random-submodlat"></a>
### `Random(L): SubModLat -> SubModLatElt`

Create a random element of $L$.

<a id="function-top-submodlat"></a>
### `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.

<a id="operation-integerring-rngint-submodlatelt"></a>
### `IntegerRing() ! e: RngInt, SubModLatElt -> RngIntElt`

The integer corresponding to lattice element $e$.

<a id="operation-op-plus-submodlatelt-submodlatelt"></a>
### `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$.

<a id="operation-op-meet-submodlatelt-submodlatelt"></a>
### `e meet f: SubModLatElt, SubModLatElt -> SubModLatElt`

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

<a id="operation-op-eq-submodlatelt-submodlatelt"></a>
### `e eq f: SubModLatElt, SubModLatElt -> SubModLatElt`

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

<a id="operation-op-subset-submodlatelt-submodlatelt"></a>
### `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$.

<a id="function-maximalsubmodules-submodlatelt"></a>
### `MaximalSubmodules(e): SubModLatElt -> { SubModLatElt }`

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

<a id="function-minimalsupermodules-submodlatelt"></a>
### `MinimalSupermodules(e): SubModLatElt -> { SubModLatElt }`

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

<a id="function-module-submodlatelt"></a>
### `Module(e): SubModLatElt -> ModRng`

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

## Properties of Lattice Elements

<a id="function-dimension-submodlatelt"></a>
### `Dimension(e): SubModLatElt -> RngIntElt`

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

<a id="function-jacobsonradical-submodlatelt"></a>
### `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$.

<a id="function-morphism-submodlatelt"></a>
### `Morphism(e): SubModLatElt -> ModMatRngElt`

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

<a id="example-ex-42abf7"></a>
### `Example: Operations in a Submodule Lattice (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
```
