1Function: bnfunits
2Section: number_fields
3C-Name: bnfunits
4Prototype: GDG
5Help: bnfunits(bnf,{S}): return the fundamental units of the number field
6 bnf output by bnfinit; if S is present and is a list of prime ideals, compute
7 fundamental S-units instead. The first component of the result contains the
8 S-units, followed by fundamental units, followed by the torsion unit.
9 The result may be used as an optional argument to bnfisunit.
10Doc: return the fundamental units of the number field
11 bnf output by bnfinit; if $S$ is present and is a list of prime ideals,
12 compute fundamental $S$-units instead. The first component of the result
13 contains independent integral $S$-units generators: first nonunits, then
14 $r_1+r_2-1$ fundamental units, then the torsion unit. The result may be used
15 as an optional argument to bnfisunit. The units are given in compact form:
16 no expensive computation is attempted if the \var{bnf} does not already
17 contain units.
18
19 \bprog
20  ? bnf = bnfinit(x^4 - x^3 + 4*x^2 + 3*x + 9, 1);
21  ? bnf.sign   \\ r1 + r2 - 1 = 1
22  %2 = [0, 2]
23  ? U = bnfunits(bnf); u = U[1];
24  ? #u \\ r1 + r2 = 2 units
25  %5 = 2;
26  ? u[1] \\ fundamental unit as factorization matrix
27  %6 =
28  [[0, 0, -1, -1]~  1]
29
30  [[2, -1, -1, 0]~ -2]
31
32  [  [1, 1, 0, 0]~  2]
33
34  [ [-1, 1, 1, 1]~ -1]
35  ? u[2] \\ torsion unit as factorization matrix
36  %7 =
37  [[1, -1, 0, 0]~ 1]
38  ? [nffactorback(bnf, z) | z <- u]  \\ same units in expanded form
39  %8 = [[-1, 1, -1, 0]~, [1, -1, 0, 0]~]
40  @eprog
41
42  Now an example involving $S$-units for a nontrivial $S$:
43  \bprog
44  ? S = idealprimedec(bnf,5); #S
45  %9 = 2
46  ? US = bnfunits(bnf, S); uS = US[1];
47  ? g = [nffactorback(bnf, z) | z <- uS] \\ now 4 units
48  %11 = [[6, -3, -2, -2]~, [-5, 5, 0, 0]~, [-1, 1, -1, 0]~, [1, -1, 0, 0]~]
49  ? bnfisunit(bnf,[10,-40,24,11]~)
50  %12 = []~  \\ not a unit
51  ? e = bnfisunit(bnf, [10,-40,24,11]~, US)
52  %13 = [2, 0, 1, 4]~  \\ ...but an S-unit
53  ? nffactorback(bnf, g, e)
54  %14 = [10, -40, 24, 11]~
55  ? nffactorback(bnf, uS, e) \\ in factored form
56  %15 =
57  [[6, -3, -2, -2]~  2]
58
59  [ [0, 0, -1, -1]~  1]
60
61  [ [2, -1, -1, 0]~ -2]
62
63  [   [1, 1, 0, 0]~  2]
64
65  [  [-1, 1, 1, 1]~ -1]
66
67  [  [1, -1, 0, 0]~  4]
68  @eprog\noindent Note that in more complicated cases, any \kbd{nffactorback}
69  fully expanding an element in factored form could be \emph{very} expensive.
70  On the other hand, the final example expands a factorization whose components
71  are themselves in factored form, hence the result is a factored form:
72  this is a cheap operation.
73