1Function: bnrmap
2Section: number_fields
3C-Name: bnrmap
4Prototype: GG
5Help: bnrmap(A, B): if A and B are bnr structures for the same bnf attached
6 to moduli mA and mB with mB | mA, return the canonical surjection from
7 A to B. Alternatively, if A is a map from bnrmap and B is a congruence
8 subgroup or ray class character modulo mA, return the corresponding object on
9 Cl(mB).
10Doc: This function has two different uses:
11
12 \item if $A$ and $B$ are \var{bnr} structures for the same \var{bnf} attached
13 to moduli $m_A$ and $m_B$ with $m_B \mid m_A$, return the canonical surjection
14 from $A$ to $B$, i.e. from the ray class group moodulo $m_A$ to the ray
15 class group modulo $m_B$. The map is coded by a triple
16 $[M,\var{cyc}_A,\var{cyc}_B]$:
17 $M$ gives the image of the fixed ray class group generators of $A$ in
18 terms of the ones in $B$, $\var{cyc}_A$ and $\var{cyc}_B$ are the cyclic
19 structures \kbd{A.cyc} and \kbd{B.cyc} respectively. Note that this function
20 does \emph{not} need $A$ or $B$ to contain explicit generators for the ray
21 class groups: they may be created using \kbd{bnrinit(,0)}.
22
23 If $B$ is only known modulo $N$-th powers (from \kbd{bnrinit(,N)}), the result
24 is correct provided $N$ is a multiple of the exponent of $A$.
25
26 \item if $A$ is a projection map as above and $B$ is either a congruence
27 subgroup $H$, or a ray class character $\chi$, or a discrete logarithm
28 (from \kbd{bnrisprincipal})  modulo $m_A$ whose conductor
29 divides $m_B$, return the image of the subgroup (resp. the character, the
30 discrete logarighm) as defined modulo $m_B$. The main use of this variant is
31 to compute the primitive subgroup or character attached to a \var{bnr} modulo
32 their conductor. This is more efficient than \tet{bnrconductor} in two
33 respects: the \var{bnr} attached to the conductor need only be computed once
34 and, most importantly, the ray class group can be computed modulo $N$-th
35 powers, where $N$ is a multiple of the exponent of $\text{Cl}_{m_A} / H$ (resp.
36 of the order of $\chi$). Whereas \kbd{bnrconductor} is specified to return a
37 \var{bnr} attached to the full ray class group, which may lead to untractable
38 discrete logarithms in the full ray class group instead of a tiny quotient.
39