% This file was created automatically from fldabnum.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  fldabnum.msk                 GAP documentation              Thomas Breuer
%%
%A  @(#)$Id: fldabnum.msk,v 1.12.2.1 2006/09/16 19:02:49 jjm Exp $
%%
%Y  (C) 1998 School Math and Comp. Sci., University of St.  Andrews, Scotland
%Y  Copyright (C) 2002 The GAP Group
%%
\Chapter{Abelian Number Fields}

An *abelian number field* is a field in characteristic zero
that is a finite dimensional normal extension of its prime field
such that the Galois group is abelian.
In {\GAP}, one implementation of abelian number fields is given by fields
of cyclotomic numbers (see Chapter~"Cyclotomic Numbers").
Note that abelian number fields can also be constructed with
the more general `AlgebraicExtension' (see~"AlgebraicExtension"),
a discussion of advantages and disadvantages can be found
in~"Internally Represented Cyclotomics".
The functions described in this chapter have been developed for fields
whose elements are in the filter `IsCyclotomic' (see~"IsCyclotomic"),
they may or may not work well for abelian number fields consisting of
other kinds of elements.

Throughout this chapter, $\Q_n$ will denote the cyclotomic field
generated by the field $\Q$ of rationals together with $n$-th roots of
unity.

In~"Construction of Abelian Number Fields", constructors for abelian
number fields are described,
"Operations for Abelian Number Fields" introduces operations for abelian
number fields,
"Integral Bases of Abelian Number Fields" deals with the vector space
structure of abelian number fields, and
"Galois Groups of Abelian Number Fields" describes field automorphisms
of abelian number fields,
% section about Gaussians here?




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Construction of Abelian Number Fields}

Besides the usual construction using `Field' or `DefaultField'
(see~"Operations for Abelian Number Fields"),
abelian number fields consisting of cyclotomics can be created with
`CyclotomicField' and `AbelianNumberField'.


\>CyclotomicField( <n> ) F
\>CyclotomicField( <gens> ) F
\>CyclotomicField( <subfield>, <n> ) F
\>CyclotomicField( <subfield>, <gens> ) F

The first version creates the <n>-th cyclotomic field $\Q_n$.
The second version creates the smallest cyclotomic field containing the
elements in the list <gens>.
In both cases the field can be generated as an extension of a designated
subfield <subfield> (cf.~"Integral Bases of Abelian Number Fields").

\indextt{CF}
`CyclotomicField' can be abbreviated to `CF',
this form is used also when {\GAP} prints cyclotomic fields.

Fields constructed with the one argument version of `CF' are stored in
the global list `CYCLOTOMIC_FIELDS',
so repeated calls of `CF' just fetch these field objects after they have
been created once.



\beginexample
gap> CyclotomicField( 5 );  CyclotomicField( [ Sqrt(3) ] );
CF(5)
CF(12)
gap> CF( CF(3), 12 );  CF( CF(4), [ Sqrt(7) ] );
AsField( CF(3), CF(12) )
AsField( GaussianRationals, CF(28) )
\endexample


\>AbelianNumberField( <n>, <stab> ) F

For a positive integer <n> and a list <stab> of prime residues modulo
<n>, `AbelianNumberField' returns the fixed field of the group described
by <stab> (cf.~"GaloisStabilizer"), in the <n>-th cyclotomic field.
`AbelianNumberField' is mainly thought for internal use and for printing
fields in a standard way;
`Field' (see~"Field", cf.~also~"Operations for Abelian Number Fields")
is probably more suitable if one knows generators of the field in
question.

\indextt{NF}
`AbelianNumberField' can be abbreviated to `NF',
this form is used also when {\GAP} prints abelian number fields.

