
<Chapter Label="Working with number fields">
<Heading>Working with number fields</Heading>

An algebraic number field is a finite-dimensional extension of the
rational numbers <M>&QQ;</M>. 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 Label="Creation of number fields">
<Heading>Creation of number fields</Heading>

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

<ManSection>
<Func Name="FieldByMatricesNC" Arg="matrices"/>
<Func Name="FieldByMatrices" Arg="matrices"/>
<Description>
Creates a field generated by the rational matrices <A>matrices</A>. In
the faster NC version, the function assumes that the input generates
a field and there are no checks on this performed.
</Description>
</ManSection>

<ManSection>
<Func Name="FieldByMatrixBasisNC" Arg="matrices"/>
<Func Name="FieldByMatrixBasis" Arg="matrices"/>
<Description>
Creates a field with basis <A>matrices</A>. The list <A>matrices</A> 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.
</Description>
</ManSection>

<ManSection>
<Func Name="FieldByPolynomialNC" Arg="polynomial"/>
<Func Name="FieldByPolynomial" Arg="polynomial"/>
<Description>
Creates a field defined by <A>polynomial</A>. The polynomial <A>polynomial</A>
must be an irreducible rational polynomial. In the faster NC version,
no checks on the input are performed.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Methods for number fields">
<Heading>Methods for number fields</Heading>

We outline a number of functions for number fields.

<ManSection>
<Func Name="PrimitiveElement" Arg="F"/>
<Func Name="DefiningPolynomial" Arg="F"/>
<Description>
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 <A>F</A> contains various primitive elements,
<C>PrimitiveElement</C> tries to find a primitive element which has a
minimal polynomial with small coefficients. Via the user preference
<C>PrimitiveElementTrials</C> the user can decide how many primitive
elements will be compared. The default value is 20.
(See <Ref BookName="ref" Func="SetUserPreference"/> for more information about
user preferences.)
</Description>
</ManSection>

<ManSection>
<Func Name="IsPrimitiveElementOfNumberField" Arg="F, a"/>
<Description>
Checks if the given element generates the field.
</Description>
</ManSection>

<ManSection>
<Func Name="DegreeOverPrimeField" Arg="F"/>
<Description>
Returns the degree of <A>F</A> over the rationals.
</Description>
</ManSection>

<ManSection>
<Func Name="EquationOrderBasis" Arg="F"/>
<Func Name="MaximalOrderBasis" Arg="F"/>
<Func Name="IsIntegerOfNumberField" Arg="F, k"/>
<Description>
These functions return bases for the equation order or the maximal order
of the number field <A>F</A>. Also, they allow to check if a given element is
an integer in the given number field.
</Description>
</ManSection>

<ManSection>
<Func Name="UnitGroup" Arg="F"/>
<Description>
determines the unit group of <A>F</A>.
<P/>

Recall that the unit group of <A>F</A> is a finitely generated abelian
group. The function <C>IsomorphismPcpGroup</C> from the &Polycyclic;
<Cite Key="Polycyclic"/> package gives an isomorphism to a pcp group which
can be used for various computations with the unit group.
</Description>
</ManSection>

<ManSection>
<Func Name="IsUnitOfNumberField" Arg="F, k"/>
<Description>
checks whether the element <A>k</A> is a unit in <A>F</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="ExponentsOfUnits" Arg="F, elms"/>
<Description>
This function determines the exponent vectors of the elements in <A>elms</A>
with respect to the generators of the unit group of <A>F</A>. If the unit
group of <A>F</A> is not known, then the function computes this unit group also.
</Description>
</ManSection>

<ManSection>
<Func Name="IsCyclotomicField" Arg="F"/>
<Description>
Check whether <A>F</A> is cyclotomic.
</Description>
</ManSection>

<ManSection>
<Func Name="NormCosetsOfNumberField" Arg="F, norm"/>
<Description>
Returns a description for the set of all elements of norm <A>norm</A> in <A>F</A>.
These elements can be written as a finite union of cosets of the unit
group of <A>F</A>. The function returns coset representatives for these cosets.
</Description>
</ManSection>


</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Presentations of multiplicative subgroups">
<Heading>Presentations of multiplicative subgroups</Heading>

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.

<ManSection>
<Func Name="PcpPresentationOfMultiplicativeSubgroup" Arg="F, elms"/>
<Func Name="IsomorphismPcpGroup" Arg="F, elms"/>
<Description>
Determine a pcp presentation for the multiplicative group of
<M><A>F</A>\backslash\{0\}</M> generated by
<A>elms</A> and an isomorphism on this presentation.
Note, that the method <C>IsomorphismPcpGroup</C> is defined in the
&Polycyclic; package <Cite Key="Polycyclic"/>. We refer to the manual of this
package for further background.
<P/>

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

<ManSection>
<Func Name="RelationLattice" Arg="F, elms"/>
<Description>
Determines a generating set
for the relation lattice of the field elements <A>elms</A>.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Methods to compute with subgroups of the unit group">
<Heading>Methods to compute with subgroups of the unit group</Heading>

<ManSection>
<Func Name="RelationLatticeOfUnits" Arg="F, elms"/>
<Description>
Determines a basis for the relation lattice of the units <A>elms</A> in
triangularized form. Note that this method is more efficient than
the method <C>RelationLattice</C>.
</Description>
</ManSection>

<ManSection>
<Func Name="IntersectionOfUnitSubgroups" Arg="F, gen1, gen2"/>
<Description>
The lists <A>gen1</A> and <A>gen2</A> are supposed to generate two subgroups
<M>U_1</M> and <M>U_2</M> of the unit group of <A>F</A>. This function determines
the intersection of <M>U_1</M> with <M>U_2</M>. The result is returned as a
list of vectors generating the lattice <M>\{ e \in &ZZ;^n \mid g_1^{e_1}
\cdots g_n^{e_n} \in U_2 \}</M> for <A>gen1</A> = <M>[g_1, \ldots, g_n]</M>.
<P/>

For efficiency reasons this function does not check the input and it
may return wrong results if the input generators do not fulfil the
requirements.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Factorisation of polynomials over a number field">
<Heading>Factorisation of polynomials over a number field</Heading>

<ManSection>
<Func Name="FactorsPolynomialAlgExt" Arg="F, pol"/>
<Description>
embeds the rational polynomial <A>pol</A> into the polynomial ring over the
number field <A>F</A>, which has to be constructed by <C>FieldByPolynomial</C>
or <C>AlgebraicExtension</C>, and returns the factorization of the embedded
polynomial.  By default <A>a</A> denotes the primitive element of the field
one can obtain from <C>PrimitiveElement(<A>F</A>)</C>, that is, a root of the
defining polynomial of <A>F</A>.
</Description>
</ManSection>

<ManSection>
<Func Name="FactorsPolynomialAlnuth" Arg="pol"/>
<Description>
takes a polynomial <A>pol</A> defined over an algebraic extension of the
Rationals and factors it using the external CAS (PARI/GP or OSCAR).
<P/>

The alias <C>FactorsPolynomialPari</C> is provided for backwards compatibility.

<Example><![CDATA[
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+(-a)*y+a^2 ]
gap> FactorsPolynomialAlnuth( last[5] );
[ y^2+(-a)*y+a^2 ]
]]></Example>
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Examples">
<Heading>Examples</Heading>

<ManSection>
<Func Name="ExampleMatField" Arg="l"/>
<Description>
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 <A>l</A> to an integer between 1 and 9. Some of the
properties of the examples are summarized in the following table.

<Log><![CDATA[
                    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
]]></Log>
</Description>
</ManSection>

</Section>
</Chapter>
