# The Unit Group

## `UnitGroup(R): RngIntRes -> GrpAb, Map`

Given $R={{\mathbb{Z}}/m{\mathbb{Z}}}$, construct the unit group of $R$ as an abelian group. This returns an (additive) abelian group $A$ of order $\phi(m)$, together with a map from $A$ to $R$.

## `IsPrimitive(n): RngIntResElt -> BoolElt`

Returns `true` if the element $n\in{{\mathbb{Z}}/m{\mathbb{Z}}}$ is primitive, that is, if it generates the multiplicative group of ${{\mathbb{Z}}/m{\mathbb{Z}}}$, `false` otherwise.

## `PrimitiveElement(R): RngIntRes -> RngIntResElt`

## `PrimitiveRoot(R): RngIntRes -> RngIntResElt`

Given $R = {\mathbb{Z}}/m{\mathbb{Z}}$, this function returns a generator for the group of units of $R$ if this group is cyclic, and returns $0$ otherwise. Thus a valid generator is only returned if $m = 2, 4, p^t$ or $2p^t$, with $p$ an odd prime and $t\geq 1$.

## `Order(a): RngIntResElt -> RngIntElt`

Given an element $a$ belonging to ${{\mathbb{Z}}/m{\mathbb{Z}}}$, return the multiplicative order $k \geq 1$ of $a$ if $a$ is in the unit group ${({{\mathbb{Z}}/m{\mathbb{Z}}})^*}$, and zero if $a$ is not a unit.

## `Normalize(x): RngIntRes -> RngIntResElt, RngIntResElt`

## `Normalise(x): RngIntRes -> RngIntResElt, RngIntResElt`

Given an element $x\in R = {\mathbb{Z}}/m{\mathbb{Z}}$, this function returns the unique canonical associate $y\in R$ of $x$ and a unit $u\in R$ such that $u\cdot x = y$. The canonical associate of $x$ is the GCD of $x$ and $m$, considered as natural integers (unless $x$ is 0, in which case it is 0).

## `Example: Unit Group (ex-8ae5da)`

We determine the unit group of the ring with modulus $735$ and then verify its order by comparing it with $\phi(m)$.

```magma
> m := 735;
> R := ResidueClassRing(m);
Residue class ring of integers modulo 735
> U, psi := UnitGroup(R);
> U;
Abelian Group isomorphic to Z/2 + Z/2 + Z/84
Defined on 3 generators
Relations:
    2*U.1 = 0
    4*U.2 = 0
    42*U.3 = 0
> #U;
336
> EulerPhi(735);
336

```

So the order of $U$ is equal to $\phi(m)$ as it should be. Finally, we look for three elements of $R$ that generate the unit group.

```magma
> gens := [ psi(U.i) : i in [1..3] ]; gens;
> [ Order(x) : x in gens ];
[ 2, 4, 42 ]

```

## `Example: Cyclic Unit Group (ex-bde8d2)`

We construct a residue class ring $R = {\mathbb{Z}}/m{\mathbb{Z}}$ having cyclic unit group. By a theorem of Gauss, the ring $R$ has cyclic unit group precisely when $n = 4, n = p^e,$ or $n = 2p^e$, and $p$ is an odd prime.

```magma
> R := IntegerRing(50);
> U, psi := UnitGroup(R);
Abelian Group isomorphic to Z/20
Defined on 1 generator
Relations:
    20*U.1 = 0
> w := PrimitiveElement(R);
> w;
3
> Order(w);
20

```

We verify that the powers of $w$ are precisely the elements of the unit group $U$.

```magma
> powers := { w^i : i in [0..19] };
> powers;
{ 29, 1, 31, 3, 33, 7, 37, 9, 39, 11, 41, 13, 43, 17, 47, 19, 49, 21, 23, 27 }
> powers eq { psi(u) : u in U };
true

```