Fields constructed with `NF' are stored in the global list
`ABELIAN_NUMBER_FIELDS',
so repeated calls of `NF' just fetch these field objects after they have
been created once.



\beginexample
gap> NF( 7, [ 1 ] );
CF(7)
gap> f:= NF( 7, [ 1, 2 ] );  Sqrt(-7); Sqrt(-7) in f;
NF(7,[ 1, 2, 4 ])
E(7)+E(7)^2-E(7)^3+E(7)^4-E(7)^5-E(7)^6
true
\endexample


\>`GaussianRationals' V
\>IsGaussianRationals( <obj> ) C

`GaussianRationals' is the field $\Q_4 = \Q(\sqrt{-1})$
of Gaussian rationals, as a set of cyclotomic numbers,
see Chapter~"Cyclotomic Numbers" for basic operations.
This field can also be obtained as `CF(4)' (see~"CyclotomicField").

The filter `IsGaussianRationals' returns `true' for the {\GAP} object
`GaussianRationals', and `false' for all other {\GAP} objects.

(For details about the field of rationals, see Chapter~"Rationals".)



\beginexample
gap> CF(4) = GaussianRationals;
true
gap> Sqrt(-1) in GaussianRationals;
true
\endexample

% factoring of elements in GaussianRationals works?


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Operations for Abelian Number Fields}

For operations for elements of abelian number fields, e.g.,
`Conductor' (see~"Conductor") or `ComplexConjugate' (see~"ComplexConjugate"),
see Chapter~"Cyclotomic Numbers".


\index{cyclotomics!DefaultField}
For a dense list $l$ of cyclotomics, `DefaultField' (see~"DefaultField")
returns the smallest cyclotomic field containing all entries of $l$,
`Field' (see~"Field") returns the smallest field containing all entries of
$l$, which need not be a cyclotomic field.
In both cases, the fields represent vector spaces over the rationals
(see~"Integral Bases of Abelian Number Fields").

\beginexample
gap> DefaultField( [ E(5) ] ); DefaultField( [ E(3), ER(6) ] );
CF(5)
CF(24)
gap> Field( [ E(5) ] ); Field( [ E(3), ER(6) ] );
CF(5)
NF(24,[ 1, 19 ])
\endexample


\index{polynomials over abelian number fields!Factors}
Factoring of polynomials over abelian number fields consisting of cyclotomics
works in principle but is not very efficient if the degree of the field
extension is large.

\beginexample
gap> x:= Indeterminate( CF(5) );
x_1
gap> Factors( PolynomialRing( Rationals ), x^5-1 );
[ x_1-1, x_1^4+x_1^3+x_1^2+x_1+1 ]
gap> Factors( PolynomialRing( CF(5) ), x^5-1 );
[ x_1-1, x_1+(-E(5)), x_1+(-E(5)^2), x_1+(-E(5)^3), x_1+(-E(5)^4) ]
\endexample


\>IsNumberField( <F> ) P

\index{number field}
returns `true' if the field <F> is a finite dimensional extension
of a prime field in characteristic zero, and `false' otherwise.


\>IsAbelianNumberField( <F> ) P

\index{abelian number field}
returns `true' if the field <F> is a number field (see~"IsNumberField")
that is a Galois extension of the prime field, with abelian Galois group
(see~"GaloisGroup!of field").


\>IsCyclotomicField( <F> ) P

returns `true' if the field <F> is a *cyclotomic field*, i.e.,
an abelian number field (see~"IsAbelianNumberField")
that can be generated by roots of unity.



\beginexample
gap> IsNumberField( CF(9) ); IsAbelianNumberField( Field( [ ER(3) ] ) );
true
true
gap> IsNumberField( GF(2) );
false
gap> IsCyclotomicField( CF(9) );
true
gap> IsCyclotomicField( Field( [ Sqrt(-3) ] ) );
true
gap> IsCyclotomicField( Field( [ Sqrt(3) ] ) );
false
\endexample


\>GaloisStabilizer( <F> ) A

