# Construction of Subgroups and Quotient Groups

The operations in this section apply to both, free abelian groups and arbitrary abelian groups.

## Construction of Subgroups

### `sub<A | L>: GrpAb, List -> GrpAb, Map`

Construct the subgroup $B$ of the abelian group $A$ generated by the elements specified by the terms of the *generator list* $L$. A term $L[i]$ of the generator list may consist of any of the following objects:

**(a)**
An element liftable to A;

**(b)**
A sequence of integers representing an element of A;

**(c)**
A subgroup of $A$;

**(d)**
A set or sequence of type (a), (b), or (c).

The collection of words and groups specified by the list must all belong to the group $A$ and the group $B$ will be constructed as a subgroup of $A$.

### `Example: Subgroup Creation (ex-f256c6)`

We create a subgroup of the group $A = Z_2 + Z_3 + Z_4 + Z_5 + Z_6 + Z + Z$.

```magma
> A<[x]> := AbelianGroup([2,3,4,5,6,0,0]);
> A;
Abelian Group isomorphic to Z/2 + Z/6 + Z/60 + Z + Z
Defined on 7 generators
Relations:
    2*x[1] = 0
    3*x[2] = 0
    4*x[3] = 0
    5*x[4] = 0
    6*x[5] = 0
> B<[y]> := sub< A | x[1], x[3], x[5], x[7] >;
> B;
Abelian Group isomorphic to Z/2 + Z/2 + Z/12 + Z
Defined on 4 generators in supergroup A:
    y[1] = 2*x[3] + 3*x[5]
    y[2] = x[1]
    y[3] = 3*x[3] + x[5]
    y[4] = x[7]
Relations:
    2*y[1] = 0
    2*y[2] = 0
    12*y[3] = 0

```

In the case of subgroups of generic groups, a number of parameters are provided.

### `sub<A | L: parameters>: GrpAbGen, List -> GrpAbGen`

```magma
Order            : RngInt                    Default: 
RandomIntrinsic  : MonStg                    Default: 
ComputeStructure : Bool                      Default: false
UseUserGenerators: Bool                      Default: false
PollardRhoRParam : RngInt                    Default: 20
PollardRhoTParam : RngInt                    Default: 8
PollardRhoVParam : RngInt                    Default: 3
```

Construct the subgroup of the generic abelian group $A$ generated by the elements specified by the terms of the *generator list* $L$. A term $L[i]$ of the generator list may consist of any of the following objects:

**(a)**
An element liftable into $A$;

**(b)**
A sequence of integers representing an element of $A$;

**(c)**
A set or sequence whose elements may be of either of the above types.

An element liftable into $A$ may be an element of $A$ itself, or it may be an element of $U$ (`Universe(U)`), $U$ being as usual the domain over which $A$ is defined. For consistency with the construction, the values of the following parameters may also be passed to the subgroup constructor:

In particular, it is possible to construct a subgroup by giving its order and a random function generating elements of the *subgroup*. In this case, the list $L$ would be empty since calculation of the subgroup structure would result in the construction of the $p$-Sylow subgroups from random elements of the subgroup. Further, when the structure of $A$ is already known and if the subgroup is defined in terms of a set of generators in $L$ then the subgroup structure is computed at the time of creation.

### `Example: Generic Subgroup Creation (ex-8e5822)`

We create a subgroup of the quadratic forms group considered above.

```magma
> S := [];
> for j in [1..2] do
>     P := Random(QF);
>     Include(~S, P);
> end for;
> S;
[ <45,26,22226>, <937,-930,1298> ]
> QF1 := sub< QF | S>;
> QF1;
Generic Abelian Group over
Binary quadratic forms of discriminant -4000004
Abelian Group isomorphic to Z/2 + Z/258
Defined on 2 generators in supergroup A:
  QF1.1 = QF.1
  QF1.2 = 2*QF.2
Relations:
  2*QF1.1 = 0
  258*QF1.2 = 0
>

```

## Construction of Quotient Groups

### `quo<F | R>: GrpAb, List -> GrpAb, Hom(GrpAb)`

Given an abelian group $F$, and a set of relations $R$ in the generators of $F$, construct (a) an abelian group $A$ isomorphic to the quotient of $F$ by the subgroup of $F$ defined by $R$, and (b) the natural homomorphism $\phi : F \rightarrow A$.

The expression defining $F$ may be either simply the name of a previously constructed group, or an expression defining an abelian group. The possibilities for the relation list $R$ are the same as for the `AbelianGroup` construction.

The function returns:

**(a)**
The quotient group $A$;

**(b)**
The natural homomorphism $\phi : F \rightarrow A$.

### `A / B: GrpAb, GrpAb -> GrpAb`

Given a subgroup $B$ of the abelian group $A$, construct the quotient of $A$ by $B$.