# Elements

## Construction of Elements

Unless otherwise stated, the operations in this section apply to fp-abelian groups and generic abelian groups.

### `A ! [a₁, ... ,aₙ]: GrpAb, [RngIntElt] -> GrpAbElt`

### `A ! [a₁, ... ,aₙ]: GrpAbGen, [RngIntElt] -> GrpAbGenElt`

Given an abelian group $A$ with generators $e_1, \ldots, e_r$ and a sequence $Q = [a_1, \cdots, a_r]$ of integers, construct the element $a_1 e_1 + \cdots + a_r e_r$ of $A$.

### `A ! e: GrpAbGen, Elt -> GrpAbGenElt`

Given a generic abelian group $A$ and an element $e$ of the domain over which it is defined, return $e$ as an element of $A$. If $A$ is a proper subset of its underlying domain, then $e$ must be a linear combination of the generators (which may be user-supplied) of $A$.

### `A ! g: GrpAbGen, GrpAbGenElt -> GrpAbGenElt`

Given a generic abelian group $A$ and an element $g$ of the underlying set $X$ of $A$, return $g$ as an element of $A$.

### `A ! n: GrpAb, RngIntElt -> GrpAbElt`

Given an abelian group $A$ with exactly one generator $x$, construct the element $n x$.

### `Random(A): GrpAbGen -> GrpAbGenElt`

Given either a finite fp-abelian group or a generic abelian group $A$, return a random element of $A$.

### `Identity(A): GrpAb -> GrpAbElt`

### `Id(A): GrpAb -> GrpAbElt`

### `A ! 0: GrpAb, RngIntElt -> GrpAbElt`

Construct the identity element (empty word) for the abelian group $A$.

Let $A$ be a generic abelian group defined in the universe $U$ of $A$. If $g$ is an element of $A$, then $U!g$ is an element of $U$.

## Representation of an Element

An element $g$ of an abelian group $A$ can be represented as a linear combination with respect to a given generating sequence. The coefficients appearing in this linear combination provide an alternative representation for $g$. If $A$ is a fp-group, the generating set will be the one on which the group was defined. In the case of a generic group, the generating set can either be that obtained when constructing a presentation for $A$ or a user-supplied generating set.

### `Representation(g): GrpAbGenElt -> [RngIntElt]`

### `ElementToSequence(g): GrpAbGenElt -> [RngIntElt]`

### `Eltseq(g): GrpAbGenElt -> [RngIntElt]`

Let $A$ be an abelian group with generating set $e_1, \ldots, e_n$ and suppose $g$ is an element of $A$, where $g = a_1 e_1 + \ldots + a_n e_n$. These functions return the sequence $Q$ of $n$ integers defined by $Q[i] = {a_i}$, for $i = 1,\ldots,n$. Moreover, each $a_i$, $i = 1,\ldots,n$, is the integer residue modulus the order of the $i$th generator.

### `UserRepresentation(g): GrpAbGenElt -> [RngIntElt]`

Let $A$ be a generic abelian group with a user-supplied set of generators $u_1, \ldots, u_n$ and suppose $g$ is an element of $A$, where $g = a_1 u_1 + \ldots + a_n u_n$. This function returns the sequence $Q$ of $n$ integers defined by $Q[i] = {a_i}$, for $i = 1,\ldots,n$. Moreover, each $a_i$, $i = 1,\ldots,n$, is the integer residue modulus the order of the $i$th generator.

### `Representation(S, g): SeqEnum, GrpAbGenElt -> [RngIntElt], RngIntElt`

Let $A$ be a generic abelian group and let $S = [s_1, \dots, s_m]$ be any sequence of elements of $A$. Assume $g$ is an element of $A$ such that $b g = a_1 s_1 + \ldots + a_m s_m$. This function returns as its first value the sequence $Q$ of $m$ integers defined by $Q[i] = {a_i}$, for $i = 1,\ldots,m$. The second value returned is the coefficient $b$ of $g$. Note that $b$ might not be 1.

### `Example: Element Creation And Rep (ex-f86c65)`

We use the quadratic forms example considered above to illustrate these functions.

```magma
> Generators(QF);
[ <2,2,500001>, <206,-102,4867> ]
> g := QF ! [5, 6];
> g;
<837,-766,1370>
> Representation(g);
[ 1, 6 ]
>
> g := Random(QF);
> Representation(g);
[ 1, 270 ]
>
> UserRepresentation(g);
[ 377, 0, 515, 0, 0, 0, 0, 0, 0, 0 ]
>
> S := [];
> for i in [1..3] do
>     d := Random(QF);
>     Include(~S, d);
> end for;
> seq, coeff := Representation(S, g);
> seq; coeff;
[ -170, -3, 0 ]
1

```

## Arithmetic with Elements

If the generic abelian group $A$ has been constructed with the flag `UseRepresentation` set true, then arithmetic with elements of $A$ is trivial.

### `u + v: GrpAbElt, GrpAbElt -> GrpAbElt`

Given elements $u$ and $v$ belonging to the same abelian group $A$, return the sum of $u$ and $v$.

### `- u: GrpAbElt -> GrpAbElt`

The inverse of element $u$.

### `u - v: GrpAbElt, GrpAbElt -> GrpAbElt`

Given elements $u$ and $v$ belonging to the same abelian group $A$, return the sum of $u$ and the inverse of $v$.

### `m * u: RngIntElt, GrpAbElt -> GrpAbElt`

### `u * m: GrpAb, RngIntElt -> GrpAbElt`

Given an integer $m$, return the element $w+w+\cdots w$ ($|m|$ summands), where $w = u$, if $m$ is positive and $w = -u$ if $m$ is negative.