<!-- #################################################################### -->
<!-- ##                                                                ## -->
<!-- ##  databases.xml         RCWA documentation         Stefan Kohl  ## -->
<!-- ##                                                                ## -->
<!-- #################################################################### -->

<Chapter Label="ch:Databases">
<Heading>
  Databases of Residue-Class-Wise Affine Groups and -Mappings
</Heading>

The &RCWA; package contains a number of databases of rcwa groups and rcwa
mappings. They can be loaded into a &GAP; session by the functions described
in this chapter.

<!-- #################################################################### -->

<Section Label="sec:Examples">
<Heading>The collection of examples</Heading>

<ManSection>
  <Func Name="LoadRCWAExamples" Arg = ""/>
  <Returns>
    a record containing a collection of examples of rcwa groups and
    -mappings, as stored in the file <F>pkg/rcwa/examples/examples.g</F>. 
  </Returns>
  <Description>
    The components of the record returned by this function are records
    which contain the individual groups and mappings.
    A detailed description of some of the examples can be found in
    Chapter&nbsp;<Ref Label="ch:Examples"/>.
<Example>
<![CDATA[
gap> examples := LoadRCWAExamples();;                                 
gap> Set(RecNames(examples));
[ "AbelianGroupOverPolynomialRing", "Basics", "CT3Z", "CTPZ", 
  "CheckingForSolvability", "ClassSwitches", 
  "ClassTranspositionProducts", "ClassTranspositionsAsCommutators", 
  "CollatzFactorizationOld", "CollatzMapping", "CollatzlikePerms", 
  "CoprimeMultDiv", "F2_PSL2Z", "Farkas", "FiniteQuotients", 
  "FiniteVsDenseCycles", "GF2xFiniteCycles", "GrigorchukQuotients", 
  "Hexagon", "HicksMullenYucasZavislak", "HigmanThompson", 
  "LongCyclesOfPrimeLength", "MatthewsLeigh", 
  "MaybeInfinitelyPresentedGroup", "ModuliOfPowers", 
  "OddNumberOfGens_FiniteOrder", "Semilocals", 
  "SlowlyContractingMappings", "Syl3_S9", "SymmetrizingCollatzTree", 
  "TameGroupByCommsOfWildPerms", "Venturini", "ZxZ" ]
gap> AssignGlobals(examples.ZxZ);
The following global variables have been assigned:
[ "R", "SigmaT", "SigmaTm", "Sigma_T", "T2", "a", "b", "commT_Tm", 
  "hyperbolic", "reflection", "reflection1", "reflection2", "switch", 
  "transvection", "twice", "twice1", "twice2" ]
gap> a*b = Sigma_T;
true
gap> Display(Sigma_T);

Rcwa mapping of Z^2 with modulus (1,0)Z+(0,6)Z

            /
            | (2m+1,(3n+1)/2) if (m,n) in (0,1)+(1,0)Z+(0,2)Z
            | (m,n/2)         if (m,n) in (0,0)+(1,0)Z+(0,6)Z U 
 (m,n) |-> <                              (0,2)+(1,0)Z+(0,6)Z
            | (2m,n/2)        if (m,n) in (0,4)+(1,0)Z+(0,6)Z
            |
            \
]]>
</Example>
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

<Section Label="sec:DatabasesOfRcwaGroups">
<Heading>Databases of rcwa groups</Heading>