Let <F> be an abelian number field (see~"IsAbelianNumberField")
with conductor $n$, say.
(This means that the $n$-th cyclotomic field is the smallest cyclotomic
field containing <F>, see~"Conductor".)
`GaloisStabilizer' returns the set of all those integers $k$ in the range
from $1$ to $n$ such that the field automorphism induced by raising
$n$-th roots of unity to the $k$-th power acts trivially on <F>.



\beginexample
gap> r5:= Sqrt(5);
E(5)-E(5)^2-E(5)^3+E(5)^4
gap> GaloisCyc( r5, 4 ) = r5;  GaloisCyc( r5, 2 ) = r5;
true
false
gap> GaloisStabilizer( Field( [ r5 ] ) );
[ 1, 4 ]
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Integral Bases of Abelian Number Fields}

Each abelian number field is naturally a vector space over $\Q$.
Moreover, if the abelian number field $F$ contains the $n$-th cyclotomic
field $\Q_n$ then $F$ is a vector space over $\Q_n$.
In {\GAP}, each field object represents a vector space object over a
certain subfield $S$, which depends on the way $F$ was constructed.
The subfield $S$ can be accessed as the value of the attribute
`LeftActingDomain' (see~"LeftActingDomain").

The return values of `NF' (see~"AbelianNumberField") and of the one
argument versions of `CF' (see~"CyclotomicField") represent vector spaces
over $\Q$,
and the return values of the two argument version of `CF' represent
vector spaces over the field that is given as the first argument.
For an abelian number field <F> and a subfield <S> of <F>,
a {\GAP} object representing <F> as a vector space over <S> can be
constructed using `AsField' (see~"AsField").

\index{cyclotomic fields!CanonicalBasis}
Let <F> be the cyclotomic field $\Q_n$, represented as a vector space
over the subfield <S>.
If <S> is the cyclotomic field $\Q_m$, with $m$ a divisor of $n$,
then `CanonicalBasis( <F> )' returns the Zumbroich basis of <F> relative
to <S>, which consists of the roots of unity $`E(<n>)'^i$ where <i> is
an element of the list `ZumbroichBase( <n>, <m> )' (see~"ZumbroichBase").
If <S> is an abelian number field that is not a cyclotomic field
then `CanonicalBasis( <F> )' returns a normal <S>-basis of <F>, i.e.,
a basis that is closed under the field automorphisms of <F>.

\index{abelian number fields!CanonicalBasis}
Let <F> be the abelian number field `NF( <n>, <stab> )', with conductor
<n>, that is itself not a cyclotomic field,
represented as a vector space over the subfield <S>.
If <S> is the cyclotomic field $\Q_m$, with $m$ a divisor of $n$,
then `CanonicalBasis( <F> )' returns the Lenstra basis of <F> relative
to <S> that consists of the sums of roots of unity described by
`LenstraBase( <n>, <stab>, <stab>, <m> )' (see~"LenstraBase").
If <S> is an abelian number field that is not a cyclotomic field
then `CanonicalBasis( <F> )' returns a normal <S>-basis of <F>.



\beginexample
gap> f:= CF(8);;   # a cycl. field over the rationals
gap> b:= CanonicalBasis( f );;  BasisVectors( b );
[ 1, E(8), E(4), E(8)^3 ]
gap> Coefficients( b, Sqrt(-2) );
[ 0, 1, 0, 1 ]
gap> f:= AsField( CF(4), CF(8) );;  # a cycl. field over a cycl. field
gap> b:= CanonicalBasis( f );;  BasisVectors( b );                    
[ 1, E(8) ]
gap> Coefficients( b, Sqrt(-2) );
[ 0, 1+E(4) ]
gap> f:= AsField( Field( [ Sqrt(-2) ] ), CF(8) );;
gap> # a cycl. field over a non-cycl. field
gap> b:= CanonicalBasis( f );;  BasisVectors( b );
[ 1/2+1/2*E(8)-1/2*E(8)^2-1/2*E(8)^3, 1/2-1/2*E(8)+1/2*E(8)^2+1/2*E(8)^3 ]
gap> Coefficients( b, Sqrt(-2) );
[ E(8)+E(8)^3, E(8)+E(8)^3 ]
gap> f:= Field( [ Sqrt(-2) ] );   # a non-cycl. field over the rationals
NF(8,[ 1, 3 ])
gap> b:= CanonicalBasis( f );;  BasisVectors( b );
[ 1, E(8)+E(8)^3 ]
gap> Coefficients( b, Sqrt(-2) );
[ 0, 1 ]
\endexample


