
\Chapter{Methods for number fields}

An algebraic number field is a finite-dimensional extension of the
rational numbers $\Q$. Such a number field has a primitive element 
and it can be defined by the minimal polynomial of  this primitive
element. Another important way to define an algebraic number field
is by a set of rational matrices which generate a number field.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Creation of number fields}

We provide functions to create number fields defined by rational 
matrices or by rational polynomials.

\> FieldByMatricesNC( <matrices> )
\> FieldByMatrices( <matrices> )

Creates a field generated by the rational matrices <matrices>. In 
the faster NC version, the function assumes that the input generates 
a field and there are no checks on this performed. 

\> FieldByMatrixBasisNC( <matrices> )
\> FieldByMatrixBasis( <matrices> )

Creates a field with basis <matrices>. The list <matrices> must consist 
of rational matrices which form a basis for a number field. In the faster
NC version, the function assumes that the input is a matrix basis for a
field and no checks are performed.

\> FieldByPolynomialNC( <polynomial> )
\> FieldByPolynomial( <polynomial> )

Creates a field defined by <polynomial>. The polynomial <polynomial>
must be an irreducible rational polynomial. In the faster NC version,
no checks on the input are performed.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Methods for number fields}

We outline a number of functions for number fields.

\> PrimitiveElement( <F> )
\> DefiningPolynomial( <F> )