<ManSection>
  <Func Name="LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions"
        Arg = "" Label = "small database"/>
  <Returns>
    a record containing a database of all groups generated by
    3 class transpositions which interchange residue classes with
    moduli <M>\leq 6</M>.
  </Returns>
  <Description>
    The record presently has the components <C>grps</C>
    (the list of the 52394 groups -- 21948 finite and 30446 infinite ones),
    <C>sizes</C> (the list of group orders), <C>mods</C> (the list of
    moduli of the groups), <C>trsstatus</C> (lists what is known about
    whether the groups are transitive on the nonnegative integers in their
    support), <C>cts</C> (the list of all 69 class transpositions which
    interchange residue classes with moduli <M>\leq 6</M>), and possibly
    further which are not described here.
    For all integers <C>i</C> from 1 to 52394 it holds that
    <C>Size(grps[i]) = sizes[i]</C> and that
    <C>Modulus(grps[i]) = mods[i]</C>. Similarly, <C>trsstatus[i]</C>
    describes what is known about whether the group <C>grps[i]</C> acts
    transitively on the set of nonnegative integers in its support --
    for many of the groups this is a description of how the computation
    failed. <P/>

    The group <C>grps[44132]</C> might be called the <Q>Collatz group</Q>
    or the <Q><M>3n+1</M> - group</Q> -- its action on the set of positive
    integers which are not divisible by 6 is transitive if and only if
    the <M>3n+1</M> conjecture is true. <P/>

    Note that the contents of this database are not <Q>set in stone</Q>,
    and are likely to change in coming releases. Also note that the database
    presently contains an entry for every unordered triple of distinct
    class transpositions in <C>cts</C>, which means that it contains
    multiple copies of equal groups. For the future it is planned to
    include information on which groups are equal and which are isomorphic,
    but in particular for the infinite groups this task seems to be
    algorithmically hard.