\>ZumbroichBase( <n>, <m> ) F

Let <n> and <m> be positive integers, such that <m> divides <n>.
`ZumbroichBase' returns the set of exponents <i> for which `E(<n>)^<i>'
belongs to the (generalized) Zumbroich basis of the cyclotomic field
$\Q_n$, viewed as a vector space over $\Q_m$.

This basis is defined as follows.
Let $P$ denote the set of prime divisors of <n>,
$<n> = \prod_{p\in P} p^{\nu_p}$, and
$<m> = \prod_{p\in P} p^{\mu_p}$ with $\mu_p \leq \nu_p$.
Let $e_n = `E(<n>)'$,
and $\{ e_{n_1}^j\}_{j\in J} \otimes \{ e_{n_2}^k\}_{k\in K} =
\{ e_{n_1}^j \cdot e_{n_2}^k\}_{j\in J, k\in K}$.

Then the basis is
$$
B_{n,m} = \bigotimes_{p\in P}
  \bigotimes_{k=\mu_p}^{\nu_p-1} \{ e_{p^{k+1}}^j\}_{j\in J_{k,p}}
  {\rm\ \ where\ \ }
J_{k,p} = \left\{
   \matrix{ \{ 0 \} & ; & k=0, p=2 \cr
            \{ 0, 1 \} & ; & k > 0, p=2 \cr
            \{ 1, \ldots, p-1 \} & ; & k = 0, p\not= 2 \cr
            \{ -\frac{p-1}{2}, \ldots, \frac{p-1}{2} \} & ; &
                             k > 0, p\not= 2 \cr
}
\right.
$$

$B_{n,1}$ is equal to the basis of $\Q_n$ over the rationals which is
introduced in~\cite{Zum89}.
Also the conversion of arbitrary sums of roots of unity into its
basis representation, and the reduction to the minimal cyclotomic field
are described in this thesis.
(Note that the notation here is slightly different from that there.)

$B_{n,m}$ consists of roots of unity, it is an integral basis
(that is, exactly the integral elements in $\Q_n$ have integral
coefficients w.r.t.~$B_{n,m}$, cf.~"IsIntegralCyclotomic"),
it is a normal basis for squarefree $n$
and closed under complex conjugation for odd $n$.

*Note:*
For $<n> \equiv 2 \pmod 4$, we have
`ZumbroichBase(<n>, 1) = 2 * ZumbroichBase(<n>/2, 1)' and
`List( ZumbroichBase(<n>, 1), x -> E(<n>)^x ) =
 List( ZumbroichBase(<n>/2, 1), x -> E(<n>/2)^x )'.



\beginexample
gap> ZumbroichBase( 15, 1 ); ZumbroichBase( 12, 3 );
[ 1, 2, 4, 7, 8, 11, 13, 14 ]
[ 0, 3 ]
gap> ZumbroichBase( 10, 2 ); ZumbroichBase( 32, 4 );
[ 2, 4, 6, 8 ]
[ 0, 1, 2, 3, 4, 5, 6, 7 ]
\endexample


\>LenstraBase( <n>, <stabilizer>, <super>, <m> ) F

Let <n> and <m> be positive integers, such that <m> divides <n>,
<stabilizer> be a list of prime residues modulo <n>, which describes
a subfield of the <n>-th cyclotomic field (see~"GaloisStabilizer"),
and <super> be a list representing a supergroup of the group given by
<stabilizer>.

`LenstraBase' returns a list $[ b_1, b_2, \ldots, b_k ]$ of lists,
each $b_i$ consisting of integers such that the elements
$\sum_{j\in b_i} `E(n)'^j$ form a basis of the abelian number field
`NF( <n>, <stabilizer> )', as a vector space over the <m>-th
cyclotomic field (see~"AbelianNumberField").

