<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %A  cyclotom.xml                GAP documentation               Thomas Breuer -->
<!-- %A                                                           Alexander Hulpke -->
<!-- %% -->
<!-- %% -->
<!-- %Y  (C) 1998 School Math and Comp. Sci., University of St Andrews, Scotland -->
<!-- %Y  Copyright (C) 2002 The GAP Group -->
<!-- %% -->
<!-- %%  This file is being maintained by Thomas Breuer. -->
<!-- %%  Please do not make any changes without consulting him. -->
<!-- %%  (This holds also for minor changes such as the removal of whitespace or -->
<!-- %%  the correction of typos.) -->
<!-- %% -->
<Chapter Label="Cyclotomic Numbers">
<Heading>Cyclotomic Numbers</Heading>

<Index Subkey="cyclotomic">type</Index>
<Index>irrationalities</Index>
<Index>cyclotomic field elements</Index>

&GAP; admits computations in abelian extension fields of the rational
number field <M>&QQ;</M>,
that is fields with abelian Galois group over <M>&QQ;</M>.
These fields are subfields of <E>cyclotomic fields</E> <M>&QQ;(e_n)</M>
where <M>e_n = \exp(2 \pi i/n)</M> is a primitive complex <M>n</M>-th root of
unity.
The elements of these fields are called <E>cyclotomics</E>.
<P/>
Information concerning operations for domains of cyclotomics,
for example certain integral bases of fields of cyclotomics,
can be found in Chapter&nbsp;<Ref Chap="Abelian Number Fields"/>.
For more general operations that take a field extension as a
&ndash;possibly optional&ndash; argument,
e.g., <Ref Attr="Trace" Label="for a field element"/> or
<Ref Oper="Coefficients"/>,
see Chapter&nbsp;<Ref Chap="Fields and Division Rings"/>.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Operations for Cyclotomics">
<Heading>Operations for Cyclotomics</Heading>

<#Include Label="E">
<#Include Label="Cyclotomics">
<#Include Label="IsCyclotomic">
<#Include Label="IsIntegralCyclotomic">
<#Include Label="Int:cyclotomics">
<#Include Label="String:cyclotomics">
<#Include Label="Conductor">
<#Include Label="AbsoluteValue">
<#Include Label="RoundCyc">
<#Include Label="CoeffsCyc">
<#Include Label="DenominatorCyc">
<#Include Label="ExtRepOfObj:cyclotomics">
<#Include Label="DescriptionOfRootOfUnity">
<#Include Label="IsGaussInt">
<#Include Label="IsGaussRat">
<#Include Label="DefaultField:cyclotomics">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Infinity">
<Heading>Infinity and negative Infinity</Heading>

<#Include Label="IsInfinity">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Comparisons of Cyclotomics">
<Heading>Comparisons of Cyclotomics</Heading>

<Index Subkey="for cyclotomics">operators</Index>
To compare cyclotomics, the operators <C>&lt;</C>, <C>&lt;=</C>, <C>=</C>,
<C>>=</C>, <C>></C>, and <C>&lt;></C> can  be used,
the result will be <K>true</K> if the first operand is
smaller, smaller or equal, equal, larger or equal, larger, or unequal,
respectively, and <K>false</K> otherwise.
<P/>
Cyclotomics are ordered as follows:
The relation between rationals is the natural one,
rationals are smaller than irrational cyclotomics,
and <Ref Var="infinity"/> is the largest cyclotomic.
For two irrational cyclotomics with different conductors
(see <Ref Attr="Conductor" Label="for a cyclotomic"/>),
the one with smaller conductor is regarded as smaller.
Two irrational cyclotomics with same conductor are compared via their
external representation
(see <Ref Meth="ExtRepOfObj" Label="for a cyclotomic"/>).
<P/>
For comparisons of cyclotomics and other &GAP; objects,
see Section&nbsp;<Ref Sect="Comparisons"/>.
<P/>
<Example><![CDATA[
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
]]></Example>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="ATLAS Irrationalities">
<Heading>ATLAS Irrationalities</Heading>

<Index>atomic irrationalities</Index>
<#Include Label="EB">
<#Include Label="EI">
<#Include Label="EY">
<#Include Label="EM">
<#Include Label="NK">
<#Include Label="AtlasIrrationality">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Galois Conjugacy of Cyclotomics">
<Heading>Galois Conjugacy of Cyclotomics</Heading>

<#Include Label="GaloisCyc">
<#Include Label="ComplexConjugate">
<#Include Label="StarCyc">
<#Include Label="Quadratic">
<#Include Label="GaloisMat">
<#Include Label="RationalizedMat">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Internally Represented Cyclotomics">
<Heading>Internally Represented Cyclotomics</Heading>

The implementation of an <E>internally represented cyclotomic</E> is based on
a list of length equal to its conductor.
This means that the internal representation of a cyclotomic does <E>not</E>
refer to the smallest number field but the smallest <E>cyclotomic</E> 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.
<P/>
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&nbsp;<Ref Chap="Character Tables"/>).
<P/>
For the representation of cyclotomics one has to recall that the
<M>n</M>-th cyclotomic field <M>&QQ;(e_n)</M> is a vector space of dimension
<M>\varphi(n)</M> over the rationals where <M>\varphi</M> denotes Euler's
phi-function (see&nbsp;<Ref Oper="Phi"/>).
<P/>
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.&nbsp;the basis
into the smallest possible cyclotomic field.
This basis is accessible in &GAP;,
see&nbsp;<Ref Sect="Integral Bases of Abelian Number Fields"/>
for more information and references.
<P/>
Note that the set of all <M>n</M>-th roots of unity is linearly dependent
for <M>n > 1</M>, so multiplication is <E>not</E> the multiplication
of the group ring <M>&QQ;\langle e_n \rangle</M>;
given a <M>&QQ;</M>-basis of <M>&QQ;(e_n)</M> the result of the multiplication
(computed as multiplication of polynomials in <M>e_n</M>,
using <M>(e_n)^n = 1</M>) will be converted to the basis.
<P/>
<Example><![CDATA[
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
]]></Example>
<P/>
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 <Ref Meth="ExtRepOfObj" Label="for a cyclotomic"/>.
<P/>
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
<Ref Func="SetCyclotomicsLimit"/> and
accessed using <Ref Func="GetCyclotomicsLimit"/>.
The maximum value of the limit is <M>2^{28}-1</M> on <M>32</M> bit systems,
and <M>2^{32}-1</M> on <M>64</M> bit systems.
So the maximal cyclotomic field implemented in &GAP; is not really
the field <M>&QQ;^{ab}</M>.
<P/>
It should be emphasized that one disadvantage of representing a cyclotomic in
the smallest <E>cyclotomic</E> 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 <M>p</M> and suppose that we want to work
with a matrix group over the field <M>&QQ;(\sqrt{{p}})</M>.
Then each matrix entry could be described by two rational coefficients,
whereas the representation in the smallest cyclotomic field requires
<M>p-1</M> rational coefficients for each entry.
So it is worth thinking about using elements in a field constructed with
<Ref Oper="AlgebraicExtension"/> when natural embeddings
of cyclotomic fields are not needed.

<!-- % show an example? -->
<ManSection>
<Func Name="SetCyclotomicsLimit" Arg="newlimit"/>
<Func Name="GetCyclotomicsLimit" Arg=""/>
<Description>
<Ref Func="GetCyclotomicsLimit"/> returns the current limit on
conductors of internally represented cyclotomic numbers
<P/>
<Ref Func="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
<Ref Sect="Internally Represented Cyclotomics"/>.
</Description>
</ManSection>

</Section>
</Chapter>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %E -->