1Function: bnrinit
2Section: number_fields
3C-Name: bnrinitmod
4Prototype: GGD0,L,DG
5Help: bnrinit(bnf,f,{flag=0},{cycmod}): given a bnf as output by
6 bnfinit and a modulus f, initializes data
7 linked to the ray class group structure corresponding to this module. flag
8 is optional, and can be 0: default, 1: compute also the generators. If
9 the positive integer cycmod is present, only compute the ray class group
10 modulo cycmod-th powers.
11Description:
12 (gen,gen,?small):bnr       bnrinit0($1, $2, $3)
13Doc: $\var{bnf}$ is as
14 output by \kbd{bnfinit} (including fundamental units), $f$ is a modulus,
15 initializes data linked to the ray class group structure corresponding to
16 this module, a so-called \kbd{bnr} structure. One can input the attached
17 \var{bid} with generators for $f$ instead of the module itself, saving some
18 time. (As in \tet{idealstar}, the finite part of the conductor may be given
19 by a factorization into prime ideals, as produced by \tet{idealfactor}.)
20
21 If the positive integer \kbd{cycmod} is present, only compute the ray class
22 group modulo \kbd{cycmod}, which may save a lot of time when some maximal
23 ideals in $f$ have a huge residue field. In applications, we are given
24 a congruence subgroup $H$ and study the class field attached to
25 $\text{Cl}_f/H$. If that finite Abelian group has an exponent which divides
26 \kbd{cycmod}, then we have changed nothing theoretically, while trivializing
27 expensive discrete logs in residue fields (since computations can be
28 made modulo \kbd{cycmod}-th powers). This is useful in \kbd{bnrclassfield},
29 for instance when computing $p$-elementary extensions.
30
31 The following member functions are available
32 on the result: \kbd{.bnf} is the underlying \var{bnf},
33 \kbd{.mod} the modulus, \kbd{.bid} the \kbd{bid} structure attached to the
34 modulus; finally, \kbd{.clgp}, \kbd{.no}, \kbd{.cyc}, \kbd{.gen} refer to the
35 ray class group (as a finite abelian group), its cardinality, its elementary
36 divisors, its generators (only computed if $\fl = 1$).
37
38 The last group of functions are different from the members of the underlying
39 \var{bnf}, which refer to the class group; use \kbd{\var{bnr}.bnf.\var{xxx}}
40 to access these, e.g.~\kbd{\var{bnr}.bnf.cyc} to get the cyclic decomposition
41 of the class group.
42
43 They are also different from the members of the underlying \var{bid}, which
44 refer to $(\Z_K/f)^*$; use \kbd{\var{bnr}.bid.\var{xxx}} to access these,
45 e.g.~\kbd{\var{bnr}.bid.no} to get $\phi(f)$.
46
47 If $\fl=0$ (default), the generators of the ray class group are not
48 explicitly computed, which saves time. Hence \kbd{\var{bnr}.gen} would
49 produce an error. Note that implicit generators are still fixed and stored
50 in the \var{bnr} (and guaranteed to be the same for fixed \var{bnf} and
51 \var{bid} inputs), in terms of \kbd{bnr.bnf.gen} and \kbd{bnr.bid.gen}.
52 The computation which is not performed is the expansion of such products
53 in the ray class group so as to fix eplicit ideal representatives.
54
55 If $\fl=1$, as the default, except that generators are computed.
56Variant: Instead of the above hardcoded  numerical flags,  one should rather use
57 \fun{GEN}{Buchraymod}{GEN bnf, GEN module, long flag, GEN cycmod}
58 where an omitted \kbd{cycmod} is coded as \kbd{NULL} and flag is an or-ed
59 combination of \kbd{nf\_GEN} (include generators) and \kbd{nf\_INIT} (if
60 omitted, return just the cardinality of the ray class group and its structure),
61 possibly 0. Or simply
62   \fun{GEN}{Buchray}{GEN bnf, GEN module, long flag}
63 when \kbd{cycmod} is \kbd{NULL}.
64