This basis is an integral basis,
that is, exactly the integral elements in `NF( <n>, <stabilizer> )'
have integral coefficients.
(For details about this basis, see~\cite{Bre97}.)

If possible then the result is chosen such that the group described by
<super> acts on it, consistently with the action of <stabilizer>,
i.e., each orbit of <super> is a union of orbits of <stabilizer>.
(A usual case is `<super> = <stabilizer>', so there is no additional
condition.

*Note:*
The $b_i$ are in general not sets, since for `<stabilizer> = <super>',
the first entry is always an element of `ZumbroichBase( <n>, <m> )';
this property is used by `NF' (see~"AbelianNumberField")
and `Coefficients' (see~"Integral Bases of Abelian Number Fields").

<stabilizer> must not contain the stabilizer of a proper
cyclotomic subfield of the <n>-th cyclotomic field,
i.e., the result must describe a basis for a field with conductor <n>.



\beginexample
gap> LenstraBase( 24, [ 1, 19 ], [ 1, 19 ], 1 );
[ [ 1, 19 ], [ 8 ], [ 11, 17 ], [ 16 ] ]
gap> LenstraBase( 24, [ 1, 19 ], [ 1, 5, 19, 23 ], 1 );
[ [ 1, 19 ], [ 5, 23 ], [ 8 ], [ 16 ] ]
gap> LenstraBase( 15, [ 1, 4 ], PrimeResidues( 15 ), 1 );
[ [ 1, 4 ], [ 2, 8 ], [ 7, 13 ], [ 11, 14 ] ]
\endexample

The first two results describe two bases of the field $\Q_3(\sqrt{6})$,
the third result describes a normal basis of $\Q_3(\sqrt{5})$.

%T missing: `IsIntegralBasis', `NormalBasis', `IsNormalBasis',
%T rings of integers in abelian number fields


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Galois Groups of Abelian Number Fields}

\atindex{abelian number fields!Galois group}%
{@abelian number fields!Galois group}
\atindex{number fields!Galois group}{@number fields!Galois group}
\index{automorphism group!of number fields}

The field automorphisms of the cyclotomic field $\Q_n$
(see Chapter~"Cyclotomic Numbers") are given by the linear maps $\ast k$
on $\Q_n$ that are defined by $`E'(n)^{\ast k} = `E'(n)^k$,
where $1 \leq k \< n$ and $`Gcd'( n, k ) = 1$ hold (see~"GaloisCyc").
Note that this action is *not* equal to exponentiation of cyclotomics,
i.e., for general cyclotomics $z$, $z^{\ast k}$ is different from $z^k$.

(In {\GAP}, the image of a cyclotomic $z$ under $\ast k$ can be computed
as $`GaloisCyc'( z, k )$.)

\beginexample
gap> ( E(5) + E(5)^4 )^2; GaloisCyc( E(5) + E(5)^4, 2 );
-2*E(5)-E(5)^2-E(5)^3-2*E(5)^4
E(5)^2+E(5)^3
\endexample

For $`Gcd'( n, k ) \not= 1$, the map $`E'(n) \mapsto `E'(n)^k$ does *not*
define a field automorphism of $\Q_n$ but only a $\Q$-linear map.

\beginexample
gap> GaloisCyc( E(5)+E(5)^4, 5 ); GaloisCyc( ( E(5)+E(5)^4 )^2, 5 );
2
-6
\endexample

\>ANFAutomorphism( <F>, <k> ) F

