Submodules

# Submodules

AbstractAlgebra allows the construction of submodules/subvector spaces of AbstractAlgebra modules over euclidean domains. These are given as the submodule generated by a finite list of elements in the original module.

We define two submodules to be equal if they are (transitively) submodules of the same module \$M\$ and their generators generate the same set of elements.

As well as implementing the entire Module interface, AbstractAlgebra submodules also provide the following interface.

## Constructors

``sub(m::AbstractAlgebra.FPModule{T}, gens::Vector{<:AbstractAlgebra.FPModuleElem{T}}) where T <: RingElement``

Return the submodule of the module `m` generated by the given generators, given as elements of `m`.

``sub(m::Module{T}, gens::Vector{<:ModuleElem{T}}) where T <: RingElement``

Return the submodule `S` of the module `m` generated by the given generators, given as elements of `m`, and a map which is the canonical injection from `S` to `m`.

``sub(m::Module{T}, subs::Vector{<:Generic.Submodule{T}}) where T <: RingElement``

Return the submodule `S` of the module `m` generated by the union of the given submodules of \$m\$, and a map which is the canonical injection from `S` to `m`.

Note that the preimage of the canonical injection can be obtained using the preimage function described in the section on module homomorphisms. As the canonical injection is injective, this is unique.

Examples

``````julia> M = FreeModule(ZZ, 2)
Free module of rank 2 over Integers

julia> m = M([ZZ(1), ZZ(2)])
(1, 2)

julia> n = M([ZZ(2), ZZ(-1)])
(2, -1)

julia> N, f = sub(M, [m, n])
(Submodule over Integers with 2 generators and no relations
, Module homomorphism with
Domain: Submodule over Integers with 2 generators and no relations

Codomain: Free module of rank 2 over Integers)

julia> v = N([ZZ(3), ZZ(4)])
(3, 4)

julia> v2 = f(v)
(3, 26)

julia> V = VectorSpace(QQ, 2)
Vector space of dimension 2 over Rationals

julia> m = V([QQ(1), QQ(2)])
(1//1, 2//1)

julia> n = V([QQ(2), QQ(-1)])
(2//1, -1//1)

julia> N, f = sub(V, [m, n])
(Subspace over Rationals with 2 generators and no relations
, Module homomorphism with
Domain: Subspace over Rationals with 2 generators and no relations

Codomain: Vector space of dimension 2 over Rationals)
``````

## Functionality for submodules

In addition to the Module interface, AbstractAlgebra submodules implement the following functionality.

### Basic manipulation

``supermodule(M::Submodule{T}) where T <: RingElement``

Return the module that this module is a submodule of.

``issubmodule(M::AbstractAlgebra.FPModule{T}, N::AbstractAlgebra.FPModule{T}) where T <: RingElement``

Return `true` if \$N\$ was constructed as a submodule of \$M\$. The relation is taken transitively (i.e. subsubmodules are submodules for the purposes of this relation, etc). The module \$M\$ is also considered a submodule of itself for this relation.

``iscompatible(M::AbstractAlgebra.FPModule{T}, N::AbstractAlgebra.FPModule{T}) where T <: RingElement``

Return `true, P` if the given modules are compatible, i.e. that they are (transitively) submodules of the same module, P. Otherwise return `false, M`.

``dim(N::AbstractAlgebra.Generic.Submodule{T}) where T <: FieldElement``

Return the dimension of the given vector subspace.

Examples

``````julia> M = FreeModule(ZZ, 2)
Free module of rank 2 over Integers

julia> m = M([ZZ(2), ZZ(3)])
(2, 3)

julia> n = M([ZZ(1), ZZ(4)])
(1, 4)

julia> N1, = sub(M, [m, n])
(Submodule over Integers with 2 generators and no relations
, Module homomorphism with
Domain: Submodule over Integers with 2 generators and no relations

Codomain: Free module of rank 2 over Integers)

julia> N2, = sub(M, [m])
(Submodule over Integers with 1 generator and no relations
, Module homomorphism with
Domain: Submodule over Integers with 1 generator and no relations

Codomain: Free module of rank 2 over Integers)

julia> supermodule(N1) == M
true

julia> iscompatible(N1, N2)
(true, Free module of rank 2 over Integers)

julia> issubmodule(N1, M)
false

julia> V = VectorSpace(QQ, 2)
Vector space of dimension 2 over Rationals

julia> m = V([QQ(2), QQ(3)])
(2//1, 3//1)

julia> N, = sub(V, [m])
(Subspace over Rationals with 1 generator and no relations
, Module homomorphism with
Domain: Subspace over Rationals with 1 generator and no relations

Codomain: Vector space of dimension 2 over Rationals)

julia> dim(V)
2

julia> dim(N)
1
``````

### Intersection

``Base.intersect(M::AbstractAlgebra.FPModule{T}, N::AbstractAlgebra.FPModule{T}) where T <: RingElement``

Return the intersection of the modules \$M\$ as a submodule of \$M\$. Note that \$M\$ and \$N\$ must be (constructed as) submodules (transitively) of some common module \$P\$.

Examples

``````julia> M = FreeModule(ZZ, 2)
Free module of rank 2 over Integers

julia> m = M([ZZ(2), ZZ(3)])
(2, 3)

julia> n = M([ZZ(1), ZZ(4)])
(1, 4)

julia> N1 = sub(M, [m, n])
(Submodule over Integers with 2 generators and no relations
, Module homomorphism with
Domain: Submodule over Integers with 2 generators and no relations

Codomain: Free module of rank 2 over Integers)

julia> N2 = sub(M, [m])
(Submodule over Integers with 1 generator and no relations
, Module homomorphism with
Domain: Submodule over Integers with 1 generator and no relations

Codomain: Free module of rank 2 over Integers)

julia> I = intersect(N1, N2)
0-element Array{Union{ModuleHomomorphism{BigInt}, Submodule{BigInt}},1}``````