18 Cyclotomic Numbers
  
  GAP  admits  computations in abelian extension fields of the rational number
  field  ℚ,  that is fields with abelian Galois group over ℚ. These fields are
  subfields  of  cyclotomic  fields  ℚ(e_n)  where  e_n  =  exp(2  π i/n) is a
  primitive  complex  n-th  root  of  unity.  The elements of these fields are
  called cyclotomics.
  
  Information  concerning  operations  for domains of cyclotomics, for example
  certain integral bases of fields of cyclotomics, can be found in Chapter 60.
  For  more  general  operations  that  take  a field extension as a –possibly
  optional–  argument,  e.g.,  Trace  (58.3-5)  or  Coefficients (61.6-3), see
  Chapter 58.
  
  
  18.1 Operations for Cyclotomics
  
  18.1-1 E
  
  E( n )  operation
  
  E  returns  the  primitive n-th root of unity e_n = exp(2π i/n). Cyclotomics
  are  usually  entered as sums of roots of unity, with rational coefficients,
  and  irrational  cyclotomics  are  displayed  in  such  a  way. (For special
  cyclotomics, see 18.4.)
  
    Example  
    gap> E(9); E(9)^3; E(6); E(12) / 3;
    -E(9)^4-E(9)^7
    E(3)
    -E(3)^2
    -1/3*E(12)^7
  
  
  A  particular basis is used to express cyclotomics, see 60.3; note that E(9)
  is not a basis element, as the above example shows.
  
  18.1-2 Cyclotomics
  
  Cyclotomics  global variable
  
  is the domain of all cyclotomics.
  
    Example  
    gap> E(9) in Cyclotomics; 37 in Cyclotomics; true in Cyclotomics;
    true
    true
    false
  
  
  As  the cyclotomics are field elements, the usual arithmetic operators +, -,
  *  and / (and ^ to take powers by integers) are applicable. Note that ^ does
  not  denote  the  conjugation  of  group  elements, so it is not possible to
  explicitly  construct  groups  of  cyclotomics.  (However, it is possible to
  compute  the  inverse and the multiplicative order of a nonzero cyclotomic.)
  Also,  taking  the  k-th  power  of  a  root  of  unity  z  defines a Galois
  automorphism  if  and  only  if k is coprime to the conductor (see Conductor
  (18.1-7)) of z.
  
    Example  
    gap> E(5) + E(3); (E(5) + E(5)^4) ^ 2; E(5) / E(3); E(5) * E(3);
    -E(15)^2-2*E(15)^8-E(15)^11-E(15)^13-E(15)^14
    -2*E(5)-E(5)^2-E(5)^3-2*E(5)^4
    E(15)^13
    E(15)^8
    gap> Order( E(5) ); Order( 1+E(5) );
    5
    infinity
  
  
  18.1-3 IsCyclotomic
  
  IsCyclotomic( obj )  Category
  IsCyc( obj )  Category
  
  Every   object   in  the  family  CyclotomicsFamily  lies  in  the  category
  IsCyclotomic.  This  covers  integers,  rationals,  proper  cyclotomics, the
  object  infinity  (18.2-1), and unknowns (see Chapter 74). All these objects
  except  infinity  (18.2-1)  and  unknowns  lie  also  in the category IsCyc,
  infinity (18.2-1) lies in (and can be detected from) the category IsInfinity
  (18.2-1), and unknowns lie in IsUnknown (74.1-3).
  
    Example  
    gap> IsCyclotomic(0); IsCyclotomic(1/2*E(3)); IsCyclotomic( infinity );
    true
    true
    true
    gap> IsCyc(0); IsCyc(1/2*E(3)); IsCyc( infinity );
    true
    true
    false
  
  
  18.1-4 IsIntegralCyclotomic
  
  IsIntegralCyclotomic( obj )  property
  
  A  cyclotomic is called integral or a cyclotomic integer if all coefficients
  of  its  minimal  polynomial  over  the  rationals  are  integers. Since the
  underlying  basis  of  the  external  representation  of  cyclotomics  is an
  integral   basis  (see 60.3),  the  subring  of  cyclotomic  integers  in  a
  cyclotomic  field  is  formed  by  those  cyclotomics for which the external
  representation  is a list of integers. For example, square roots of integers
  are  cyclotomic  integers  (see 18.4),  any  root  of  unity is a cyclotomic
  integer,  character values are always cyclotomic integers, but all rationals
  which are not integers are not cyclotomic integers.
  
    Example  
    gap> r:= ER( 5 );               # The square root of 5 ...
    E(5)-E(5)^2-E(5)^3+E(5)^4
    gap> IsIntegralCyclotomic( r ); # ... is a cyclotomic integer.
    true
    gap> r2:= 1/2 * r;              # This is not a cyclotomic integer, ...
    1/2*E(5)-1/2*E(5)^2-1/2*E(5)^3+1/2*E(5)^4
    gap> IsIntegralCyclotomic( r2 );
    false
    gap> r3:= 1/2 * r - 1/2;        # ... but this is one.
    E(5)+E(5)^4
    gap> IsIntegralCyclotomic( r3 );
    true
  
  
  18.1-5 Int
  
  Int( cyc )  method
  
  The  operation  Int  can  be  used  to  find a cyclotomic integer near to an
  arbitrary cyclotomic, by applying Int (14.2-3) to the coefficients.
  
    Example  
    gap> Int( E(5)+1/2*E(5)^2 ); Int( 2/3*E(7)-3/2*E(4) );
    E(5)
    -E(4)
  
  
  18.1-6 String
  
  String( cyc )  method
  
  The  operation String returns for a cyclotomic cyc a string corresponding to
  the way the cyclotomic is printed by ViewObj (6.3-5) and PrintObj (6.3-5).
  
    Example  
    gap> String( E(5)+1/2*E(5)^2 ); String( 17/3 );
    "E(5)+1/2*E(5)^2"
    "17/3"
  
  
  18.1-7 Conductor
  
  Conductor( cyc )  attribute
  Conductor( C )  attribute
  
  For  an  element  cyc  of a cyclotomic field, Conductor returns the smallest
  integer  n  such  that  cyc is contained in the n-th cyclotomic field. For a
  collection  C  of  cyclotomics (for example a dense list of cyclotomics or a
  field  of  cyclotomics),  Conductor returns the smallest integer n such that
  all elements of C are contained in the n-th cyclotomic field.
  
    Example  
    gap> Conductor( 0 ); Conductor( E(10) ); Conductor( E(12) );
    1
    5
    12
  
  
  18.1-8 AbsoluteValue
  
  AbsoluteValue( cyc )  attribute
  
  returns  the  absolute  value of a cyclotomic number cyc. At the moment only
  methods for rational numbers exist.
  
    Example  
    gap> AbsoluteValue(-3);
    3
  
  
  18.1-9 RoundCyc
  
  RoundCyc( cyc )  operation
  
  is  a  cyclotomic  integer z (see IsIntegralCyclotomic (18.1-4)) near to the
  cyclotomic  cyc in the following sense: Let c be the i-th coefficient in the
  external  representation  (see CoeffsCyc  (18.1-10))  of  cyc. Then the i-th
  coefficient  in the external representation of z is Int( c + 1/2 ) or Int( c
  - 1/2 ), depending on whether c is nonnegative or negative, respectively.
  
  Expressed   in  terms  of  the  Zumbroich  basis  (see 60.3),  rounding  the
  coefficients  of  cyc  w.r.t. this  basis  to the nearest integer yields the
  coefficients of z.
  
    Example  
    gap> RoundCyc( E(5)+1/2*E(5)^2 ); RoundCyc( 2/3*E(7)+3/2*E(4) );
    E(5)+E(5)^2
    -2*E(28)^3+E(28)^4-2*E(28)^11-2*E(28)^15-2*E(28)^19-2*E(28)^23
     -2*E(28)^27
  
  
  18.1-10 CoeffsCyc
  
  CoeffsCyc( cyc, N )  function
  
  Let  cyc  be a cyclotomic with conductor n (see Conductor (18.1-7)). If N is
  not  a  multiple  of  n  then  CoeffsCyc  returns fail because cyc cannot be
  expressed  in  terms  of  N-th roots of unity. Otherwise CoeffsCyc returns a
  list  of length N with entry at position j equal to the coefficient of exp(2
  π  i  (j-1)/N)  if this root belongs to the N-th Zumbroich basis (see 60.3),
  and  equal  to  zero otherwise. So we have cyc = CoeffsCyc( cyc, N ) * List(
  [1..N], j -> E(N)^(j-1) ).
  
    Example  
    gap> cyc:= E(5)+E(5)^2;
    E(5)+E(5)^2
    gap> CoeffsCyc( cyc, 5 );  CoeffsCyc( cyc, 15 );  CoeffsCyc( cyc, 7 );
    [ 0, 1, 1, 0, 0 ]
    [ 0, -1, 0, 0, 0, 0, 0, 0, -1, 0, 0, -1, 0, -1, 0 ]
    fail
  
  
  18.1-11 DenominatorCyc
  
  DenominatorCyc( cyc )  function
  
  For  a  cyclotomic  number  cyc  (see IsCyclotomic  (18.1-3)), this function
  returns  the  smallest  positive integer n such that n * cyc is a cyclotomic
  integer  (see IsIntegralCyclotomic  (18.1-4)). For rational numbers cyc, the
  result is the same as that of DenominatorRat (17.2-5).
  
  18.1-12 ExtRepOfObj
  
  ExtRepOfObj( cyc )  method
  
  The  external  representation  of  a  cyclotomic  cyc  with conductor n (see
  Conductor  (18.1-7) is the list returned by CoeffsCyc (18.1-10), called with
  cyc and n.
  
    Example  
    gap> ExtRepOfObj( E(5) ); CoeffsCyc( E(5), 5 );
    [ 0, 1, 0, 0, 0 ]
    [ 0, 1, 0, 0, 0 ]
    gap> CoeffsCyc( E(5), 15 );
    [ 0, 0, 0, 0, 0, 0, 0, 0, -1, 0, 0, 0, 0, -1, 0 ]
  
  
  18.1-13 DescriptionOfRootOfUnity
  
  DescriptionOfRootOfUnity( root )  function
  
  Given  a  cyclotomic  root  that is known to be a root of unity (this is not
  checked),  DescriptionOfRootOfUnity  returns  a  list  [  n,  e ] of coprime
  positive integers such that root = E(n)^e holds.
  
    Example  
    gap> E(9);  DescriptionOfRootOfUnity( E(9) );
    -E(9)^4-E(9)^7
    [ 9, 1 ]
    gap> DescriptionOfRootOfUnity( -E(3) );
    [ 6, 5 ]
  
  
  18.1-14 IsGaussInt
  
  IsGaussInt( x )  function
  
  IsGaussInt   returns   true   if   the   object  x  is  a  Gaussian  integer
  (see GaussianIntegers  (60.5-1)), and false otherwise. Gaussian integers are
  of the form a + b*E(4), where a and b are integers.
  
  18.1-15 IsGaussRat
  
  IsGaussRat( x )  function
  
  IsGaussRat   returns   true   if   the  object  x  is  a  Gaussian  rational
  (see GaussianRationals  (60.1-3)),  and  false otherwise. Gaussian rationals
  are of the form a + b*E(4), where a and b are rationals.
  
  18.1-16 DefaultField
  
  DefaultField( list )  function
  
  DefaultField  for  cyclotomics  is defined to return the smallest cyclotomic
  field containing the given elements.
  
  Note  that  Field  (58.1-3)  returns the smallest field containing all given
  elements,  which  need  not be a cyclotomic field. In both cases, the fields
  represent vector spaces over the rationals (see 60.3).
  
    Example  
    gap> Field( E(5)+E(5)^4 );  DefaultField( E(5)+E(5)^4 );
    NF(5,[ 1, 4 ])
    CF(5)
  
  
  
  18.2 Infinity and negative Infinity
  
  18.2-1 IsInfinity
  
  IsInfinity( obj )  Category
  IsNegInfinity( obj )  Category
  infinity  global variable
  -infinity  global variable
  
  infinity   and   -infinity   are   special   GAP   objects   that   lie   in
  CyclotomicsFamily. They are larger or smaller than all other objects in this
  family  respectively.  infinity is mainly used as return value of operations
  such  as  Size  (30.4-6)  and  Dimension  (57.3-3) for infinite and infinite
  dimensional domains, respectively.
  
  Some  arithmetic operations are provided for convenience when using infinity
  and -infinity as top and bottom element respectively.
  
    Example  
    gap> -infinity + 1;
    -infinity
    gap> infinity + infinity;
    infinity
  
  
  Often  it  is  useful  to  distinguish infinity from proper cyclotomics. For
  that,  infinity  lies  in the category IsInfinity but not in IsCyc (18.1-3),
  and  the  other  cyclotomics  lie  in the category IsCyc (18.1-3) but not in
  IsInfinity.
  
    Example  
    gap> s:= Size( Rationals );
    infinity
    gap> s = infinity; IsCyclotomic( s ); IsCyc( s ); IsInfinity( s );
    true
    true
    false
    true
    gap> s in Rationals; s > 17;
    false
    true
    gap> Set( [ s, 2, s, E(17), s, 19 ] );
    [ 2, 19, E(17), infinity ]
  
  
  
  18.3 Comparisons of Cyclotomics
  
  To  compare  cyclotomics, the operators <, <=, =, >=, >, and <> can be used,
  the  result  will be true if the first operand is smaller, smaller or equal,
  equal,  larger  or  equal,  larger,  or  unequal,  respectively,  and  false
  otherwise.
  
  Cyclotomics  are  ordered  as follows: The relation between rationals is the
  natural one, rationals are smaller than irrational cyclotomics, and infinity
  (18.2-1)  is  the  largest  cyclotomic.  For two irrational cyclotomics with
  different   conductors  (see  Conductor  (18.1-7)),  the  one  with  smaller
  conductor  is  regarded  as  smaller.  Two  irrational cyclotomics with same
  conductor  are  compared  via their external representation (see ExtRepOfObj
  (18.1-12)).
  
  For comparisons of cyclotomics and other GAP objects, see Section 4.13.
  
    Example  
    gap> E(5) < E(6);      # the latter value has conductor 3
    false
    gap> E(3) < E(3)^2;    # both have conductor 3, compare the ext. repr.
    false
    gap> 3 < E(3); E(5) < E(7);
    true
    true
  
  
  
  18.4 ATLAS Irrationalities
  
  
  18.4-1 EB, EC, ..., EH
  
  EB( N )  function
  EC( N )  function
  ED( N )  function
  EE( N )  function
  EF( N )  function
  EG( N )  function
  EH( N )  function
  
  For  a  positive  integer  N,  let  z  =  E(N) = exp(2 π i/N). The following
  so-called  atomic  irrationalities (see [CCN+85, Chapter 7, Section 10]) can
  be  entered  using  functions.  (Note  that  the  values  are  not necessary
  irrational.)
  
        EB(N)   =   b_N   =   ( ∑_{j = 1}^{N-1} z^{j^2} ) / 2   ,   N ≡ 1 mod 2   
        EC(N)   =   c_N   =   ( ∑_{j = 1}^{N-1} z^{j^3} ) / 3   ,   N ≡ 1 mod 3   
        ED(N)   =   d_N   =   ( ∑_{j = 1}^{N-1} z^{j^4} ) / 4   ,   N ≡ 1 mod 4   
        EE(N)   =   e_N   =   ( ∑_{j = 1}^{N-1} z^{j^5} ) / 5   ,   N ≡ 1 mod 5   
        EF(N)   =   f_N   =   ( ∑_{j = 1}^{N-1} z^{j^6} ) / 6   ,   N ≡ 1 mod 6   
        EG(N)   =   g_N   =   ( ∑_{j = 1}^{N-1} z^{j^7} ) / 7   ,   N ≡ 1 mod 7   
        EH(N)   =   h_N   =   ( ∑_{j = 1}^{N-1} z^{j^8} ) / 8   ,   N ≡ 1 mod 8   
  
  (Note that in EC(N), ..., EH(N), N must be a prime.)
  
    Example  
    gap> EB(5);  EB(9);
    E(5)+E(5)^4
    1
  
  
  
  18.4-2 EI and ER
  
  EI( N )  function
  ER( N )  function
  
  For  a  rational  number  N, ER returns the square root sqrt{N} of N, and EI
  returns  sqrt{-N}.  By  the  chosen  embedding of cyclotomic fields into the
  complex  numbers,  ER returns the positive square root if N is positive, and
  if  N  is  negative  then  ER(N) = EI(-N) holds. In any case, EI(N) = E(4) *
  ER(N).
  
  ER  is  installed  as  method for the operation Sqrt (31.12-5), for rational
  argument.
  
  From a theorem of Gauss we know that b_N =
  
        (-1 + sqrt{N}) / 2     if   N ≡ 1 mod 4    
        (-1 + i sqrt{N}) / 2   if   N ≡ -1 mod 4   
  
  So sqrt{N} can be computed from b_N, see EB (18.4-1).
  
    Example  
    gap> ER(3); EI(3);
    -E(12)^7+E(12)^11
    E(3)-E(3)^2
  
  
  
  18.4-3 EY, EX, ..., ES
  
  EY( N[, d] )  function
  EX( N[, d] )  function
  EW( N[, d] )  function
  EV( N[, d] )  function
  EU( N[, d] )  function
  ET( N[, d] )  function
  ES( N[, d] )  function
  
  For  the  given  integer  N  >  2,  let  N_k  denote  the first integer with
  multiplicative order exactly k modulo N, chosen in the order of preference
  
  
  1, -1, 2, -2, 3, -3, 4, -4, ... .
  
  We define (with z = exp(2 π i/N))
  
        EY(N)   =   y_N   =   z + z^n                                 (n = N_2)   
        EX(N)   =   x_N   =   z + z^n + z^{n^2}                       (n = N_3)   
        EW(N)   =   w_N   =   z + z^n + z^{n^2} + z^{n^3}             (n = N_4)   
        EV(N)   =   v_N   =   z + z^n + z^{n^2} + z^{n^3} + z^{n^4}   (n = N_5)   
        EU(N)   =   u_N   =   z + z^n + z^{n^2} + ... + z^{n^5}       (n = N_6)   
        ET(N)   =   t_N   =   z + z^n + z^{n^2} + ... + z^{n^6}       (n = N_7)   
        ES(N)   =   s_N   =   z + z^n + z^{n^2} + ... + z^{n^7}       (n = N_8)   
  
  For the two-argument versions of the functions, see Section NK (18.4-5).
  
    Example  
    gap> EY(5);
    E(5)+E(5)^4
    gap> EW(16,3); EW(17,2);
    0
    E(17)+E(17)^4+E(17)^13+E(17)^16
  
  
  
  18.4-4 EM, EL, ..., EJ
  
  EM( N[, d] )  function
  EL( N[, d] )  function
  EK( N[, d] )  function
  EJ( N[, d] )  function
  
  Let N be an integer, N > 2. We define (with z = exp(2 π i/N))
  
        EM(N)   =   m_N   =   z - z^n                       (n = N_2)   
        EL(N)   =   l_N   =   z - z^n + z^{n^2} - z^{n^3}   (n = N_4)   
        EK(N)   =   k_N   =   z - z^n + ... - z^{n^5}       (n = N_6)   
        EJ(N)   =   j_N   =   z - z^n + ... - z^{n^7}       (n = N_8)   
  
  For the two-argument versions of the functions, see Section NK (18.4-5).
  
  18.4-5 NK
  
  NK( N, k, d )  function
  
  Let  N_k^(d)  be  the  (d+1)-th  integer with multiplicative order exactly k
  modulo  N,  chosen  in the order of preference defined in Section 18.4-3; NK
  returns  N_k^(d);  if  there  is no integer with the required multiplicative
  order, NK returns fail.
  
  We write N_k = N_k^(0), N_k^' = N_k^(1), N_k^'' = N_k^(2) and so on.
  
  The algebraic numbers
  
  
  y_N^' = y_N^(1), y_N^'' = y_N^(2), ..., x_N^', x_N^'', ..., j_N^', j_N^'', ...
  
  are  obtained on replacing N_k in the definitions in the sections 18.4-3 and
  18.4-4 by N_k^', N_k^'', ...; they can be entered as
  
        EY(N,d)    =    y_N^(d)   
        EX(N,d)    =    x_N^(d)   
                  ...             
        EJ(N,d)    =    j_N^(d)   
  
  18.4-6 AtlasIrrationality
  
  AtlasIrrationality( irratname )  function
  
  Let  irratname  be  a  string that describes an irrational value as a linear
  combination  in  terms  of  the  atomic  irrationalities  introduced  in the
  sections 18.4-1, 18.4-2, 18.4-3, 18.4-4. These irrational values are defined
  in  [CCN+85, Chapter 6, Section 10], and the following description is mainly
  copied  from  there.  If  q_N  is  such  a  value (e.g. y_24^'') then linear
  combinations  of  algebraic  conjugates  of  q_N  are  abbreviated as in the
  following examples:
  
        2qN+3&5-4&7+&9   means   2 q_N + 3 q_N^{*5} - 4 q_N^{*7} + q_N^{*9}               
        4qN&3&5&7-3&4    means   4 (q_N + q_N^{*3} + q_N^{*5} + q_N^{*7}) - 3 q_N^{*11}   
        4qN*3&5+&7       means   4 (q_N^{*3} + q_N^{*5}) + q_N^{*7}                       
  
  To  explain the ampersand syntax in general we remark that &k is interpreted
  as  q_N^{*k}, where q_N is the most recently named atomic irrationality, and
  that the scope of any premultiplying coefficient is broken by a + or - sign,
  but  not  by & or *k. The algebraic conjugations indicated by the ampersands
  apply  directly  to  the atomic irrationality q_N, even when, as in the last
  example, q_N first appears with another conjugacy *k.
  
    Example  
    gap> AtlasIrrationality( "b7*3" );
    E(7)^3+E(7)^5+E(7)^6
    gap> AtlasIrrationality( "y'''24" );
    E(24)-E(24)^19
    gap> AtlasIrrationality( "-3y'''24*13&5" );
    3*E(8)-3*E(8)^3
    gap> AtlasIrrationality( "3y'''24*13-2&5" );
    -3*E(24)-2*E(24)^11+2*E(24)^17+3*E(24)^19
    gap> AtlasIrrationality( "3y'''24*13-&5" );
    -3*E(24)-E(24)^11+E(24)^17+3*E(24)^19
    gap> AtlasIrrationality( "3y'''24*13-4&5&7" );
    -7*E(24)-4*E(24)^11+4*E(24)^17+7*E(24)^19
    gap> AtlasIrrationality( "3y'''24&7" );
    6*E(24)-6*E(24)^19
  
  
  
  18.5 Galois Conjugacy of Cyclotomics
  
  18.5-1 GaloisCyc
  
  GaloisCyc( cyc, k )  operation
  GaloisCyc( list, k )  operation
  
  For  a  cyclotomic  cyc  and  an integer k, GaloisCyc returns the cyclotomic
  obtained by raising the roots of unity in the Zumbroich basis representation
  of  cyc to the k-th power. If k is coprime to the integer n, GaloisCyc( ., k
  )  acts as a Galois automorphism of the n-th cyclotomic field (see 60.4); to
  get the Galois automorphisms themselves, use GaloisGroup (58.3-1).
  
  The  complex  conjugate  of  cyc  is GaloisCyc( cyc, -1 ), which can also be
  computed using ComplexConjugate (18.5-2).
  
  For  a  list  or  matrix  list  of  cyclotomics,  GaloisCyc returns the list
  obtained by applying GaloisCyc to the entries of list.
  
  18.5-2 ComplexConjugate
  
  ComplexConjugate( z )  attribute
  RealPart( z )  attribute
  ImaginaryPart( z )  attribute
  
  For  a  cyclotomic  number  z,  ComplexConjugate returns GaloisCyc( z, -1 ),
  see GaloisCyc  (18.5-1). For a quaternion z = c_1 e + c_2 i + c_3 j + c_4 k,
  ComplexConjugate  returns  c_1  e  - c_2 i - c_3 j - c_4 k, see IsQuaternion
  (62.8-8).
  
  When  ComplexConjugate  is called with a list then the result is the list of
  return  values of ComplexConjugate for the list entries in the corresponding
  positions.
  
  When  ComplexConjugate  is  defined  for  an  object  z  then  RealPart  and
  ImaginaryPart   return   (z   +   ComplexConjugate(  z  ))  /  2  and  (z  -
  ComplexConjugate(   z   ))   /  2  i,  respectively,  where  i  denotes  the
  corresponding imaginary unit.
  
    Example  
    gap> GaloisCyc( E(5) + E(5)^4, 2 );
    E(5)^2+E(5)^3
    gap> GaloisCyc( E(5), -1 );           # the complex conjugate
    E(5)^4
    gap> GaloisCyc( E(5) + E(5)^4, -1 );  # this value is real
    E(5)+E(5)^4
    gap> GaloisCyc( E(15) + E(15)^4, 3 );
    E(5)+E(5)^4
    gap> ComplexConjugate( E(7) );
    E(7)^6
  
  
  18.5-3 StarCyc
  
  StarCyc( cyc )  function
  
  If  the  cyclotomic cyc is an irrational element of a quadratic extension of
  the  rationals  then StarCyc returns the unique Galois conjugate of cyc that
  is  different  from  cyc, otherwise fail is returned. In the first case, the
  return value is often called cyc* (see 71.13).
  
    Example  
    gap> StarCyc( EB(5) ); StarCyc( E(5) );
    E(5)^2+E(5)^3
    fail
  
  
  18.5-4 Quadratic
  
  Quadratic( cyc )  function
  
  Let  cyc be a cyclotomic integer that lies in a quadratic extension field of
  the  rationals. Then we have cyc= (a + b sqrt{n}) / d, for integers a, b, n,
  d,  such  that  d is either 1 or 2. In this case, Quadratic returns a record
  with  the  components  a,  b, root, d, ATLAS, and display; the values of the
  first  four  are  a,  b,  n,  and  d,  the ATLAS value is a (not necessarily
  shortest)  representation  of  cyc  in  terms  of  the Atlas irrationalities
  b_{|n|},  i_{|n|}, r_{|n|}, and the display value is a string that expresses
  cyc in GAP notation, corresponding to the value of the ATLAS component.
  
  If  cyc is not a cyclotomic integer or does not lie in a quadratic extension
  field of the rationals then fail is returned.
  
  If the denominator d is 2 then necessarily n is congruent to 1 modulo 4, and
  r_n,  i_n are not possible; we have cyc = x + y * EB( root ) with y = b, x =
  ( a + b ) / 2.
  
  If  d  =  1, we have the possibilities i_{|n|} for n < -1, a + b * i for n =
  -1, a + b * r_n for n > 0. Furthermore if n is congruent to 1 modulo 4, also
  cyc  =  (a+b) + 2 * b * b_{|n|} is possible; the shortest string of these is
  taken as the value for the component ATLAS.
  
    Example  
    gap> Quadratic( EB(5) ); Quadratic( EB(27) );
    rec( ATLAS := "b5", a := -1, b := 1, d := 2, 
      display := "(-1+Sqrt(5))/2", root := 5 )
    rec( ATLAS := "1+3b3", a := -1, b := 3, d := 2, 
      display := "(-1+3*Sqrt(-3))/2", root := -3 )
    gap> Quadratic(0); Quadratic( E(5) );
    rec( ATLAS := "0", a := 0, b := 0, d := 1, display := "0", root := 1 )
    fail
  
  
  18.5-5 GaloisMat
  
  GaloisMat( mat )  attribute
  
  Let mat be a matrix of cyclotomics. GaloisMat calculates the complete orbits
  under  the operation of the Galois group of the (irrational) entries of mat,
  and  the  permutations of rows corresponding to the generators of the Galois
  group.
  
  If  some rows of mat are identical, only the first one is considered for the
  permutations, and a warning will be printed.
  
  GaloisMat  returns  a  record  with  the  components  mat,  galoisfams,  and
  generators.
  
  mat
        a  list with initial segment being the rows of mat (not shallow copies
        of  these  rows); the list consists of full orbits under the action of
        the Galois group of the entries of mat defined above. The last rows in
        the  list are those not contained in mat but must be added in order to
        complete  the  orbits; so if the orbits were already complete, mat and
        mat have identical rows.
  
  galoisfams
        a  list that has the same length as the mat component, its entries are
        either 1, 0, -1, or lists.
  
        galoisfams[i] = 1
              means  that mat[i] consists of rationals, i.e., [ mat[i] ] forms
              an orbit;
  
        galoisfams[i] = -1
              means  that  mat[i]  contains unknowns (see Chapter 74); in this
              case  [  mat[i]  ]  is regarded as an orbit, too, even if mat[i]
              contains irrational entries;
  
        galoisfams[i] = [ l_1, l_2 ]
              (a  list) means that mat[i] is the first element of its orbit in
              mat,  l_1  is the list of positions of rows that form the orbit,
              and  l_2  is  the list of corresponding Galois automorphisms (as
              exponents,  not  as  functions);  so  we have mat[ l_1[j] ][k] =
              GaloisCyc( mat[i][k], l_2[j] );
  
        galoisfams[i] = 0
              means  that  mat[i]  is an element of a nontrivial orbit but not
              the first element of it.
  
  generators
        a  list of permutations generating the permutation group corresponding
        to the action of the Galois group on the rows of mat.
  
    Example  
    gap> GaloisMat( [ [ E(3), E(4) ] ] );
    rec( galoisfams := [ [ [ 1, 2, 3, 4 ], [ 1, 7, 5, 11 ] ], 0, 0, 0 ], 
      generators := [ (1,2)(3,4), (1,3)(2,4) ], 
      mat := [ [ E(3), E(4) ], [ E(3), -E(4) ], [ E(3)^2, E(4) ], 
          [ E(3)^2, -E(4) ] ] )
    gap> GaloisMat( [ [ 1, 1, 1 ], [ 1, E(3), E(3)^2 ] ] );
    rec( galoisfams := [ 1, [ [ 2, 3 ], [ 1, 2 ] ], 0 ], 
      generators := [ (2,3) ], 
      mat := [ [ 1, 1, 1 ], [ 1, E(3), E(3)^2 ], [ 1, E(3)^2, E(3) ] ] )
  
  
  18.5-6 RationalizedMat
  
  RationalizedMat( mat )  attribute
  
  returns  the  list  of  rationalized  rows of mat, which must be a matrix of
  cyclotomics.  This  is  the  set of sums over orbits under the action of the
  Galois  group  of  the  entries  of  mat  (see  GaloisMat  (18.5-5)), so the
  operation may be viewed as a kind of trace on the rows.
  
  Note that no two rows of mat should be equal.
  
    Example  
    gap> mat:= [ [ 1, 1, 1 ], [ 1, E(3), E(3)^2 ], [ 1, E(3)^2, E(3) ] ];;
    gap> RationalizedMat( mat );
    [ [ 1, 1, 1 ], [ 2, -1, -1 ] ]
  
  
  
  18.6 Internally Represented Cyclotomics
  
  The  implementation  of  an  internally represented cyclotomic is based on a
  list  of  length  equal  to  its  conductor.  This  means  that the internal
  representation  of  a cyclotomic does not refer to the smallest number field
  but  the smallest cyclotomic field containing it. The reason for this is the
  wish to reflect the natural embedding of two cyclotomic fields into a larger
  one  that  contains  both. With such embeddings, it is easy to construct the
  sum  or  the  product  of  two  arbitrary cyclotomics (in possibly different
  fields) as an element of a cyclotomic field.
  
  The  disadvantage  of  this approach is that the arithmetical operations are
  quite  expensive,  so  the  use of internally represented cyclotomics is not
  recommended  for  doing arithmetics over number fields, such as calculations
  with  matrices  of  cyclotomics.  But internally represented cyclotomics are
  good  enough  for  dealing  with  irrationalities  in  character tables (see
  chapter 71).
  
  For  the  representation  of  cyclotomics  one  has  to recall that the n-th
  cyclotomic  field  ℚ(e_n)  is  a  vector  space  of  dimension φ(n) over the
  rationals where φ denotes Euler's phi-function (see Phi (15.2-2)).
  
  A  special  integral basis of cyclotomic fields is chosen that allows one to
  easily  convert  arbitrary sums of roots of unity into the basis, as well as
  to  convert  a  cyclotomic  represented  w.r.t. the  basis into the smallest
  possible  cyclotomic  field.  This  basis is accessible in GAP, see 60.3 for
  more information and references.
  
  Note  that  the set of all n-th roots of unity is linearly dependent for n >
  1,  so  multiplication is not the multiplication of the group ring ℚ⟨ e_n ⟩;
  given  a  ℚ-basis  of  ℚ(e_n)  the result of the multiplication (computed as
  multiplication  of  polynomials in e_n, using (e_n)^n = 1) will be converted
  to the basis.
  
    Example  
    gap> E(5) * E(5)^2; ( E(5) + E(5)^4 ) * E(5)^2;
    E(5)^3
    E(5)+E(5)^3
    gap> ( E(5) + E(5)^4 ) * E(5);
    -E(5)-E(5)^3-E(5)^4
  
  
  An  internally  represented cyclotomic is always represented in the smallest
  cyclotomic  field  it  is  contained  in.  The  internal  coefficients  list
  coincides   with   the   external  representation  returned  by  ExtRepOfObj
  (18.1-12).
  
  To  avoid calculations becoming unintentionally very long, or consuming very
  large  amounts  of  memory,  there is a limit on the conductor of internally
  represented  cyclotomics,  by default set to one million. This can be raised
  (although not lowered) using SetCyclotomicsLimit (18.6-1) and accessed using
  GetCyclotomicsLimit (18.6-1). The maximum value of the limit is 2^28-1 on 32
  bit  systems,  and 2^32-1 on 64 bit systems. So the maximal cyclotomic field
  implemented in GAP is not really the field ℚ^ab.
  
  It  should  be emphasized that one disadvantage of representing a cyclotomic
  in  the  smallest  cyclotomic  field (and not in the smallest field) is that
  arithmetic  operations  in  a  fixed  small  extension field of the rational
  number  field are comparatively expensive. For example, take a prime integer
  p  and  suppose  that  we  want  to  work with a matrix group over the field
  ℚ(sqrt{p}).  Then  each  matrix  entry  could  be  described by two rational
  coefficients,  whereas  the  representation in the smallest cyclotomic field
  requires  p-1  rational coefficients for each entry. So it is worth thinking
  about using elements in a field constructed with AlgebraicExtension (67.1-1)
  when natural embeddings of cyclotomic fields are not needed.
  
  18.6-1 SetCyclotomicsLimit
  
  SetCyclotomicsLimit( newlimit )  function
  GetCyclotomicsLimit(  )  function
  
  GetCyclotomicsLimit  returns  the  current limit on conductors of internally
  represented cyclotomic numbers
  
  SetCyclotomicsLimit  can  be  called  to increase the limit on conductors of
  internally  represented  cyclotomic  numbers.  Note  that computing in large
  cyclotomic   fields   using   this  representation  can  be  both  slow  and
  memory-consuming, and that other approaches may be better for some problems.
  See 18.6.