\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 `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 `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 `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}

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

embeds the rational polynomial <pol> into the polynomial ring over the
number field <F>, which has to be constructed by `FieldByPolynomial'
or `AlgebraicExtension', and returns the factorization of the embedded
polynomial.  By default <a> denotes the primitive element of the field
one can obtain from `PrimitiveElement(<F>)', i. e. a root of the
defining polynomial of <F>. 

\> FactorsPolynomialKant( <pol> )

takes a polynomial <pol> defined over an algebraic extension of the
Rationals and factors it using KANT.

\beginexample
gap> x := Indeterminate( Rationals, "x" );;
gap> pol := 2*x^7+2*x^5+8*x^4+8*x^2;
2*x^7+2*x^5+8*x^4+8*x^2
gap> L := FieldByPolynomial( x^3-4 );
<algebraic extension over the Rationals of degree 3>
gap> y := Indeterminate( L, "y" );;
gap> FactorsPolynomialAlgExt( L, pol );
[ !2*y, y, y+(a), y^2+!1, y^2+((-1*a))*y+(a^2) ]
gap> FactorsPolynomialKant( last[5] );
[ y^2+((-1*a))*y+(a^2) ]
gap>
\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.

\beginexample
                    degree over Q  number of generators  dim. of generators
ExampleMatField(1)              4                     4                   4
ExampleMatField(2)              4                     4                   4
ExampleMatField(3)              4                     4                   4
ExampleMatField(4)              4                    13                   4
ExampleMatField(5)              4                    13                   4
ExampleMatField(6)              4                     7                   4
ExampleMatField(7)              4                    18                   4
ExampleMatField(8)              4                    13                   4
ExampleMatField(9)              4                     7                   4
\endexample