Function: galoissubcyclo
Section: number_fields
C-Name: galoissubcyclo
Prototype: GDGD0,L,Dn
Help: galoissubcyclo(N,H,{flag=0},{v}): computes a polynomial (in variable v)
 defining the subfield of Q(zeta_n) fixed by the subgroup H of (Z/nZ)*. N can
 be an integer n, znstar(n) or bnrinit(bnfinit(y),[n,[1]]). H can be given
 by a generator, a set of generator given by a vector or a HNF matrix (see
 manual). If flag is 1, outputs only the conductor of the abelian extension.
 If flag is 2, outputs [pol,f] where pol is the polynomial and f the conductor.
 If flag is 3, outputs galoisinit(pol).
Doc: computes the subextension $L$ of $\Q(\zeta_{n})$ fixed by the subgroup
 $H \subset (\Z/n\Z)^{*}$. By the Kronecker-Weber theorem, all abelian number
 fields can be generated in this way (uniquely if $n$ is taken to be minimal).
 This function output is somewhat canonical, as it returns the minimal
 polynomial of a Gaussian period $\text{Tr}_{\Q(\zeta_{f})/L}(\zeta_{f})$,
 where $f$ is the smallest integer so that $\zeta_n\in \Q(\zeta_{f})$.

 \noindent The pair $(n, H)$ is deduced from the parameters $(N, H)$ as follows

 \item $N$ an integer: then $n = N$; $H$ is a generator, i.e. an
 integer or an integer modulo $n$; or a vector of generators.

 \item $N$ the output of \kbd{znstar}$(n)$ or \kbd{znstar}$(n,1)$.
 $H$ as in the first case above, or a matrix, taken to be a HNF left divisor
 of the SNF for $(\Z/n\Z)^{*}$
 (\kbd{$N$.cyc}), giving the generators of $H$ in terms of \kbd{$N$.gen}.

 \item $N$ the output of \kbd{bnrinit(bnfinit(y), $m$)} where $m$ is a
 module. $H$ as in the first case, or a matrix taken to be a HNF left
 divisor of the SNF for the ray class group modulo $m$
 (of type \kbd{$N$.cyc}), giving the generators of $H$ in terms of
 \kbd{$N$.bid.gen} (= \kbd{$N$}.gen if $N$ includes generators).

 In this last case, beware that $H$ is understood relatively to $N$; in
 particular, if the infinite place does not divide the module, e.g if $m$ is
 an integer, then it is not a subgroup of $(\Z/n\Z)^{*}$, but of its quotient by
 $\{\pm 1\}$.

 If $\fl=0$, computes a polynomial (in the variable \var{v}) defining
 the subfield of $\Q(\zeta_{n})$ fixed by the subgroup \var{H} of
 $(\Z/n\Z)^{*}$.

 If $\fl=1$, computes only the conductor of the abelian extension, as a module.

 If $\fl=2$, outputs $[pol, N]$, where $pol$ is the polynomial as output when
 $\fl=0$ and $N$ the conductor as output when $\fl=1$.

 If $\fl=3$; outputs \kbd{galoisinit(pol)}.

 The following function can be used to compute all subfields of
 $\Q(\zeta_{n})$ (of exact degree \kbd{d}, if \kbd{d} is set):
 \bprog
 subcyclo(n, d = -1)=
 { my(bnr,L,IndexBound);
   IndexBound = if (d < 0, n, [d]);
   bnr = bnrinit(bnfinit(y), [n,[1]]);
   L = subgrouplist(bnr, IndexBound, 1);
   vector(#L,i, galoissubcyclo(bnr,L[i]));
 }
 @eprog\noindent
 Setting \kbd{L = subgrouplist(bnr, IndexBound)} would produce subfields of
 exact conductor $n\infty$.
