1Function: bnfisunit
2Section: number_fields
3C-Name: bnfisunit0
4Prototype: GGDG
5Help: bnfisunit(bnf,x, {U}): bnf being output by bnfinit, give
6 the column vector of exponents of x on the fundamental units and the roots
7 of unity if x is a unit, the empty vector otherwise. If U is present,
8 as given by bnfunits, decompose x on the attached S-units generators.
9Doc: \var{bnf} being the number field data
10 output by \kbd{bnfinit} and $x$ being an algebraic number (type integer,
11 rational or polmod), this outputs the decomposition of $x$ on the fundamental
12 units and the roots of unity if $x$ is a unit, the empty vector otherwise.
13 More precisely, if $u_1$,\dots,$u_r$ are the fundamental units, and $\zeta$
14 is the generator of the group of roots of unity (\kbd{bnf.tu}), the output is
15 a vector $[x_1,\dots,x_r,x_{r+1}]$ such that $x=u_1^{x_1}\cdots
16 u_r^{x_r}\cdot\zeta^{x_{r+1}}$. The $x_i$ are integers but the last one
17 ($i = r+1$) is only defined modulo the order $w$ of $\zeta$ and is guaranteed
18 to be in $[0,w[$.
19
20 Note that \var{bnf} need not contain the fundamental units explicitly: it may
21 contain the placeholder $0$ instead:
22 \bprog
23 ? setrand(1); bnf = bnfinit(x^2-x-100000);
24 ? bnf.fu
25 %2 = 0
26 ? u = [119836165644250789990462835950022871665178127611316131167, \
27        379554884019013781006303254896369154068336082609238336]~;
28 ? bnfisunit(bnf, u)
29 %3 = [-1, 0]~
30 @eprog\noindent The given $u$ is $1/u_1$, where $u_1$ is the fundamental
31 unit implicitly stored in \var{bnf}. In this case, $u_1$ was not computed
32 and stored in algebraic form since the default accuracy was too low. Re-run
33 the \kbd{bnfinit} command at \kbd{\bs g1} or higher to see such diagnostics.
34
35 This function allows $x$ to be given in factored form, but it then assumes
36 that $x$ is an actual unit. (Because it is general too costly to check
37 whether this is the case.)
38 \bprog
39 ? { v = [2, 85; 5, -71; 13, -162; 17, -76; 23, -37; 29, -104; [224, 1]~, -66;
40 [-86, 1]~, 86; [-241, 1]~, -20; [44, 1]~, 30; [124, 1]~, 11; [125, -1]~, -11;
41 [-214, 1]~, 33; [-213, -1]~, -33; [189, 1]~, 74; [190, -1]~, 104;
42 [-168, 1]~, 2; [-167, -1]~, -8]; }
43 ? bnfisunit(bnf,v)
44 %5 = [1, 0]~
45 @eprog\noindent Note that $v$ is the fundamental unit of \kbd{bnf} given in
46 compact (factored) form.
47
48 If the argument \kbd{U} is present, as output by \kbd{bnfunits(bnf, S)},
49 then the function decomposes $x$ on the $S$-units generators given in
50 \kbd{U[1]}.
51 \bprog
52  ? bnf = bnfinit(x^4 - x^3 + 4*x^2 + 3*x + 9, 1);
53  ? bnf.sign
54  %2 = [0, 2]
55  ? S = idealprimedec(bnf,5); #S
56  %3 = 2
57  ? US = bnfunits(bnf,S);
58  ? g = US[1]; #g  \\ #S = #g, four S-units generators, in factored form
59  %5 = 4
60  ? g[1]
61  %6 = [[6, -3, -2, -2]~ 1]
62  ? g[2]
63  %7 =
64  [[-1, 1/2, -1/2, -1/2]~ 1]
65
66  [      [4, -2, -1, -1]~ 1]
67  ? [nffactorback(bnf, x) | x <- g]
68  %8 = [[6, -3, -2, -2]~, [-5, 5, 0, 0]~, [-1, 1, -1, 0]~,
69        [1, -1, 0, 0]~]
70
71  ? u = [10,-40,24,11]~;
72  ? a = bnfisunit(bnf, u, US)
73  %9 = [2, 0, 1, 4]~
74  ? nffactorback(bnf, g, a) \\ prod_i g[i]^a[i] still in factored form
75  %10 =
76  [[6, -3, -2, -2]~  2]
77
78  [ [0, 0, -1, -1]~  1]
79
80  [ [2, -1, -1, 0]~ -2]
81
82  [   [1, 1, 0, 0]~  2]
83
84  [  [-1, 1, 1, 1]~ -1]
85
86  [  [1, -1, 0, 0]~  4]
87
88  ? nffactorback(bnf,%)  \\ u = prod_i g[i]^a[i]
89  %11 = [10, -40, 24, 11]~
90 @eprog
91Variant: Also available is \fun{GEN}{bnfisunit}{GEN bnf, GEN x} for $U =
92 \kbd{NULL}$.
93