Computes a primitive element and a defining polynomial for the given number
field. The defining polynomial is the minimal polynomial of the primitive
element. Since <F> contains various primitive elements, 
`PrimitiveElement' tries to find a primitive element which has a
minimal polynomial with small coefficients. Via the global variable
<PRIM_TEST> the user can decide how many primitive elements will be
compared. The default value is 20.

\> IsPrimitiveElement( <F>, <a> )

Checks if the given element generates the field.

\> DegreeOverPrimeField( <F> )

Returns the degree of <F> over the rationals. 

\> EquationOrderBasis( <F> )
\> MaximalOrderBasis( <F> )
\> IsIntegerOfNumberField( <F>, <k> )

These functions return bases for the equation order or the maximal order
of the number field <F>. Also, they allow to check if a given element is
an integer in the given number field.

\> UnitGroup( <F> )
\> IsomorphismPcpGroup( <U> )
\> IsUnitOfNumberField( <F>, <k> )

These functions determine the unit group of <F> and an isomorphism to
a pcp group. (Recall that the unit group of <F> is a finitely generated 
abelian group.) The isomorphism can be used for various computations with
the unit group. Also, the last function allows to check whether a given
element is a unit in <F>. 

\> ExponentsOfUnits( <F>, <elms> )

This function determines the exponent vectors of the elements in <elms>
with respect to the generators of the unit group of <F>. If the unit
group of <F> is not known, then the function computes this unit group also.

\> IsCyclotomicField( <F> )

Check whether <F> is cyclotomic.

\> NormCosetsOfNumberField( <F>, <norm> )

Returns a description for the set of all elements of norm <norm> in <F>. 
These elements can be written as a finite union of cosets of the unit
group of <F>. The function returns coset representatives for these cosets.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Presentations of multiplicative subgroups}
\label{section_present}

Suppose that a finite number of
invertible elements
of a number field are given. Then these elements generate a finitely
generated abelian group. However, it is a non-trivial task to provide
a presentation for this abelian group. The most useful representation
for such groups is as pcp group.

\> PcpPresentationOfMultiplicativeSubgroup( <F>, <elms> )
\> IsomorphismPcpGroup( <F>, <elms> )

Determine a pcp presentation for the multiplicative group of
$<F>\backslash\{0\}$ generated by
<elms> and an isomorphism on this presentation. 
Note, that the method {\tt IsomorphismPcpGroup} is defined in the
Polycyclic package \cite{Polycyclic}. We refer to the manual of this
package for further background. 


\> Kernel( <map> )
\> ImagesSet( <map>, <fieldelms> ) 
\> ImageElm( <map>, <fieldelm> )
\> PreImagesRepresentative( <map>, <pcpelm> )

These functions can be used to compute with an isomorphism to a pcp
presented image. If <fieldelm> is not contained in the source of
<map>,
then the function {\tt ImageElm} returns fail.

In the determination of the Pcp-presentation of a multiplicative
subgroup generated by <elms> the relations between the elements in
<elms> play an important role.
Let $elms=\{e_1,\dots,e_l\}$ be a finite subset of a field <F>.
The relation lattice for <elms> is 
$$
rl(elms):=\left\{(h_1,\dots,h_l) \in \Z^l | e_1^{h_1} \cdots
e_l^{h_l} = 1\right\} .
$$

\> RelationLattice( <F>, <elms> )

Determines a generating set 
for the relation lattice of the field elements <elms>.
 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Methods to compute with subgroups of the unit group}

\> RelationLatticeOfUnits( <F>, <elms> )

Determines a basis for the relation lattice of the units <elms> in 
triangularized form. Note that this method is more efficient than 
the method {\tt RelationLattice}.

\> IntersectionOfUnitSubgroups( <F>, <gen1>, <gen2> )

The lists <gen1> and <gen2> are supposed to generate two subgroups 
$U_1$ and $U_2$ of the unit group of <F>. This function determines 
the intersection of $U_1$ with $U_2$. The result is returned as a 
list of vectors generating the lattice $\{ e \in \Z^n \mid g_1^{e_1} 
\cdots g_n^{e_n} \in U_2 \}$ for <gen1> = $[g_1, \ldots, g_n]$.

This function does not check the input for efficiency reasons and it 
may return wrong results if the input generators do not fulfil the 
requirements.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Factorisation of polynomials over a number field}

\> FactorsPolynomialKant( <pol>, <F> )

Factors <pol>, a polynomial with coefficients in the rationals, over the
number field <F>, which have to be constructed by `FieldByPolynomial' or
may be the rationals itself. In the coefficients of the factors, <a>
denotes the primitive Element one can obtain from `PrimitiveElement(<F>)',
i. e. a root of the defining Polynomial of <F>. 

\beginexample
gap> x := Indeterminate( Rationals );
x_1
gap> pol := 2*x^7+2*x^5+8*x^4+8*x^2;
2*x_1^7+2*x_1^5+8*x_1^4+8*x_1^2
gap> L := FieldByPolynomial(  x^3-4 );
<field in characteristic 0>
gap> FactorsPolynomialKant( pol, L );
[ !2*x_1, x_1, x_1+(a), x_1^2+(-1*a)*x_1+(a^2), x_1^2+!1 ]
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Examples}

\> ExampleMatField( <l> )

This function returns some examples of fields generated by matrices. 
There are 9 such example fields provided and they can be obtained by
assigning the input <l> to an integer between 1 and 9. Some of the
properties of the examples are summarized in the following table.

\
\settabs \+ \hskip 4cm & \hskip 3cm  & \hskip 4cm& \cr
\+ & degree over \Q & number of generators & dimension of generators\cr
\+ {\tt ExampleMatField(1)}  & 4& 4& 4 \cr 
\+ {\tt ExampleMatField(2)}  & 4& 4& 4\cr 
\+ {\tt ExampleMatField(3)}  & 4& 4& 4\cr 
\+ {\tt ExampleMatField(4)}  & 4& 13&4 \cr 
\+ {\tt ExampleMatField(5)}  & 4& 13&4 \cr 
\+ {\tt ExampleMatField(6)}  & 4& 7& 4\cr 
\+ {\tt ExampleMatField(7)}  & 4& 18& 4\cr 
\+ {\tt ExampleMatField(8)}  & 4& 13& 4\cr 
\+ {\tt ExampleMatField(9)}  & 4& 7& 4\cr 








