Function: rnfinit
Section: number_fields
C-Name: rnfinit0
Prototype: GGD0,L,
Help: rnfinit(nf,T,{flag=0}): T being an irreducible polynomial
 defined over the number field nf, initializes a vector of data necessary for
 working in relative number fields (rnf functions). See manual for technical
 details.
Doc: given an \var{nf} structure attached to a number field $K$, as output by
 \kbd{nfinit}, and a monic irreducible polynomial $T$ in $K[x]$ defining a
 relative extension $L = K[x]/(T)$, this computes data to work in $L/K$
 The main variable of $T$ must be of higher priority
 (see \secref{se:priority}) than that of $\var{nf}$, and the coefficients of
 $T$ must be in $K$.

 The result is a row vector, whose components are technical.
 We let $m = [K:\Q]$ the degree of the base field, $n = [L:K]$ the relative
 degree, $r_1$ and $r_2$ the number of real and complex places of $K$. Access
 to this information via \emph{member functions} is preferred since the
 specific data organization specified below will change in the future.

 If $\fl = 1$, add an \var{nf} structure attached to $L$ to \var{rnf}.
 This is likely to be very expensive if the absolute degree $mn$ is large,
 but fixes an integer basis for $\Z_L$ as a $\Z$-module and allows to input
 and output elements of $L$ in absolute form: as \typ{COL} for elements,
 as \typ{MAT} in HNF for ideals, as \kbd{prid} for prime ideals. Without such
 a call, elements of $L$ are represented as \typ{POLMOD}, etc.
 Note that a subsequent \kbd{nfinit}$(\var{rnf})$ will also explicitly
 add such a component, and so will the following functions \kbd{rnfidealmul},
 \kbd{rnfidealtwoelt}, \kbd{rnfidealprimedec}, \kbd{rnfidealup} (with flag 1)
 and \kbd{rnfidealreltoabs} (with flag 1). The absolute \var{nf} structure
 attached to $L$ can be recovered using \kbd{nfinit(rnf)}.

 $\var{rnf}[1]$(\kbd{rnf.pol}) contains the relative polynomial $T$.

 $\var{rnf}[2]$ contains the integer basis $[A,d]$ of $K$, as
 (integral) elements of $L/\Q$. More precisely, $A$ is a vector of
 polynomial with integer coefficients, $d$ is a denominator, and the integer
 basis is given by $A/d$.

 $\var{rnf}[3]$ (\kbd{rnf.disc}) is a two-component row vector
 $[\goth{d}(L/K),s]$ where $\goth{d}(L/K)$ is the relative ideal discriminant
 of $L/K$ and $s$ is the discriminant of $L/K$ viewed as an element of
 $K^*/(K^*)^2$, in other words it is the output of \kbd{rnfdisc}.

 $\var{rnf}[4]$(\kbd{rnf.index}) is the ideal index $\goth{f}$, i.e.~such
 that $d(T)\Z_K=\goth{f}^2\goth{d}(L/K)$.

 $\var{rnf}[5]$ is currently unused.

 $\var{rnf}[6]$ is currently unused.

 $\var{rnf}[7]$ (\kbd{rnf.zk}) is the pseudo-basis $(A,I)$ for the maximal
 order $\Z_L$ as a $\Z_K$-module: $A$ is the relative integral pseudo basis
 expressed as polynomials (in the variable of $T$) with polmod coefficients
 in $\var{nf}$, and the second component $I$ is the ideal list of the
 pseudobasis in HNF.

 $\var{rnf}[8]$ is the inverse matrix of the integral basis matrix, with
 coefficients polmods in $\var{nf}$.

 $\var{rnf}[9]$ is currently unused.

 $\var{rnf}[10]$ (\kbd{rnf.nf}) is $\var{nf}$.

 $\var{rnf}[11]$ is an extension of \kbd{rnfequation(K, T, 1)}. Namely, a
 vector $[P, a, k, \kbd{K.pol}, T]$ describing the \emph{absolute}
 extension $L/\Q$: $P$ is an absolute equation, more conveniently obtained
 as \kbd{rnf.polabs}; $a$ expresses the generator $\alpha = y \mod \kbd{K.pol}$
 of the number field $K$ as an element of $L$, i.e.~a polynomial modulo the
 absolute equation $P$;

 $k$ is a small integer such that, if $\beta$ is an abstract root of $T$
 and $\alpha$ the generator of $K$ given above, then $P(\beta + k\alpha) = 0$.
 It is guaranteed that $k = 0$ if $\Q(\beta) = L$.

 \misctitle{Caveat} Be careful if $k\neq0$ when dealing simultaneously with
 absolute and relative quantities since $L = \Q(\beta + k\alpha) =
 K(\alpha)$, and the generator chosen for the absolute extension is not the
 same as for the relative one. If this happens, one can of course go on
 working, but we advise to change the relative polynomial so that its root
 becomes $\beta + k \alpha$. Typical GP instructions would be
 \bprog
   [P,a,k] = rnfequation(K, T, 1);
   if (k, T = subst(T, x, x - k*Mod(y, K.pol)));
   L = rnfinit(K, T);
 @eprog

 $\var{rnf}[12]$ is by default unused and set equal to 0. This field is used
 to store further information about the field as it becomes available (which
 is rarely needed, hence would be too expensive to compute during the initial
 \kbd{rnfinit} call).

 \misctitle{Huge discriminants, helping rnfdisc} When $T$ has a
 discriminant which is difficult to factor, it is hard to compute
 $\Z_L$. As in \kbd{nfinit}, the special input format $[T,B]$
 is also accepted, where $T$ is a polynomial as above and $B$ is
 an integer. Instead of $\Z_L$, this produces an order which is maximal
 at all primes less than $B$. The result is actually a complete and correct
 \var{rnf} structure if all prime divisors of the relative ideal
 discriminant divide a rational prime less than $B$. In general, the order
 may not be maximal at primes $\goth{p} | p $ for $p \geq B$ such that
 $\goth{p}^2$ divides the relative ideal discriminant.

Variant: Also available is
 \fun{GEN}{rnfinit}{GEN nf,GEN T} ($\fl = 0$).
