Unit and S-unit groups of Number Fields

EXAMPLES:

sage: x = polygen(QQ)
sage: K.<a> = NumberField(x^4-8*x^2+36)
sage: UK = UnitGroup(K); UK
Unit group with structure C4 x Z of Number Field in a with defining polynomial x^4 - 8*x^2 + 36

The first generator is a primitive root of unity in the field:

sage: UK.gens()
(u0, u1)
sage: UK.gens_values()  # random
[-1/12*a^3 + 1/6*a, 1/24*a^3 + 1/4*a^2 - 1/12*a - 1]
sage: UK.gen(0).value()
-1/12*a^3 + 1/6*a

sage: UK.gen(0)
u0
sage: UK.gen(0) + K.one()   # coerce abstract generator into number field
-1/12*a^3 + 1/6*a + 1

sage: [u.multiplicative_order() for u in UK.gens()]
[4, +Infinity]
sage: UK.rank()
1
sage: UK.ngens()
2

Units in the field can be converted into elements of the unit group represented as elements of an abstract multiplicative group:

sage: UK(1)
1
sage: UK(-1)
u0^2
sage: [UK(u) for u in (x^4-1).roots(K, multiplicities=False)]
[1, u0^2, u0^3, u0]

sage: UK.fundamental_units() # random
[1/24*a^3 + 1/4*a^2 - 1/12*a - 1]
sage: torsion_gen = UK.torsion_generator();  torsion_gen
u0
sage: torsion_gen.value()
-1/12*a^3 + 1/6*a
sage: UK.zeta_order()
4
sage: UK.roots_of_unity()
[-1/12*a^3 + 1/6*a, -1, 1/12*a^3 - 1/6*a, 1]

Exp and log functions provide maps between units as field elements and exponent vectors with respect to the generators:

sage: u = UK.exp([13,10]); u # random
-41/8*a^3 - 55/4*a^2 + 41/4*a + 55
sage: UK.log(u)
(1, 10)
sage: u = UK.fundamental_units()[0]
sage: [UK.log(u^k) == (0,k) for k in range(10)]
[True, True, True, True, True, True, True, True, True, True]
sage: all([UK.log(u^k) == (0,k) for k in range(10)])
True

sage: K.<a> = NumberField(x^5-2,'a')
sage: UK = UnitGroup(K)
sage: UK.rank()
2
sage: UK.fundamental_units()
[a^3 + a^2 - 1, a - 1]

S-unit groups may be constructed, where S is a set of primes:

sage: K.<a> = NumberField(x^6+2)
sage: S = K.ideal(3).prime_factors(); S
[Fractional ideal (3, a + 1), Fractional ideal (3, a - 1)]
sage: SUK = UnitGroup(K,S=tuple(S)); SUK
S-unit group with structure C2 x Z x Z x Z x Z of Number Field in a with defining polynomial x^6 + 2 with S = (Fractional ideal (3, a + 1), Fractional ideal (3, a - 1))
sage: SUK.primes()
(Fractional ideal (3, a + 1), Fractional ideal (3, a - 1))
sage: SUK.rank()
4
sage: SUK.gens_values()
[-1, a^2 + 1, a^5 + a^4 - a^2 - a - 1, a + 1, -a + 1]
sage: u = 9*prod(SUK.gens_values()); u
-18*a^5 - 18*a^4 - 18*a^3 - 9*a^2 + 9*a + 27
sage: SUK.log(u)
(1, 3, 1, 7, 7)
sage: u == SUK.exp((1,3,1,7,7))
True

A relative number field example:

sage: L.<a, b> = NumberField([x^2 + x + 1, x^4 + 1])
sage: UL = L.unit_group(); UL
Unit group with structure C24 x Z x Z x Z of Number Field in a with defining polynomial x^2 + x + 1 over its base field
sage: UL.gens_values() # random
[-b^3*a - b^3, -b^3*a + b, (-b^3 - b^2 - b)*a - b - 1, (-b^3 - 1)*a - b^2 + b - 1]
sage: UL.zeta_order()
24
sage: UL.roots_of_unity()
[-b*a - b,
 b^2*a,
 b^3,
 a + 1,
 -b*a,
 -b^2,
 b^3*a + b^3,
 a,
 b,
 -b^2*a - b^2,
 b^3*a,
 -1,
 b*a + b,
 -b^2*a,
 -b^3,
 -a - 1,
 b*a,
 b^2,
 -b^3*a - b^3,
 -a,
 -b,
 b^2*a + b^2,
 -b^3*a,
 1]

A relative extension example, which worked thanks to the code review by F.W.Clarke:

sage: PQ.<X> = QQ[]
sage: F.<a, b> = NumberField([X^2 - 2, X^2 - 3])
sage: PF.<Y> = F[]
sage: K.<c> = F.extension(Y^2 - (1 + a)*(a + b)*a*b)
sage: K.unit_group()
Unit group with structure C2 x Z x Z x Z x Z x Z x Z x Z of Number Field in c with defining polynomial Y^2 + (-2*b - 3)*a - 2*b - 6 over its base field

AUTHOR:

  • John Cremona
sage.rings.number_field.unit_group.UnitGroup

The unit group or an S-unit group of a number field.