Let <F> be an abelian number field and <k> an integer that is coprime to
the conductor (see~"Conductor") of <F>.
Then `ANFAutomorphism' returns the automorphism of <F> that is defined as
the linear extension of the map that raises each root of unity in <F>
to its <k>-th power.


\beginexample
gap> f:= CF(25);
CF(25)
gap> alpha:= ANFAutomorphism( f, 2 );
ANFAutomorphism( CF(25), 2 )
gap> alpha^2;
ANFAutomorphism( CF(25), 4 )
gap> Order( alpha );
20
gap> E(5)^alpha;
E(5)^2
\endexample

The Galois group $Gal( \Q_n, \Q )$ of the field extension
$\Q_n / \Q$ is isomorphic to the group $(\Z / n \Z)^{\ast}$
of prime residues modulo $n$, via the isomorphism
$(\Z / n \Z)^{\ast} \rightarrow Gal( \Q_n, \Q )$ that is defined by
$k + n \Z \mapsto ( z \mapsto z^{\ast k} )$.

The Galois group of the field extension $\Q_n / L$ with
any abelian number field $L \subseteq \Q_n$ is simply the
factor group of $Gal( \Q_n, \Q )$ modulo the stabilizer of $L$,
and the Galois group of $L / L^{\prime}$, with $L^{\prime}$ an abelian
number field contained in $L$, is the subgroup in this group that stabilizes
$L^{\prime}$.
These groups are easily described in terms of $(\Z / n \Z)^{\ast}$.
Generators of $(\Z / n \Z)^{\ast}$ can be computed using
`GeneratorsPrimeResidues' (see~"GeneratorsPrimeResidues").

In {\GAP}, a field extension $L / L^{\prime}$ is given by the field
object $L$ with `LeftActingDomain' value $L^{\prime}$
(see~"Integral Bases of Abelian Number Fields").

\beginexample
gap> f:= CF(15);
CF(15)
gap> g:= GaloisGroup( f );
<group with 2 generators>
gap> Size( g ); IsCyclic( g ); IsAbelian( g );
8
false
true
gap> Action( g, NormalBase( f ), OnPoints );
Group([ (1,6)(2,4)(3,8)(5,7), (1,4,3,7)(2,8,5,6) ])
\endexample

The following example shows Galois groups of a cyclotomic field
and of a proper subfield that is not a cyclotomic field.

\beginexample
gap> gens1:= GeneratorsOfGroup( GaloisGroup( CF(5) ) );
[ ANFAutomorphism( CF(5), 2 ) ]
gap> gens2:= GeneratorsOfGroup( GaloisGroup( Field( Sqrt(5) ) ) );
[ ANFAutomorphism( NF(5,[ 1, 4 ]), 2 ) ]
gap> Order( gens1[1] );  Order( gens2[1] );
4
2
gap> Sqrt(5)^gens1[1] = Sqrt(5)^gens2[1];
true
\endexample

The following example shows the Galois group of a cyclotomic field
over a non-cyclotomic field.

\beginexample
gap> g:= GaloisGroup( AsField( Field( [ Sqrt(5) ] ), CF(5) ) );
<group with 1 generators>
gap> gens:= GeneratorsOfGroup( g );
[ ANFAutomorphism( AsField( NF(5,[ 1, 4 ]), CF(5) ), 4 ) ]
gap> x:= last[1];;  x^2;
IdentityMapping( AsField( NF(5,[ 1, 4 ]), CF(5) ) )
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Gaussians}

\>`GaussianIntegers' V

`GaussianIntegers' is the ring $\Z[\sqrt{-1}]$ of Gaussian integers.
This is a subring of the cyclotomic field `GaussianRationals',
see~"GaussianRationals".


\>IsGaussianIntegers( <obj> ) C

is the defining category for the domain `GaussianIntegers'.



% Gcd and Euclidean... for the rings of integers in CF(4) and CF(3) !


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E