Function: nfbasis
Section: number_fields
C-Name: nfbasis
Prototype: GD&
Help: nfbasis(T,{&dK}): integral basis of the field Q[a], where a is
 a root of the polynomial T, using the round 4 algorithm. An argument
 [T,listP] is possible, where listP is a list of primes or a prime bound,
 to get an order which is maximal at certain primes only. If present, dK is
 set to the discriminant of the returned order.
Doc:
 Let $T(X)$ be an irreducible polynomial with integral coefficients. This
 function returns an \idx{integral basis} of the number field defined by $T$,
 that is a $\Z$-basis of its maximal order. If present, \kbd{dK} is set
 to the discriminant of the returned order. The basis elements are given as
 elements in $K = \Q[X]/(T)$, in Hermite normal form with respect to the
 $\Q$-basis $(1,X,\dots,X^{\deg T-1})$ of $K$, lifted to $\Q[X]$.
 In particular its first element is always $1$ and its $i$-th element is a
 polynomial of degree $i-1$ whose leading coefficient is the inverse of an
 integer: the product of those integers is the index of $\Z[X]/(T)$ in the
 maximal order $\Z_{K}$:
 \bprog
 ? nfbasis(x^2 + 4) \\ Z[X]/(T) has index 2 in Z_K
 %1 = [1, x/2]
 ? nfbasis(x^2 + 4, &D)
 %2 = [1, x/2]
 ? D
 %3 = -4
 @eprog
 This function uses a modified version of the \idx{round 4} algorithm,
 due to David \idx{Ford}, Sebastian \idx{Pauli} and Xavier \idx{Roblot}.

 \misctitle{Local basis, orders maximal at certain primes}

 Obtaining the maximal order is hard: it requires factoring the discriminant
 $D$ of $T$. Obtaining an order which is maximal at a finite explicit set of
 primes is easy, but it may then be a strict suborder of the maximal order. To
 specify that we are interested in a given set of places only, we can replace
 the argument $T$ by an argument $[T,\var{listP}]$, where \var{listP} encodes
 the primes we are interested in: it must be a factorization matrix, a vector
 of integers or a single integer.

 \item Vector: we assume that it contains distinct \emph{prime} numbers.

 \item Matrix: we assume that it is a two-column matrix of a
 (partial) factorization of $D$; namely the first column contains
 distinct \emph{primes} and the second one the valuation of $D$ at each of
 these primes.

 \item Integer $B$: this is replaced by the vector of primes up to $B$. Note
 that the function will use at least $O(B)$ time: a small value, about
 $10^{5}$, should be enough for most applications. Values larger than $2^{32}$
 are not supported.

 In all these cases, the primes may or may not divide the discriminant $D$
 of $T$. The function then returns a $\Z$-basis of an order whose index is
 not divisible by any of these prime numbers. The result may actually be
 a global integral basis, in particular if all the prime divisors of the
 \emph{field} discriminant are included, but this is not guaranteed!
 Note that \kbd{nfinit} has built-in support for such a check:
 \bprog
 ? K = nfinit([T, listP]);
 ? nfcertify(K)   \\ we computed an actual maximal order
 %2 = [];
 @eprog\noindent The first line initializes a number field structure
 incorporating \kbd{nfbasis([T, listP]} in place of a proven integral basis.
 The second line certifies that the resulting structure is correct. This
 allows to create an \kbd{nf} structure attached to the number field $K =
 \Q[X]/(T)$, when the discriminant of $T$ cannot be factored completely,
 whereas the prime divisors of $\disc K$ are known. If present, the argument
 \kbd{dK} is set to the discriminant of the returned order, and is
 equal to the field discriminant if and only if the order is maximal.

 Of course, if \var{listP} contains a single prime number $p$,
 the function returns a local integral basis for $\Z_{p}[X]/(T)$:
 \bprog
 ? nfbasis(x^2+x-1001)
 %1 = [1, 1/3*x - 1/3]
 ? nfbasis( [x^2+x-1001, [2]] )
 %2 = [1, x]
 @eprog\noindent The following function computes the index $i_{T}$
 of $\Z[X]/(T)$ in the order generated by the $\Z$-basis $B$:
 \bprog
 nfbasisindex(T, B) = vecprod([denominator(pollead(Q)) | Q <- B]);
 @eprog\noindent In particular, $B$ is a basis of the maximal order
 if and only if $\kbd{poldisc}(T) / i_{T}^{2}$ is equal to the field
 discriminant. More generally, this formula gives the square of index of the
 order given by $B$ in $\Z_{K}$. For instance, assume that $P$ is a vector
 of prime numbers containing (at least) all prime divisors of the field
 discriminant, then the following construct allows to provably compute the
 field discriminant and to check whether the returned basis is actually
 a basis of the maximal order
 \bprog
 ? B = nfbasis([T, P], &D);
 ? dK = sign(D) * vecprod([p^valuation(D,p) | p<-P]);
 ? dK * nfbasisindex(T, B)^2 == poldisc(T)
 @eprog\noindent The variable \kbd{dK} contains the field discriminant and
 the last command returns $1$ if and only if $B$ is a $\Z$-basis of the
 maximal order. Of course, the \kbd{nfinit} / \kbd{nfcertify} approach is
 simpler, but it is also more costly.

 \misctitle{The Buchmann-Lenstra algorithm}

 We now complicate the picture: it is in fact allowed to include
 \emph{composite} numbers instead of primes
 in \kbd{listP} (Vector or Matrix case), provided they are pairwise coprime.
 The result may still be a correct integral basis if
 the field discriminant factors completely over the actual primes in the
 list; again, this is not guaranteed. Adding a composite $C$ such that $C^{2}$
 \emph{divides} $D$ may help because when we consider $C$ as a prime and run
 the algorithm, two good things can happen: either we succeed in proving that
 no prime dividing $C$ can divide the index (without actually needing to find
 those primes), or the computation exhibits a nontrivial zero divisor,
 thereby factoring $C$ and we go on with the refined factorization. (Note that
 including a $C$ such that $C^{2}$ does not divide $D$ is useless.) If neither
 happen, then the computed basis need not generate the maximal order. Here is
 an example:
 \bprog
 ? B = 10^5;
 ? listP = factor(poldisc(T), B); \\ primes <= B dividing D + cofactor
 ? basis = nfbasis([T, listP], &D)
 @eprog\noindent If the computed discriminant $D$ factors completely
 over the primes less than $B$ (together with the primes contained in the
 \tet{addprimes} table), then everything is certified: $D$ is the field
 discriminant and \kbd{basis} generates the maximal order.
 This can be tested as follows:
 \bprog
   F = factor(D, B); P = F[,1]; E = F[,2];
   for (i = 1, #P,
     if (P[i] > B && !isprime(P[i]), warning("nf may be incorrect")));
 @eprog\noindent
 This is a sufficient but not a necessary condition, hence the warning,
 instead of an error.

 The function \tet{nfcertify} speeds up and automates the above process:
 \bprog
 ? B = 10^5;
 ? nf = nfinit([T, B]);
 ? nfcertify(nf)
 %3 = []      \\ nf is unconditionally correct
 ? [basis, disc] = [nf.zk, nf.disc];
 @eprog
