---
title: "Unit Groups"
canonical: "https://docs.magma-maths.org/v2.30-1/GlobalFields/NumberFieldsAndOrders/unit-group.html"
source: "https://docs.magma-maths.org/v2.30-1/GlobalFields/NumberFieldsAndOrders/unit-group.md"
part: "Global Fields"
chapter: "Number Fields and Orders"
breadcrumbs:
  - {"title": "Magma Handbook", "source": "https://docs.magma-maths.org/v2.30-1/index.md"}
  - {"title": "Global Fields", "source": "https://docs.magma-maths.org/v2.30-1/GlobalFields/index-global-fields.md"}
  - {"title": "Number Fields and Orders", "source": "https://docs.magma-maths.org/v2.30-1/GlobalFields/NumberFieldsAndOrders/index-number-fields-and-orders.md"}
prev: {"title": "Ideal Class Groups", "source": "https://docs.magma-maths.org/v2.30-1/GlobalFields/NumberFieldsAndOrders/ideal-class-group.md"}
next: {"title": "Diophantine Equations", "source": "https://docs.magma-maths.org/v2.30-1/GlobalFields/NumberFieldsAndOrders/equation.md"}
intrinsics:
  - {"name": "UnitRank", "signature": "UnitRank(O): RngOrd -> RngIntElt"}
  - {"name": "UnitRank", "signature": "UnitRank(K): FldAlg -> RngIntElt"}
  - {"name": "TorsionUnitGroup", "signature": "TorsionUnitGroup(O): RngOrd -> GrpAb, Map"}
  - {"name": "TorsionUnitGroup", "signature": "TorsionUnitGroup(K): FldNum -> GrpAb, Map"}
  - {"name": "UnitGroup", "signature": "UnitGroup(O): RngOrd -> GrpAb, Map"}
  - {"name": "MultiplicativeGroup", "signature": "MultiplicativeGroup(O): RngOrd -> GrpAb, Map"}
  - {"name": "UnitGroup", "signature": "UnitGroup(K): FldNum -> GrpAb, Map"}
  - {"name": "MultiplicativeGroup", "signature": "MultiplicativeGroup(K): FldNum -> GrpAb, Map"}
  - {"name": "IndependentUnits", "signature": "IndependentUnits(O): RngOrd -> GrpAb, Map"}
  - {"name": "IndependentUnits", "signature": "IndependentUnits(K): FldNum -> GrpAb, Map"}
  - {"name": "pFundamentalUnits", "signature": "pFundamentalUnits(O, p): RngOrd, RngIntElt -> GrpAb, Map"}
  - {"name": "pFundamentalUnits", "signature": "pFundamentalUnits(K, p): FldNum, RngIntElt -> GrpAb, Map"}
  - {"name": "UnitGroupAsSubgroup", "signature": "UnitGroupAsSubgroup(O): RngOrd -> GrpAb"}
  - {"name": "MergeUnits", "signature": "MergeUnits(K, a): FldNum, FldNumElt -> BoolElt"}
  - {"name": "MergeUnits", "signature": "MergeUnits(O, a): RngOrd, RngOrdElt -> BoolElt"}
  - {"name": "IsExceptionalUnit", "signature": "IsExceptionalUnit(u): RngOrdElt -> BoolElt"}
  - {"name": "ExceptionalUnitOrbit", "signature": "ExceptionalUnitOrbit(u): RngOrdElt -> [ RngOrdElt ]"}
  - {"name": "ExceptionalUnits", "signature": "ExceptionalUnits(O): RngOrd -> [ RngOrdElt ]"}
  - {"name": "UnitsWithSigns", "signature": "UnitsWithSigns(O, oo, Signs): RngOrd, [ PlcNumElt ], [ RngInt ] -> [ RngOrdElt ]"}
  - {"name": "UnitsWithSigns", "signature": "UnitsWithSigns(K, oo, Signs): FldAlg, [ PlcNumElt ], [ RngInt ] -> [ FldAlgElt ]"}
  - {"name": "UnitsWithSigns", "signature": "UnitsWithSigns(O, x): RngOrd, RngElt -> [ RngOrdElt ]"}
  - {"name": "UnitsWithSigns", "signature": "UnitsWithSigns(K, x): FldAlg, RngElt -> [ FldAlgElt ]"}
  - {"name": "UnitsWithSigns", "signature": "UnitsWithSigns(x): RngOrdElt -> [ RngOrdElt ]"}
  - {"name": "UnitsWithSigns", "signature": "UnitsWithSigns(x): FldAlgElt -> [ FldAlgElt ]"}
  - {"name": "HasTotallyPositiveGenerator", "signature": "HasTotallyPositiveGenerator(I): RngOrdFracIdl -> BoolElt, [ RngOrdElt ]"}
  - {"name": "TraceMinimalCone", "signature": "TraceMinimalCone(nf): FldNum -> TorCon"}
