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 and IndependentUnits below.

Previously, some of the algorithms described in [PZ89], (pp. 343--344), and in [Poh93] 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
    Al: MonStgElt                       Default: "Automatic"
    GRH: BoolElt                        Default: false
    SetVerbose("UnitGroup", n):         Maximum: 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≤i≤r1 + r2.

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), 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
    Al: MonStgElt                       Default: "Automatic"
    SetVerbose("UnitGroup", n):         Maximum: 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(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
    Al: MonStgElt                       Default: "Automatic"
    SetVerbose("UnitGroup", n):         Maximum: 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, [PK05].
MergeUnits(K, a) : FldNum, FldNumElt -> BoolElt
MergeUnits(O, a) : RngOrd, RngOrdElt -> BoolElt
    SetVerbose("UnitGroup", n):         Maximum: 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∈O, add the unit to the already known subgroup of UO 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 RngOrd_UnitGroup (H39E20)

In our field defined by x4 - 420 * x2 + 40000, we obtain the class and unit groups as follows.
> 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 u1=u, u2=(1/u), u3=1 - u, u4=(1/(1 - u)), u5=((u - 1)/u), u6=(u/(u - 1)) are exceptional. The set Ω(u) formed by u1, ..., u6 is called the orbit of u. Usually it will have 6 elements. This function returns a sequence containing the elements of Ω(u).
ExceptionalUnits(O) : RngOrd -> [ RngOrdElt ]
    SetVerbose("UnitEq", n):            Maximum: 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.
V2.28, 13 July 2023