<Example>
<![CDATA[
gap> data := LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions();;
gap> ViewString(data.grps[44132]); # the "3n+1 group"
"<(2(3),4(6)),(1(3),2(6)),(1(2),4(6))>"
gap> data.trsstatus[44132]; # deciding this would solve the 3n+1 problem
"exceeded memory bound"
gap> Length(Set(data.sizes));
1066
gap> Maximum(Filtered(data.sizes,IsInt));
7165033589793852697531456980706732548435609645091822296777976465116824959\
2135499174617837911754921014138184155204934961004073853323458315539461543\
4480515260818409913846161473536000000000000000000000000000000000000000000\
000000
gap> Positions(data.sizes,last);
[ 33814, 36548 ]
gap> List(data.grps{last},ViewString);
[ "<(1(5),4(5)),(0(3),1(6)),(3(4),0(6))>", 
  "<(0(5),3(5)),(2(3),4(6)),(0(4),5(6))>" ]
gap> Collected(data.mods);
[ [ 0, 30446 ], [ 3, 1 ], [ 4, 37 ], [ 5, 120 ], [ 6, 1450 ], [ 8, 18 ], 
  [ 10, 45 ], [ 12, 3143 ], [ 15, 165 ], [ 18, 484 ], [ 20, 528 ], 
  [ 24, 1339 ], [ 30, 2751 ], [ 36, 2064 ], [ 40, 26 ], [ 48, 515 ], 
  [ 60, 2322 ], [ 72, 2054 ], [ 80, 44 ], [ 90, 108 ], [ 96, 108 ], 
  [ 108, 114 ], [ 120, 782 ], [ 144, 310 ], [ 160, 26 ], [ 180, 206 ], 
  [ 192, 6 ], [ 216, 72 ], [ 240, 304 ], [ 270, 228 ], [ 288, 14 ], 
  [ 360, 84 ], [ 432, 36 ], [ 480, 218 ], [ 540, 18 ], [ 720, 120 ], 
  [ 810, 112 ], [ 864, 8 ], [ 960, 94 ], [ 1080, 488 ], [ 1620, 44 ], 
  [ 1920, 38 ], [ 2160, 506 ], [ 3240, 34 ], [ 3840, 12 ], 
  [ 4320, 218 ], [ 4860, 16 ], [ 6480, 282 ], [ 7680, 10 ], 
  [ 8640, 16 ], [ 12960, 120 ], [ 14580, 2 ], [ 25920, 34 ], 
  [ 30720, 2 ], [ 38880, 12 ], [ 51840, 8 ], [ 77760, 32 ] ]
gap> Collected(data.trsstatus);
[ [ "> 1 orbit (mod m)", 593 ], 
  [ "Mod(U DecreasingOn) exceeded <maxmod>", 23 ], 
  [ "U DecreasingOn stable and exceeded memory bound", 11 ], 
  [ "U DecreasingOn stable for <maxeq> steps", 5757 ], 
  [ "exceeded memory bound", 497 ], [ "finite", 21948 ], 
  [ "intransitive, but finitely many orbits", 8 ], 
  [ "seemingly only finite orbits (long)", 1227 ], 
  [ "seemingly only finite orbits (medium)", 2501 ], 
  [ "seemingly only finite orbits (short)", 4816 ], 
  [ "seemingly only finite orbits (very long)", 230 ], 
  [ "seemingly only finite orbits (very long, very unclear)", 76 ], 
  [ "seemingly only finite orbits (very short)", 208 ], 
  [ "there are infinite orbits which have exponential sphere size growth"
        , 2934 ], 
  [ "there are infinite orbits which have linear sphere size growth", 
      10881 ],
  [ "there are infinite orbits which have unclear sphere size growth", 
      86 ], [ "transitive", 558 ], 
  [ "transitive up to one finite orbit", 40 ] ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Func Name="LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions"
        Arg = "max_m" Label = "small or large database"/>
  <Returns>
    a record containing a database of all groups generated by
    3 class transpositions which interchange residue classes with
    moduli less than or equal to <A>max_m</A>, where <A>max_m</A>
    is either 6 or&nbsp;9.
  </Returns>
  <Description>
    If <A>max_m</A> is 6, this is equivalent to the call of the function
    without argument described above. If <A>max_m</A> is 9, the function
    returns a record with components <C>cts</C> (a list of all class
    transpositions which interchange residue classes with moduli
    <M>\leq 9</M>), <C>mods</C> (the list of moduli of the groups, i.e.
    <C>Mod(Group(cts{[i,j,k]})) = mods[i][j][k]</C>, for all triples
    <M>(i,j,k)</M> of positive integers which satisfy
    <M>264 \geq i > j > k</M>), <C>partlengths</C> (the list of shortest
    respected partitions of the groups, i.e.
    <C>Length(RespectedPartition(Group(cts{[i,j,k]})))</C> <C>=</C>
    <C>partlengths[i][j][k]</C>), and <C>sizes</C> (the list of orders
    of the groups, i.e. <C>Size(Group(cts{[i,j,k]}))</C> <C>=</C>
    <C>sizes[i][j][k]</C>).
  </Description>
</ManSection>

<ManSection>
  <Func Name="LoadDatabaseOfGroupsGeneratedBy4ClassTranspositions"
        Arg = ""/>
  <Returns>
    a record containing a database of all groups generated by
    4 class transpositions which interchange residue classes with
    moduli <M>\leq 6</M> for which all subgroups generated by
    3 out of the 4 generators are finite. 
  </Returns>
  <Description>
    The record presently has the components <C>grps4_3finite</C>
    (the list of all 140947 groups in the database),
    <C>sizes4</C> (the list of group orders), <C>mods4</C> (the list of
    moduli of the groups),
    <C>conjugacyclasses4cts</C> (a list of lists of positions of groups
    in the list <C>grps4_3finite</C> which are already known to be
    conjugate), <C>grps4_3finite_reps</C> (tentative conjugacy class
    representatives from the list <C>grps4_3finite</C> --
    <E>tentative</E> in the sense that likely some of the groups
    in the list are still conjugate), <C>cts</C> (the list of all
    69 class transpositions which interchange residue classes with
    moduli <M>\leq 6</M>), <C>grps4_3finitepos</C> (the list
    obtained from <C>grps4_3finite</C> by replacing every group
    generator by its position in the list <C>cts</C>,
    and possibly further which are not described here.
    For all integers <C>i</C> from 1 to 140947 it holds that
    <C>Size(grps4_3finite[i]) = sizes4[i]</C> and that
    <C>Modulus(grps4_3finite[i]) = mods4[i]</C>.

    Note that the contents of this database are not <Q>set in stone</Q>,
    and are likely to change in coming releases. Also note that the
    database contains an entry for every suitable unordered 4-tuple of
    distinct class transpositions in <C>cts</C>, which means that it
    contains multiple copies of equal groups. 
<Example>
<![CDATA[
gap> data := LoadDatabaseOfGroupsGeneratedBy4ClassTranspositions();;
gap> AssignGlobals(data);
The following global variables have been assigned:
[ "conjugacyclasses4cts", "cts", "grps4_3finite", "grps4_3finite_reps", 
  "grps4_3finitepos", "mods4", "sizes4", "sizes4pos", "sizes4set" ]
gap> Length(grps4_3finite);
140947
gap> Length(sizes4);
140947
gap> Size(grps4_3finite[1]);
518400
gap> sizes4[1];
518400
gap> Maximum(Filtered(sizes4,IsInt));
<integer 420...000 (3852 digits)>
gap> Modulus(grps4_3finite[1]);
12
gap> mods4[1];
12
gap> Length(Set(sizes4));
7339
gap> Length(Set(mods4));
91
gap> Set(mods4);
[ 0, 4, 5, 6, 8, 10, 12, 15, 18, 20, 24, 30, 36, 40, 48, 60, 72, 80, 90, 
  96, 108, 120, 144, 160, 180, 192, 216, 240, 270, 288, 320, 360, 384, 
  432, 480, 540, 576, 720, 810, 864, 960, 1080, 1440, 1620, 1728, 1920, 
  2160, 2430, 2592, 2880, 3240, 3840, 4320, 4860, 5760, 6480, 7680, 
  8640, 9720, 10368, 12960, 14580, 15360, 17280, 19440, 25920, 30720, 
  34560, 38880, 43740, 51840, 61440, 69120, 77760, 103680, 116640, 
  122880, 155520, 207360, 233280, 311040, 349920, 414720, 466560, 
  622080, 933120, 1244160, 1658880, 1866240, 5598720, 33592320 ]
gap> conjugacyclasses4cts{[1..4]};
[ [ 1, 23, 563, 867 ], [ 2, 859 ], [ 3, 622 ], [ 4, 16, 868, 873 ] ]
gap> grps4_3finite[1] = grps4_3finite[23];
true
gap> grps4_3finite[4] = grps4_3finite[16];
false
gap> Size(grps4_3finite[4]);
44696597299200000
gap> Size(grps4_3finite[16]);
44696597299200000
gap> RepresentativeAction(RCWA(Integers),grps4_3finite[4],
>                                        grps4_3finite[16],OnPoints);
( 0(30), 6(30), 12(30) ) ( 1(30), 7(30), 13(30) ) ( 2(30), 8(30), 14(30) \
) ( 3(30), 9(30), 15(30) ) ( 4(30), 10(30), 16(30) ) ( 5(30), 11(30), 17(\
30) )
]]>
</Example>
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

<Section Label="sec:DatabasesOfRcwaMappings">
<Heading>Databases of rcwa mappings</Heading>

<ManSection>
  <Func Name="LoadDatabaseOfProductsOf2ClassTranspositions"
        Arg = ""/>
  <Returns>
    a record containing a database of all products of 2 class
    transpositions which interchange residue classes with
    moduli <M>\leq 6</M>.
  </Returns>
  <Description>
    There are 69 class transpositions which interchange residue
    classes with moduli <M>\leq 6</M>, thus there is a total of
    <M>(69 \cdot 68)/2 = 2346</M> unordered pairs of distinct
    such class transpositions. Looking at intersection-
    and subset relations between the 4 involved residue classes,
    we can distinguish 17 different <Q>intersection types</Q>
    (or 18, together with the trivial case of equal class transpositions).
    The intersection type does not fully determine the cycle
    structure of the product. -- In total, we can distinguish
    88 different cycle types of products of 2 class transpositions
    which interchange residue classes with moduli <M>\leq 6</M>. <P/>

    The components of the returned record are a list <C>CTPairs</C> 
    of all 2346 pairs of distinct class transpositions which interchange
    residue classes with moduli <M>\leq 6</M>, functions
    <C>CTPairsIntersectionTypes</C>, <C>CTPairIntersectionType</C> and
    <C>CTPairProductType</C> as well as data lists
    <C>CTPairsProductClassification</C> and <C>CTPairsProductType</C>.
    -- For a precise description see the file
    <F>pkg/rcwa/data/ctprodclass.g</F>.
<Example>
<![CDATA[
gap> data := LoadDatabaseOfProductsOf2ClassTranspositions();;
gap> Set(RecNames(data));
[ "CTPairIntersectionType", "CTPairProductType", "CTPairs", 
  "CTPairsIntersectionTypes", "CTPairsProductClassification", 
  "CTPairsProductType", "CTProds12", "CTProds32", "OrdersMatrix" ]
gap> Length(data.CTPairs);
2346
gap> Collected(List(data.CTPairsProductType,l->l[2])); # order statistics
[ [ 2, 165 ], [ 3, 255 ], [ 4, 173 ], [ 6, 693 ], [ 10, 2 ], 
  [ 12, 345 ], [ 15, 4 ], [ 20, 10 ], [ 30, 120 ], [ 60, 44 ], 
  [ infinity, 535 ] ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Func Name="LoadDatabaseOfNonbalancedProductsOfClassTranspositions"
        Arg = ""/>
  <Returns>
    a record containing a database of products of class transpositions
    which are not balanced.
  </Returns>
  <Description>
    This database contains a list of the 24 pairs of class
    transpositions which interchange residue classes with moduli
    <M>\leq 6</M> and whose product is not balanced, as well as a list
    of all 36 essentially distinct triples of such class transpositions
    whose product has coprime multiplier and divisor.
<Example>
<![CDATA[
gap> data := LoadDatabaseOfNonbalancedProductsOfClassTranspositions();;
gap> Set(RecNames(data));
[ "PairsOfCTsWhoseProductIsNotBalanced", 
  "TriplesOfCTsWhoseProductHasCoprimeMultiplierAndDivisor" ]
gap> List(data.PairsOfCTsWhoseProductIsNotBalanced,
>         p->List(p,TransposedClasses));
[ [ [ 1(2), 2(4) ], [ 2(4), 3(6) ] ], [ [ 1(2), 2(4) ], [ 2(4), 5(6) ] ],
  [ [ 1(2), 2(4) ], [ 2(4), 1(6) ] ], [ [ 1(2), 0(4) ], [ 0(4), 1(6) ] ],
  [ [ 1(2), 0(4) ], [ 0(4), 3(6) ] ], [ [ 1(2), 0(4) ], [ 0(4), 5(6) ] ],
  [ [ 0(2), 1(4) ], [ 1(4), 2(6) ] ], [ [ 0(2), 1(4) ], [ 1(4), 4(6) ] ],
  [ [ 0(2), 1(4) ], [ 1(4), 0(6) ] ], [ [ 0(2), 3(4) ], [ 3(4), 4(6) ] ],
  [ [ 0(2), 3(4) ], [ 3(4), 2(6) ] ], [ [ 0(2), 3(4) ], [ 3(4), 0(6) ] ],
  [ [ 1(2), 2(6) ], [ 3(4), 2(6) ] ], [ [ 1(2), 2(6) ], [ 1(4), 2(6) ] ],
  [ [ 1(2), 4(6) ], [ 3(4), 4(6) ] ], [ [ 1(2), 4(6) ], [ 1(4), 4(6) ] ],
  [ [ 1(2), 0(6) ], [ 1(4), 0(6) ] ], [ [ 1(2), 0(6) ], [ 3(4), 0(6) ] ],
  [ [ 0(2), 1(6) ], [ 2(4), 1(6) ] ], [ [ 0(2), 1(6) ], [ 0(4), 1(6) ] ],
  [ [ 0(2), 3(6) ], [ 2(4), 3(6) ] ], [ [ 0(2), 3(6) ], [ 0(4), 3(6) ] ],
  [ [ 0(2), 5(6) ], [ 2(4), 5(6) ] ], [ [ 0(2), 5(6) ], [ 0(4), 5(6) ] ] ]
]]>
</Example>
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

</Chapter>

<!-- #################################################################### -->