examples:
  - "ex-98001b"
---

<a id="unit-group"></a>
<a id="rngord-unit"></a>
# 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`](https://docs.magma-maths.org/v2.30-1/GlobalFields/NumberFieldsAndOrders/unit-group.md#function-rngord-unitgroup) and `IndependentUnits` below.

Previously, some of the algorithms described in [[PZ89](https://docs.magma-maths.org/v2.30-1/references.md#cite-pohst1)], (pp. 343–344), and in [[Poh93](https://docs.magma-maths.org/v2.30-1/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.

<a id="function-unitrank-rngord-2"></a>
## `UnitRank(O): RngOrd -> RngIntElt`

<a id="function-unitrank-fldalg"></a>
## `UnitRank(K): FldAlg -> RngIntElt`

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

<a id="function-torsionunitgroup-rngord"></a>
## `TorsionUnitGroup(O): RngOrd -> GrpAb, Map`

<a id="function-torsionunitgroup-fldnum"></a>
## `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)`.

<a id="function-rngord-unitgroup"></a>
## `UnitGroup(O): RngOrd -> GrpAb, Map`

<a id="function-multiplicativegroup-rngord"></a>
## `MultiplicativeGroup(O): RngOrd -> GrpAb, Map`

```magma
Al       : MonStgElt                    Default: "Automatic"
GRH      : BoolElt                      Default: false
UnitGroup: Verbose                      Default: 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](https://docs.magma-maths.org/v2.30-1/GlobalFields/NumberFieldsAndOrders/ideal-class-group.md#rngord-clg)), and then call `IndependentUnits` (see below).

<a id="function-unitgroup-fldnum"></a>
## `UnitGroup(K): FldNum -> GrpAb, Map`

<a id="function-multiplicativegroup-fldnum"></a>
## `MultiplicativeGroup(K): FldNum -> GrpAb, Map`

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

<a id="function-independentunits-rngord"></a>
## `IndependentUnits(O): RngOrd -> GrpAb, Map`

<a id="function-independentunits-fldnum"></a>
## `IndependentUnits(K): FldNum -> GrpAb, Map`

```magma
Al       : MonStgElt                    Default: "Automatic"
UnitGroup: Verbose                      Default: 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`](https://docs.magma-maths.org/v2.30-1/GlobalFields/NumberFieldsAndOrders/operation.md#procedure-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.

<a id="function-pfundamentalunits-rngord-rngintelt"></a>
## `pFundamentalUnits(O, p): RngOrd, RngIntElt -> GrpAb, Map`

<a id="function-pfundamentalunits-fldnum-rngintelt"></a>
## `pFundamentalUnits(K, p): FldNum, RngIntElt -> GrpAb, Map`

```magma
Al       : MonStgElt                    Default: "Automatic"
UnitGroup: Verbose                      Default: 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$.

<a id="function-unitgroupassubgroup-rngord"></a>
## `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, [[PK05](https://docs.magma-maths.org/v2.30-1/references.md#cite-kluenerspauli2005)].

<a id="function-mergeunits-fldnum-fldnumelt"></a>
## `MergeUnits(K, a): FldNum, FldNumElt -> BoolElt`

<a id="function-mergeunits-rngord-rngordelt"></a>
## `MergeUnits(O, a): RngOrd, RngOrdElt -> BoolElt`

```magma
UnitGroup: Verbose                    Default: 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.

<a id="example-ex-98001b"></a>
## `Example: Class and Unit Groups of a Quartic Field (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
```

<a id="function-isexceptionalunit-rngordelt"></a>
## `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.

<a id="function-exceptionalunitorbit-rngordelt"></a>
## `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)$.

<a id="function-exceptionalunits-rngord"></a>
## `ExceptionalUnits(O): RngOrd -> [ RngOrdElt ]`

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

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

<a id="function-unitswithsigns-rngord-plcnumelt-rngint"></a>
## `UnitsWithSigns(O, oo, Signs): RngOrd, [ PlcNumElt ], [ RngInt ] -> [ RngOrdElt ]`

<a id="function-unitswithsigns-fldalg-plcnumelt-rngint"></a>
## `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]$.

<a id="function-unitswithsigns-rngord-rngelt"></a>
## `UnitsWithSigns(O, x): RngOrd, RngElt -> [ RngOrdElt ]`

<a id="function-unitswithsigns-fldalg-rngelt"></a>
## `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$.

<a id="function-unitswithsigns-rngordelt"></a>
## `UnitsWithSigns(x): RngOrdElt -> [ RngOrdElt ]`

<a id="function-unitswithsigns-fldalgelt"></a>
## `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$.

<a id="function-hastotallypositivegenerator-rngordfracidl"></a>
## `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.

<a id="function-traceminimalcone-fldnum"></a>
## `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.
