# Unit Groups

For most number fields, the algorithm used to compute the unit group involves computing the class group and obtaining units from the ‘class group relations’. If a class group has already been computed for the field, these ‘unit relations’ are already stored; otherwise, the standard class group computation will be performed first.

The unit group routine is fully rigorous, even when the class group computation is not. For details see [`UnitGroup`](#function-rngord-unitgroup) and `IndependentUnits` below.

Previously, some of the algorithms described in [[Pohst and Zassenhaus, 1989](../../references.md#cite-pohst1)], (pp. 343–344), and in [[Pohst, 1993](../../references.md#cite-pohst2)] were used but since V2.21 the class group, computed assuming GRH if not already computed, is used to compute the independent units.

## `UnitRank(O): RngOrd -> RngIntElt`

## `UnitRank(K): FldAlg -> RngIntElt`

The free rank of the group of units in the ring of integers $O$ (of a number field $K$).

## `TorsionUnitGroup(O): RngOrd -> GrpAb, Map`

## `TorsionUnitGroup(K): FldNum -> GrpAb, Map`

The torsion subgroup of the unit group of the order $O$, or, in case of a number field $K$, of its maximal order $O$. The torsion subgroup is returned as an abelian group $T$, together with a map $m$ from the group to the order $O$. The torsion subgroup will be cyclic, and is generated by `m(T.1)`.

## `UnitGroup(O): RngOrd -> GrpAb, Map`

## `MultiplicativeGroup(O): RngOrd -> GrpAb, Map`

```magma
Al     : MonStgElt                    Default: "Automatic"
GRH    : BoolElt                      Default: false
verbose: UnitGroup                    Default: Verbose : 6
```

Given an order $O$ in a number field, this function returns an (abstract) abelian group $U$, as well as a bijection $m$ between $U$ and the units of the order. The unit group consists of the torsion subgroup, generated by the image `m(U.1)` and a free part, generated in $O$ by the images `m(U.i)` for $2\leq i\leq r_1+r_2$. By default, `UnitGroup` performs a proof phase, to verify rigorously that the unit group returned is the full unit group rather than a finite index subgroup. This is done even when the class group computation was only heuristic. It is done by a different method than the proof phase for the class group (and it does not prove the class group). When `UnitGroup` is called with the option `GRH` set to `true`, this proof phase is skipped, which means the calculation has the same level of rigour as the class group computation. This is equivalent to doing the following: first compute a class group, specifying the rigour of that computation (see [Ideal Class Groups](ideal-class-group.md#rngord-clg)), and then call `IndependentUnits` (see below).

## `UnitGroup(K): FldNum -> GrpAb, Map`

## `MultiplicativeGroup(K): FldNum -> GrpAb, Map`

This is identical to `UnitGroup(MaximalOrder(K))`.

## `IndependentUnits(O): RngOrd -> GrpAb, Map`

## `IndependentUnits(K): FldNum -> GrpAb, Map`

```magma
Al     : MonStgElt                    Default: "Automatic"
verbose: UnitGroup                    Default: Verbose : 6
```

This function is an alternative to `UnitGroup` which returns a subgroup of finite index in the unit group. The arguments and return values are the same as for `UnitGroup`. In the current implementation, `IndependentUnits` returns the full unit group whenever the class group computation is correct. This is always the case if the GRH holds. After calling `IndependentUnits(O)`, if [`SetOrderUnitsAreFundamental`](operation.md#function-rngord-setorderunitsarefundamental)`(O)` is invoked Magma will assume this unit group is the full unit group in all subsequent calculations with the same number field.

## `pFundamentalUnits(O, p): RngOrd, RngIntElt -> GrpAb, Map`

## `pFundamentalUnits(K, p): FldNum, RngIntElt -> GrpAb, Map`

```magma
Al     : MonStgElt                    Default: "Automatic"
verbose: UnitGroup                    Default: Verbose : 6
```

Given a maximal order $O$ in a number field, this function returns an (abstract) abelian group $U$, as well as a map $m$ from $U$ to the order. $U$ will be a subgroup (of finite index) of the unit group $G$ such that $p$ does not divide the index $(G:U)$ where $p$ is the prime number given. If a field $K$ is given rather than an order, the above is computed for the maximal order of $K$.

## `UnitGroupAsSubgroup(O): RngOrd -> GrpAb`

For a (possibly non-maximal) order $O$ in some absolute field $K$, return the unit group of $O$ as a subgroup of the unit group of the maximal order of $O$. The algorithm and its implementation is due to Klüners and Pauli, [[Pauli and Klüners, 2005](../../references.md#cite-kluenerspauli2005)].

## `MergeUnits(K, a): FldNum, FldNumElt -> BoolElt`

## `MergeUnits(O, a): RngOrd, RngOrdElt -> BoolElt`

```magma
verbose: UnitGroup                    Default: Verbose : 6
```

This function is largely irrelevant in the current implementation.

For an order $O$ or a number field with maximal order $O$ and a unit $a\in O$, add the unit to the already known subgroup of $U_O$ that is stored in $O$. Returns `true` if and only if the rank of the currently known unit group of $O$ or $K$ increases when $a$ is merged with it.

## `Example: Unit Group (ex-98001b)`

In our field defined by $x^4 - 420*x^2 + 40000$, we obtain the class and unit groups as follows.

```magma
> R<x> := PolynomialRing(Integers());
> f := x^4 - 420*x^2 + 40000;
> K<y> := NumberField(f);
> C := ClassGroup(K);
> C;
Abelian Group of order 1
> U := UnitGroup(K);
> U;
Abelian Group isomorphic to Z/2 + Z + Z + Z
Defined on 4 generators
Relations:
      2*U.1 = 0
> T := TorsionUnitGroup(K);
> T;
Abelian Group isomorphic to Z/2
Defined on 1 generator
Relations:
    2*T.1 = 0

```

## `IsExceptionalUnit(u): RngOrdElt -> BoolElt`

An element $x$ of an order $O$ is an exceptional unit if both $x$ and $x-1$ are units in $O$. This function returns `true` if and only if the order element $u$ is an exceptional unit.

## `ExceptionalUnitOrbit(u): RngOrdElt -> [ RngOrdElt ]`

If $u$ is an exceptional unit of an order $O$, then all of the units $u_1=u$, $u_2={1\over u}$, $u_3=1-u$, $u_4={1\over {1-u}}$, $u_5={{u-1}\over u}$, $u_6={u\over {u-1}}$ are exceptional. The set $\Omega(u)$ formed by $u_1, \ldots, u_6$ is called the *orbit* of $u$. Usually it will have 6 elements. This function returns a sequence containing the elements of $\Omega(u)$.

## `ExceptionalUnits(O): RngOrd -> [ RngOrdElt ]`

```magma
verbose: UnitEq                    Default: Verbose : 5
```

This function returns a sequence $S$ of exceptional units of the order $O$.

## `UnitsWithSigns(O, oo, Signs): RngOrd, [ PlcNumElt ], [ RngInt ] -> [ RngOrdElt ]`

## `UnitsWithSigns(K, oo, Signs): FldAlg, [ PlcNumElt ], [ RngInt ] -> [ FldAlgElt ]`

Returns all units in $O$ (or the ring of integers of $K$) modulo squares that have sign $Signs[i]$ at the i-th real place given in $oo[i]$.

## `UnitsWithSigns(O, x): RngOrd, RngElt -> [ RngOrdElt ]`

## `UnitsWithSigns(K, x): FldAlg, RngElt -> [ FldAlgElt ]`

Returns all units in $O$ (or the ring of integers of $K$) modulo squares that have the same signs at the real places of $O$ as the element $x$.

## `UnitsWithSigns(x): RngOrdElt -> [ RngOrdElt ]`

## `UnitsWithSigns(x): FldAlgElt -> [ FldAlgElt ]`

Given an element $x$ in an order $O$ or a number field $K$, return all units of $O$ (or the ring of integers of $K$) modulo squares that have the same signs at the real places of $O$ as $x$.

## `HasTotallyPositiveGenerator(I): RngOrdFracIdl -> BoolElt, [ RngOrdElt ]`

Decides if $I$ is generated by some totally positive element. If so, the second return value contains all such generators up to squares.

## `TraceMinimalCone(nf): FldNum -> TorCon`

Given a totally real number field, find the trace-minimal cone, which is a fundamental domain for the action of the totally positive units.