  
  [1X2 [33X[0;0YWorking with number fields[133X[101X
  
  [33X[0;0YAn  algebraic number field is a finite-dimensional extension of the rational
  numbers [22Xℚ[122X. 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.[133X
  
  
  [1X2.1 [33X[0;0YCreation of number fields[133X[101X
  
  [33X[0;0YWe provide functions to create number fields defined by rational matrices or
  by rational polynomials.[133X
  
  [1X2.1-1 FieldByMatricesNC[101X
  
  [33X[1;0Y[29X[2XFieldByMatricesNC[102X( [3Xmatrices[103X ) [32X function[133X
  [33X[1;0Y[29X[2XFieldByMatrices[102X( [3Xmatrices[103X ) [32X function[133X
  
  [33X[0;0YCreates  a  field generated by the rational matrices [3Xmatrices[103X. In the faster
  NC  version, the function assumes that the input generates a field and there
  are no checks on this performed.[133X
  
  [1X2.1-2 FieldByMatrixBasisNC[101X
  
  [33X[1;0Y[29X[2XFieldByMatrixBasisNC[102X( [3Xmatrices[103X ) [32X function[133X
  [33X[1;0Y[29X[2XFieldByMatrixBasis[102X( [3Xmatrices[103X ) [32X function[133X
  
  [33X[0;0YCreates  a  field  with  basis  [3Xmatrices[103X.  The list [3Xmatrices[103X 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.[133X
  
  [1X2.1-3 FieldByPolynomialNC[101X
  
  [33X[1;0Y[29X[2XFieldByPolynomialNC[102X( [3Xpolynomial[103X ) [32X function[133X
  [33X[1;0Y[29X[2XFieldByPolynomial[102X( [3Xpolynomial[103X ) [32X function[133X
  
  [33X[0;0YCreates  a field defined by [3Xpolynomial[103X. The polynomial [3Xpolynomial[103X must be an
  irreducible  rational polynomial. In the faster NC version, no checks on the
  input are performed.[133X
  
  
  [1X2.2 [33X[0;0YMethods for number fields[133X[101X
  
  [33X[0;0YWe outline a number of functions for number fields.[133X
  
  [1X2.2-1 PrimitiveElement[101X
  
  [33X[1;0Y[29X[2XPrimitiveElement[102X( [3XF[103X ) [32X function[133X
  [33X[1;0Y[29X[2XDefiningPolynomial[102X( [3XF[103X ) [32X function[133X
  
  [33X[0;0YComputes  a primitive element and a defining polynomial for the given number
  field.  The  defining  polynomial is the minimal polynomial of the primitive
  element. Since [3XF[103X contains various primitive elements, [10XPrimitiveElement[110X tries
  to  find  a  primitive  element  which  has  a minimal polynomial with small
  coefficients.  Via  the  user preference [10XPrimitiveElementTrials[110X the user can
  decide  how  many  primitive elements will be compared. The default value is
  20.   (See   [2XSetUserPreference[102X   ([14XReference:   SetUserPreference[114X)  for  more
  information about user preferences.)[133X
  
  [1X2.2-2 IsPrimitiveElementOfNumberField[101X
  
  [33X[1;0Y[29X[2XIsPrimitiveElementOfNumberField[102X( [3XF[103X, [3Xa[103X ) [32X function[133X
  
  [33X[0;0YChecks if the given element generates the field.[133X
  
  [1X2.2-3 DegreeOverPrimeField[101X
  
  [33X[1;0Y[29X[2XDegreeOverPrimeField[102X( [3XF[103X ) [32X function[133X
  
  [33X[0;0YReturns the degree of [3XF[103X over the rationals.[133X
  
  [1X2.2-4 EquationOrderBasis[101X
  
  [33X[1;0Y[29X[2XEquationOrderBasis[102X( [3XF[103X ) [32X function[133X
  [33X[1;0Y[29X[2XMaximalOrderBasis[102X( [3XF[103X ) [32X function[133X
  [33X[1;0Y[29X[2XIsIntegerOfNumberField[102X( [3XF[103X, [3Xk[103X ) [32X function[133X
  
  [33X[0;0YThese  functions return bases for the equation order or the maximal order of
  the  number  field  [3XF[103X.  Also,  they  allow to check if a given element is an
  integer in the given number field.[133X
  
  [1X2.2-5 UnitGroup[101X
  
  [33X[1;0Y[29X[2XUnitGroup[102X( [3XF[103X ) [32X function[133X
  
  [33X[0;0Ydetermines the unit group of [3XF[103X.[133X
  
  [33X[0;0YRecall  that  the unit group of [3XF[103X is a finitely generated abelian group. The
  function  [10XIsomorphismPcpGroup[110X  from  the [5XPolycyclic[105X [EHN11] package gives an
  isomorphism  to  a pcp group which can be used for various computations with
  the unit group.[133X
  
  [1X2.2-6 IsUnitOfNumberField[101X
  
  [33X[1;0Y[29X[2XIsUnitOfNumberField[102X( [3XF[103X, [3Xk[103X ) [32X function[133X
  
  [33X[0;0Ychecks whether the element [3Xk[103X is a unit in [3XF[103X.[133X
  
  [1X2.2-7 ExponentsOfUnits[101X
  
  [33X[1;0Y[29X[2XExponentsOfUnits[102X( [3XF[103X, [3Xelms[103X ) [32X function[133X
  
  [33X[0;0YThis  function  determines the exponent vectors of the elements in [3Xelms[103X with
  respect  to the generators of the unit group of [3XF[103X. If the unit group of [3XF[103X is
  not known, then the function computes this unit group also.[133X
  
  [1X2.2-8 IsCyclotomicField[101X
  
  [33X[1;0Y[29X[2XIsCyclotomicField[102X( [3XF[103X ) [32X function[133X
  
  [33X[0;0YCheck whether [3XF[103X is cyclotomic.[133X
  
  [1X2.2-9 NormCosetsOfNumberField[101X
  
  [33X[1;0Y[29X[2XNormCosetsOfNumberField[102X( [3XF[103X, [3Xnorm[103X ) [32X function[133X
  
  [33X[0;0YReturns  a  description for the set of all elements of norm [3Xnorm[103X in [3XF[103X. These
  elements  can be written as a finite union of cosets of the unit group of [3XF[103X.
  The function returns coset representatives for these cosets.[133X
  
  
  [1X2.3 [33X[0;0YPresentations of multiplicative subgroups[133X[101X
  
  [33X[0;0YSuppose  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.[133X
  
  [1X2.3-1 PcpPresentationOfMultiplicativeSubgroup[101X
  
  [33X[1;0Y[29X[2XPcpPresentationOfMultiplicativeSubgroup[102X( [3XF[103X, [3Xelms[103X ) [32X function[133X
  [33X[1;0Y[29X[2XIsomorphismPcpGroup[102X( [3XF[103X, [3Xelms[103X ) [32X function[133X
  
  [33X[0;0YDetermine  a  pcp presentation for the multiplicative group of [22X[3XF[103Xbackslash{0}[122X
  generated  by  [3Xelms[103X  and an isomorphism on this presentation. Note, that the
  method  [10XIsomorphismPcpGroup[110X is defined in the [5XPolycyclic[105X package [EHN11]. We
  refer to the manual of this package for further background.[133X
  
  [33X[0;0YIn  the  determination  of the Pcp-presentation of a multiplicative subgroup
  generated  by  [3Xelms[103X  the  relations  between  the  elements  in [3Xelms[103X play an
  important role. Let [22Xelms={e_1,dots,e_l}[122X be a finite subset of a field [3XF[103X. The
  relation lattice for [3Xelms[103X is[133X
  
  
  [24X[33X[0;6Yrl(elms):=\left\{(h_1,\dots,h_l)  \in  ℤ^l  |  e_1^{h_1}  \cdots e_l^{h_l} =
  1\right\} .[133X
  
  [124X
  
  [1X2.3-2 RelationLattice[101X
  
  [33X[1;0Y[29X[2XRelationLattice[102X( [3XF[103X, [3Xelms[103X ) [32X function[133X
  
  [33X[0;0YDetermines  a  generating set for the relation lattice of the field elements
  [3Xelms[103X.[133X
  
  
  [1X2.4 [33X[0;0YMethods to compute with subgroups of the unit group[133X[101X
  
  [1X2.4-1 RelationLatticeOfUnits[101X
  
  [33X[1;0Y[29X[2XRelationLatticeOfUnits[102X( [3XF[103X, [3Xelms[103X ) [32X function[133X
  
  [33X[0;0YDetermines   a  basis  for  the  relation  lattice  of  the  units  [3Xelms[103X  in
  triangularized form. Note that this method is more efficient than the method
  [10XRelationLattice[110X.[133X
  
  [1X2.4-2 IntersectionOfUnitSubgroups[101X
  
  [33X[1;0Y[29X[2XIntersectionOfUnitSubgroups[102X( [3XF[103X, [3Xgen1[103X, [3Xgen2[103X ) [32X function[133X
  
  [33X[0;0YThe  lists  [3Xgen1[103X and [3Xgen2[103X are supposed to generate two subgroups [22XU_1[122X and [22XU_2[122X
  of  the  unit  group  of [3XF[103X. This function determines the intersection of [22XU_1[122X
  with [22XU_2[122X. The result is returned as a list of vectors generating the lattice
  [22X{ e ∈ ℤ^n ∣ g_1^e_1 ⋯ g_n^e_n ∈ U_2 }[122X for [3Xgen1[103X = [22X[g_1, ..., g_n][122X.[133X
  
  [33X[0;0YFor  efficiency  reasons  this  function does not check the input and it may
  return wrong results if the input generators do not fulfil the requirements.[133X
  
  
  [1X2.5 [33X[0;0YFactorisation of polynomials over a number field[133X[101X
  
  [1X2.5-1 FactorsPolynomialAlgExt[101X
  
  [33X[1;0Y[29X[2XFactorsPolynomialAlgExt[102X( [3XF[103X, [3Xpol[103X ) [32X function[133X
  
  [33X[0;0Yembeds  the rational polynomial [3Xpol[103X into the polynomial ring over the number
  field   [3XF[103X,   which   has   to   be   constructed   by  [10XFieldByPolynomial[110X  or
  [10XAlgebraicExtension[110X,   and   returns   the   factorization  of  the  embedded
  polynomial.  By default [3Xa[103X denotes the primitive element of the field one can
  obtain  from [10XPrimitiveElement([3XF[103X[10X)[110X, that is, a root of the defining polynomial
  of [3XF[103X.[133X
  
  [1X2.5-2 FactorsPolynomialAlnuth[101X
  
  [33X[1;0Y[29X[2XFactorsPolynomialAlnuth[102X( [3Xpol[103X ) [32X function[133X
  
  [33X[0;0Ytakes  a polynomial [3Xpol[103X defined over an algebraic extension of the Rationals
  and factors it using the external CAS (PARI/GP or OSCAR).[133X
  
  [33X[0;0YThe alias [10XFactorsPolynomialPari[110X is provided for backwards compatibility.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27Xx := Indeterminate( Rationals, "x" );;[127X[104X
    [4X[25Xgap>[125X [27Xpol := 2*x^7+2*x^5+8*x^4+8*x^2;[127X[104X
    [4X[28X2*x^7+2*x^5+8*x^4+8*x^2[128X[104X
    [4X[25Xgap>[125X [27XL := FieldByPolynomial( x^3-4 );[127X[104X
    [4X[28X<algebraic extension over the Rationals of degree 3>[128X[104X
    [4X[25Xgap>[125X [27Xy := Indeterminate( L, "y" );;[127X[104X
    [4X[25Xgap>[125X [27XFactorsPolynomialAlgExt( L, pol );[127X[104X
    [4X[28X[ !2*y, y, y+a, y^2+!1, y^2+(-a)*y+a^2 ][128X[104X
    [4X[25Xgap>[125X [27XFactorsPolynomialAlnuth( last[5] );[127X[104X
    [4X[28X[ y^2+(-a)*y+a^2 ][128X[104X
  [4X[32X[104X
  
  
  [1X2.6 [33X[0;0YExamples[133X[101X
  
  [1X2.6-1 ExampleMatField[101X
  
  [33X[1;0Y[29X[2XExampleMatField[102X( [3Xl[103X ) [32X function[133X
  
  [33X[0;0YThis  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  [3Xl[103X  to  an  integer  between  1  and  9. Some of the properties of the
  examples are summarized in the following table.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28X                    degree over Q  number of generators  dim. of generators[128X[104X
    [4X[28XExampleMatField(1)              4                     4                   4[128X[104X
    [4X[28XExampleMatField(2)              4                     4                   4[128X[104X
    [4X[28XExampleMatField(3)              4                     4                   4[128X[104X
    [4X[28XExampleMatField(4)              4                    13                   4[128X[104X
    [4X[28XExampleMatField(5)              4                    13                   4[128X[104X
    [4X[28XExampleMatField(6)              4                     7                   4[128X[104X
    [4X[28XExampleMatField(7)              4                    18                   4[128X[104X
    [4X[28XExampleMatField(8)              4                    13                   4[128X[104X
    [4X[28XExampleMatField(9)              4                     7                   4[128X[104X
  [4X[32X[104X
  
