rcwagrp.xml

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

<Chapter Label="ch:RcwaGroups">
<Heading>Residue-Class-Wise Affine Groups</Heading>

<Ignore Remark="settings for the example tester">
<Example>
<![CDATA[
gap> SizeScreen([75,24]);;
gap> SetAssertionLevel(0);
]]>
</Example>
</Ignore>

In this chapter, we describe how to construct residue-class-wise affine
groups and how to compute with them.

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

<Section Label="sec:ContructingRcwaGroups">
<Heading>Constructing residue-class-wise affine groups</Heading>

<Index Key="Group"><C>Group</C></Index>
<Index Key="GroupByGenerators"><C>GroupByGenerators</C></Index>
<Index Key="GroupWithGenerators"><C>GroupWithGenerators</C></Index>

As any other groups in &GAP;, residue-class-wise affine (rcwa-) groups
can be constructed by <C>Group</C>, <C>GroupByGenerators</C> or
<C>GroupWithGenerators</C>.

<Example>
<![CDATA[
gap> G := Group(ClassTransposition(0,2,1,4),ClassShift(0,5));
<rcwa group over Z with 2 generators>
gap> IsTame(G); Size(G); IsSolvable(G); IsPerfect(G);
true
infinity
false
false
]]>
</Example>

An rcwa group isomorphic to a given group can be obtained by taking
the image of a faithful rcwa representation:

<ManSection>
  <Attr Name="IsomorphismRcwaGroup"
        Arg="G, R" Label="for a group, over a given ring"/>
  <Attr Name="IsomorphismRcwaGroup"
        Arg="G" Label="for a group"/>
  <Returns>
    a monomorphism from the group <A>G</A> to&nbsp;RCWA(<A>R</A>)
    or to&nbsp;RCWA(&ZZ;), respectively.
  </Returns>
  <Description>
    The best-supported case is <A>R</A> = &ZZ;.
    Currently there are methods available for finite groups, for
    free products of finite groups and for free groups. The method for
    free products of finite groups uses the Table-Tennis Lemma
    (cf. e.g. Section&nbsp;II.B. in&nbsp;<Cite Key="LaHarpe00"/>), and the
    method for free groups uses an adaptation of the construction given
    on page&nbsp;27 in&nbsp;<Cite Key="LaHarpe00"/> from PSL(2,&CC;)
    to RCWA(&ZZ;). <P/>
<Example>
<![CDATA[
gap> F := FreeProduct(Group((1,2)(3,4),(1,3)(2,4)),Group((1,2,3)),
>                     SymmetricGroup(3));
<fp group on the generators [ f1, f2, f3, f4, f5 ]>
gap> IsomorphismRcwaGroup(F);
[ f1, f2, f3, f4, f5 ] -> [ <rcwa permutation of Z with modulus 12>,
  <rcwa permutation of Z with modulus 24>,
  <rcwa permutation of Z with modulus 12>,
  <rcwa permutation of Z with modulus 72>,
  <rcwa permutation of Z with modulus 36> ]
gap> IsomorphismRcwaGroup(FreeGroup(2));
[ f1, f2 ] -> [ <wild rcwa permutation of Z with modulus 8>,
  <wild rcwa permutation of Z with modulus 8> ]
gap> F2 := Image(last);
<wild rcwa group over Z with 2 generators>
]]>
</Example>
  </Description>
</ManSection>

Further, new rcwa groups can be constructed from given ones by
taking direct products and by taking wreath products with finite
groups or with the infinite cyclic group:

<ManSection>
  <Meth Name="DirectProduct"
        Arg="G1, G2, ..." Label="for rcwa groups over Z"/>
  <Returns>
    an rcwa group isomorphic to the direct product of the rcwa groups
    over&nbsp;&ZZ; given as arguments.
  </Returns>
  <Description>
    There is certainly no unique or canonical way to embed a direct
    product of rcwa groups into RCWA(&ZZ;). 
    This method chooses to embed the groups <A>G1</A>, <A>G2</A>,
    <A>G3</A>&nbsp;... via restrictions by <M>n \mapsto mn</M>,
    <M>n \mapsto mn+1</M>, <M>n \mapsto mn+2</M>&nbsp;...
    (<M>\rightarrow</M>&nbsp;<Ref Oper="Restriction"
    Label="of an rcwa group, by an injective rcwa mapping"/>),
    where <M>m</M> denotes the number of groups given as arguments.
<Example>
<![CDATA[
gap> F2 := Image(IsomorphismRcwaGroup(FreeGroup(2)));;
gap> F2xF2 := DirectProduct(F2,F2);
<wild rcwa group over Z with 4 generators>
gap> Image(Projection(F2xF2,1)) = F2;
true
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Heading>
    WreathProduct
    (for an rcwa group over Z, with a permutation group or (&ZZ;,+))
  </Heading>
  <Meth Name="WreathProduct" Arg="G, P"
        Label="for an rcwa group over Z and a permutation group"/>
  <Meth Name="WreathProduct" Arg="G, Z"
        Label="for an rcwa group over Z and the infinite cyclic group"/>
  <Returns>
    an rcwa group isomorphic to the wreath product of the rcwa
    group&nbsp;<A>G</A> over&nbsp;&ZZ; with the finite permutation
    group&nbsp;<A>P</A> or with the infinite cyclic group&nbsp;<A>Z</A>,
    respectively.
  </Returns>
  <Description>
    The first-mentioned method embeds the <C>NrMovedPoints(<A>P</A>)</C>th
    direct power of&nbsp;<A>G</A> using the method for <C>DirectProduct</C>,
    and lets the permutation group&nbsp;<A>P</A> act naturally on the set of
    residue classes modulo <C>NrMovedPoints(<A>P</A>)</C>.
    The second-mentioned method restricts
    (<M>\rightarrow</M>&nbsp;<Ref Oper="Restriction"
    Label="of an rcwa group, by an injective rcwa mapping"/>)
    the group&nbsp;<A>G</A> to the residue class&nbsp;3(4), and maps the
    generator of the infinite cyclic group&nbsp;<A>Z</A>
    to <C>ClassTransposition(0,2,1,2) * ClassTransposition(0,2,1,4)</C>.
<Example>
<![CDATA[
gap> F2 := Image(IsomorphismRcwaGroup(FreeGroup(2)));;
gap> F2wrA5 := WreathProduct(F2,AlternatingGroup(5));;
gap> Embedding(F2wrA5,1);
[ <wild rcwa permutation of Z with modulus 8>,
  <wild rcwa permutation of Z with modulus 8> ] ->
[ <wild rcwa permutation of Z with modulus 40>,
  <wild rcwa permutation of Z with modulus 40> ]
gap> Embedding(F2wrA5,2);
[ (1,2,3,4,5), (3,4,5) ] -> [ ( 0(5), 1(5), 2(5), 3(5), 4(5) ), 
  ( 2(5), 3(5), 4(5) ) ]
gap> ZwrZ := WreathProduct(Group(ClassShift(0,1)),Group(ClassShift(0,1)));
<wild rcwa group over Z with 2 generators>
gap> Embedding(ZwrZ,1);
[ ClassShift( Z ) ] ->
[ <tame rcwa permutation of Z with modulus 4, of order infinity> ]
gap> Embedding(ZwrZ,2);
[ ClassShift( Z ) ] -> [ <wild rcwa permutation of Z with modulus 4> ]
]]>
</Example>
  </Description>
</ManSection>

Also, rcwa groups can be obtained as particular extensions of finite
permutation groups:

<ManSection>
  <Oper Name="MergerExtension"
        Arg="G, points, point" Label="for finite permutation groups"/>
  <Returns>
     roughly spoken, an extension of <A>G</A> by an involution
     which <Q>merges</Q> <A>points</A> into <A>point</A>.
  </Returns>
  <Description>
    The arguments of this operation are a finite permutation
    group <A>G</A>, a set <A>points</A> of points moved by <A>G</A>
    and a single point <A>point</A> moved by <A>G</A> which is not in
    <A>points</A>. <P/>

    Let <M>n</M> be the largest moved point of <A>G</A>, and let
    <M>H</M> be the tame subgroup of CT(&ZZ;) which respects the
    partition <M>\mathcal{P}</M> of &ZZ; into the residue classes
    (mod&nbsp;<M>n</M>), and which acts on <M>\mathcal{P}</M>
    as <A>G</A> acts on <M>\{1, \dots, n\}</M>.
    Further assume that <A>points</A> = <M>\{p_1, \dots, p_k\}</M> and
    <A>point</A> = <M>p</M>, and put <M>r_i := p_i-1, \ i = 1, \dots, k</M>
    and <M>r := p-1</M>. Now let <M>\sigma</M> be the product of the
    class transpositions <M>\tau_{r_i(n),r+(i-1)n(kn)}, \ i = 1, \dots, k</M>.
    The group returned by this operation is the extension of <M>H</M>
    by the involution <M>\sigma</M>. --
    On first reading, this may look a little complicated, but really the
    code of the method is only about half as long as this description.
<Example>
<![CDATA[
gap> # First example -- a group isomorphic to PSL(2,Z):
gap> G := MergerExtension(Group((1,2,3)),[1,2],3);
<rcwa group over Z with 2 generators>
gap> Size(G); 
infinity
gap> GeneratorsOfGroup(G);
[ ( 0(3), 1(3), 2(3) ), ( 0(3), 2(6) ) ( 1(3), 5(6) ) ]
gap> B := Ball(G,One(G),6:Spheres);;
gap> List(B,Length);
[ 1, 3, 4, 6, 8, 12, 16 ]
gap> #
gap> # Second example -- a group isomorphic to Thompson's group V:
gap> G := MergerExtension(Group((1,2,3,4),(1,2)),[1,2],3);
<rcwa group over Z with 3 generators>
gap> Size(G);
infinity
gap> GeneratorsOfGroup(G);
[ ( 0(4), 1(4), 2(4), 3(4) ), ( 0(4), 1(4) ),
  ( 0(4), 2(8) ) ( 1(4), 6(8) ) ]
gap> B := Ball(G,One(G),6:Spheres);;
gap> List(B,Length);
[ 1, 4, 11, 28, 69, 170, 413 ]
gap> G = Group(List([[0,2,1,2],[1,2,2,4],[0,2,1,4],[1,4,2,4]],
>                   ClassTransposition));
true
]]>
</Example>
  </Description>
</ManSection>

It is also possible to build an rcwa group from a list of residue classes:

<ManSection>
  <Func Name="GroupByResidueClasses" Arg="classes"
        Label="the group `permuting a given list of residue classes'"/>
  <Returns>
    the group which is generated by all class transpositions which
    interchange disjoint residue classes in <A>classes</A>.
  </Returns>
  <Description>
    The argument <A>classes</A> must be a list of residue classes. <P/>

    If the residue classes in <A>classes</A> are pairwise
    disjoint, then the returned group is the symmetric group on
    <A>classes</A>. If any two residue classes in <A>classes</A>
    intersect non-trivially, then the returned group is trivial.
    In many other cases, the returned group is infinite.
<Example>
<![CDATA[
gap> G := GroupByResidueClasses(List([[0,2],[0,4],[1,4],[2,4],[3,4]],
>                                    ResidueClass));
<rcwa group over Z with 8 generators>
gap> H := Group(List([[0,2,1,2],[1,2,2,4],[0,2,1,4],[1,4,2,4]],
>                    ClassTransposition)); # Thompson's group V
<(0(2),1(2)),(1(2),2(4)),(0(2),1(4)),(1(4),2(4))>
gap> G = H;
true
]]>
</Example>
  </Description>
</ManSection>

Various ways to construct rcwa groups are based on certain
monomorphisms from the group RCWA(<M>R</M>) into itself.
Examples are the constructions of direct products and wreath products
described above. The support of the image of such a monomorphism is
the image of a given injective rcwa mapping. For this reason,
these monomorphisms are called <E>restriction monomorphisms</E>.
The following operation computes images of rcwa mappings and -groups
under these embeddings of RCWA(<M>R</M>) into itself:

<ManSection>
  <Heading>
    Restriction (of an rcwa mapping or -group, by an injective rcwa mapping)
  </Heading>
  <Oper Name="Restriction"
        Arg="g, f" Label="of an rcwa mapping, by an injective rcwa mapping"/>
  <Oper Name="Restriction"
        Arg="G, f" Label="of an rcwa group, by an injective rcwa mapping"/>
  <Returns>
    the restriction of the rcwa mapping <A>g</A> (respectively the
    rcwa group <A>G</A>) by the injective rcwa mapping&nbsp;<A>f</A>.
  </Returns>
  <Description>
    By definition, the <E>restriction</E> <M>g_f</M> of an rcwa mapping
    <A>g</A> by an injective rcwa mapping&nbsp;<A>f</A> is the unique rcwa
    mapping which satisfies the equation <M>f \cdot g_f = g \cdot f</M>
    and which fixes the complement of the image of <A>f</A> pointwise.
    If <A>f</A> is bijective, the restriction of <A>g</A> by <A>f</A>
    is just the conjugate of <A>g</A> under&nbsp;<A>f</A>. <P/>

    The <E>restriction</E> of an rcwa group&nbsp;<A>G</A> by an injective
    rcwa mapping&nbsp;<A>f</A> is defined as the group whose elements are
    the restrictions of the elements of&nbsp;<A>G</A> by&nbsp;<A>f</A>.
    The restriction of&nbsp;<A>G</A> by&nbsp;<A>f</A> acts on the
    image of&nbsp;<A>f</A> and fixes its complement pointwise.
<Example>
<![CDATA[
gap> F2tilde := Restriction(F2,RcwaMapping([[5,3,1]]));
<wild rcwa group over Z with 2 generators>
gap> Support(F2tilde);
3(5)
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Heading>
    Induction (of an rcwa mapping or -group, by an injective rcwa mapping)
  </Heading>
  <Oper Name ="Induction"
        Arg="g, f" Label="of an rcwa mapping, by an injective rcwa mapping"/>
  <Oper Name ="Induction"
        Arg="G, f" Label="of an rcwa group, by an injective rcwa mapping"/>
  <Returns>
    the induction of the rcwa mapping <A>g</A> (respectively the rcwa
    group <A>G</A>) by the injective rcwa mapping&nbsp;<A>f</A>.
  </Returns>
  <Description>
    <E>Induction</E> is the right inverse of restriction, i.e. it is
    <C>Induction(Restriction(<A>g</A>,<A>f</A>),<A>f</A>) = <A>g</A></C> and
    <C>Induction(Restriction(<A>G</A>,<A>f</A>),<A>f</A>) = <A>G</A></C>.
    The mapping&nbsp;<A>g</A> respectively the group&nbsp;<A>G</A> must not
    move points outside the image of&nbsp;<A>f</A>.
<Example>
<![CDATA[
gap> Induction(F2tilde,RcwaMapping([[5,3,1]])) = F2;
true
]]>
</Example>
  </Description>
</ManSection>

<Index Key="SmallGeneratingSet"><C>SmallGeneratingSet</C></Index>

Once having constructed an rcwa group, it is sometimes possible
to obtain a smaller generating set by the operation
<C>SmallGeneratingSet</C>. <P/>

<Index Key="View" Subkey="for an rcwa group"><C>View</C></Index>
<Index Key="Display" Subkey="for an rcwa group"><C>Display</C></Index>
<Index Key="Print" Subkey="for an rcwa group"><C>Print</C></Index>
<Index Key="String" Subkey="for an rcwa group"><C>String</C></Index>

There are methods for the operations <C>View</C>, <C>Display</C>,
<C>Print</C> and <C>String</C> which are applicable to rcwa groups. <P/>

<Index Key="rcwa group" Subkey="modulus">rcwa group</Index>
<Index Key="rcwa group" Subkey="multiplier">rcwa group</Index>
<Index Key="rcwa group" Subkey="divisor">rcwa group</Index>
<Index Key="rcwa group" Subkey="prime set">rcwa group</Index>
<Index Key="rcwa group" Subkey="class-wise translating">rcwa group</Index>
<Index Key="rcwa group" Subkey="integral">rcwa group</Index>
<Index Key="rcwa group" Subkey="class-wise order-preserving">
  rcwa group
</Index>
<Index Key="rcwa group" Subkey="sign-preserving">rcwa group</Index>

<Index Key="Modulus" Subkey="of an rcwa group"><C>Modulus</C></Index>
<Index Key="Mod" Subkey="for an rcwa group"><C>Mod</C></Index>
<Index Key="ModulusOfRcwaMonoid" Subkey="for an rcwa group">
  <C>ModulusOfRcwaMonoid</C>
</Index>
<Index Key="Multiplier" Subkey="of an rcwa group"><C>Multiplier</C></Index>
<Index Key="Mult" Subkey="for an rcwa group"><C>Mult</C></Index>
<Index Key="Divisor" Subkey="of an rcwa group"><C>Divisor</C></Index>
<Index Key="Div" Subkey="for an rcwa group"><C>Div</C></Index>
<Index Key="PrimeSet" Subkey="of an rcwa group"><C>PrimeSet</C></Index>
<Index Key="IsClassWiseTranslating" Subkey="for an rcwa group">
  <C>IsClassWiseTranslating</C>
</Index>
<Index Key="IsIntegral" Subkey="for an rcwa group"><C>IsIntegral</C></Index>
<Index Key="IsClassWiseOrderPreserving" Subkey="for an rcwa group">
  <C>IsClassWiseOrderPreserving</C>
</Index>
<Index Key="IsSignPreserving" Subkey="for an rcwa group">
  <C>IsSignPreserving</C>
</Index>

Basic attributes of an rcwa group which are derived from the coefficients
of its elements are <C>Modulus</C>, <C>Multiplier</C>, <C>Divisor</C> and
<C>PrimeSet</C>.
The <E>modulus</E> of an rcwa group is the lcm of the moduli of its
elements if such an lcm exists, i.e. if the group is tame, and 0 otherwise.
The <E>multiplier</E> respectively <E>divisor</E> of an rcwa group is the
lcm of the multipliers respectively divisors of its elements in case such
an lcm exists and <M>\infty</M> otherwise.
The <E>prime set</E> of an rcwa group is the union of the prime sets of
its elements.
There are shorthands <C>Mod</C>, <C>Mult</C> and <C>Div</C> defined for
<C>Modulus</C>, <C>Multiplier</C> and <C>Divisor</C>, respectively.
An rcwa group is called <E>class-wise translating</E>, <E>integral</E>
or <E>class-wise order-preserving</E> if all of its elements are so.
There are corresponding methods available for <C>IsClassWiseTranslating</C>,
<C>IsIntegral</C> and <C>IsClassWiseOrderPreserving</C>. There is a property
<C>IsSignPreserving</C>, which indicates whether a given rcwa group
over&nbsp;&ZZ; acts on the set of nonnegative integers.
The latter holds for any subgroup of CT(&ZZ;) (cf. below).

<Example>
<![CDATA[
gap> G := Group(ClassTransposition(0,2,1,2),ClassTransposition(1,3,2,6),
>               ClassReflection(2,4));
<rcwa group over Z with 3 generators>
gap> List([Modulus,Multiplier,Divisor,PrimeSet,IsClassWiseTranslating,
>          IsIntegral,IsClassWiseOrderPreserving,IsSignPreserving],f->f(G));
[ 24, 2, 2, [ 2, 3 ], false, false, false, false ]
]]>
</Example>

All rcwa groups over a ring <M>R</M> are subgroups of RCWA(<M>R</M>).
The group RCWA(<M>R</M>) itself is not finitely generated, thus cannot
be constructed as described above. It is handled as a special case:

<ManSection>
  <Func Name="RCWA" Arg="R"
        Label="the group formed by all rcwa permutations of a ring"/>
  <Returns>
    the group RCWA(<A>R</A>) of all residue-class-wise affine
    permutations of the ring&nbsp;<A>R</A>.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> RCWA_Z := RCWA(Integers);
RCWA(Z)
gap> IsSubgroup(RCWA_Z,G);
true
]]>
</Example>
  </Description>
</ManSection>

Examples of rcwa permutations can be obtained via
<C>Random(RCWA(<A>R</A>))</C>, see Section&nbsp;<Ref Label="sec:Random"/>.

<Index Key="NrConjugacyClassesOfRCWAZOfOrder">
  <C>NrConjugacyClassesOfRCWAZOfOrder</C>
</Index>

The number of conjugacy classes of RCWA(&ZZ;) of elements of
given order is known, cf. Corollary&nbsp;2.7.1&nbsp;(b)
in&nbsp;<Cite Key="Kohl05"/>. It can be determined by the function
<C>NrConjugacyClassesOfRCWAZOfOrder</C>:

<Example>
<![CDATA[
gap> List([2,105],NrConjugacyClassesOfRCWAZOfOrder);
[ infinity, 218 ]
]]>
</Example>

We denote the group which is generated by all
class transpositions of the ring&nbsp;<M>R</M> by CT(<M>R</M>).
This group is handled as a special case as well:

<ManSection>
  <Func Name="CT" Arg="R"
        Label="the group generated by all class transpositions of a ring"/>
  <Func Name="CT" Arg="P, Integers"
        Label="subgroup of CT(Z)"/>
  <Returns>
    the group CT(<A>R</A>) which is generated by all
    class transpositions of the ring&nbsp;<A>R</A>, respectively,
    the group CT(<A>P</A>,&ZZ;) which is generated by all
    class transpositions of&nbsp;&ZZ; which interchange residue classes
    whose moduli have only prime factors in the finite set <A>P</A>.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> CT_Z := CT(Integers);
CT(Z)
gap> IsSimple(CT_Z); # One of a number of stored attributes/properties.
true
gap> V := CT([2],Integers);
CT_[ 2 ](Z)
gap> GeneratorsOfGroup(V);
[ ( 0(2), 1(2) ), ( 1(2), 2(4) ), ( 0(2), 1(4) ), ( 1(4), 2(4) ) ]
gap> G := CT([2,3],Integers); 
CT_[ 2, 3 ](Z)
gap> GeneratorsOfGroup(G);
[ ( 0(2), 1(2) ), ( 0(3), 1(3) ), ( 1(3), 2(3) ), ( 0(2), 1(4) ), 
  ( 0(2), 5(6) ), ( 0(3), 1(6) ) ]
]]>
</Example>
  </Description>
</ManSection>

<Index Key="Mirrored"> <C>Mirrored</C> </Index>

The group CT(&ZZ;) has an outer automorphism which is given by conjugation
with <M>n \mapsto -n - 1</M>. This automorphism can be applied to an
rcwa mapping of &ZZ; or to an rcwa group over &ZZ; by the operation
<C>Mirrored</C>. The group <C>Mirrored(</C><A>G</A><C>)</C> acts on the
nonnegative integers as <A>G</A> acts on the negative integers, and vice
versa.

<Example>
<![CDATA[
gap> ct := ClassTransposition(0,2,1,6);
( 0(2), 1(6) )
gap> Mirrored(ct);
( 1(2), 4(6) )
gap> G := Group(List([[0,2,1,2],[0,3,2,3],[2,4,1,6]],ClassTransposition));;
gap> ShortOrbits(G,[-100..100],100);
[ [ 0, 1, 2, 3, 4, 5 ] ]
gap> ShortOrbits(Mirrored(G),[-100..100],100);
[ [ -6, -5, -4, -3, -2, -1 ] ]
]]>
</Example>

<Index Key="AllElementsOfCTZWithGivenModulus">
  <C>AllElementsOfCTZWithGivenModulus</C>
</Index>
<Index Key="NrElementsOfCTZWithGivenModulus">
  <C>NrElementsOfCTZWithGivenModulus</C>
</Index>

Under the hypothesis that CT(&ZZ;) is the setwise
stabilizer of <M>&NN;_0</M> in RCWA(&ZZ;), the elements of CT(&ZZ;) with
modulus dividing a given positive integer <M>m</M> are parametrized by
the ordered partitions of &ZZ; into <M>m</M> residue classes.
The list of these elements for given <M>m</M> can be obtained by
the function <C>AllElementsOfCTZWithGivenModulus</C>, and the numbers
of such elements for <M>m \leq 24</M> are stored in the list
<C>NrElementsOfCTZWithGivenModulus</C>.

<Example>
<![CDATA[
gap> NrElementsOfCTZWithGivenModulus{[1..8]};
[ 1, 1, 17, 238, 4679, 115181, 3482639, 124225680 ]
]]>
</Example>

<Index Key="NrConjugacyClassesOfRCWAZOfOrder">
  <C>NrConjugacyClassesOfCTZOfOrder</C>
</Index>

The number of conjugacy classes of CT(&ZZ;) of elements of
given order is also known under the hypothesis that CT(&ZZ;) is the setwise
stabilizer of <M>&NN;_0</M> in RCWA(&ZZ;). It can be determined by the
function <C>NrConjugacyClassesOfCTZOfOrder</C>.

</Section>

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

<Section Label="sec:InvestigatingRcwaGroups">
<Heading>
  Basic routines for investigating residue-class-wise affine groups
</Heading>

In the previous section we have seen how to construct rcwa groups.
The purpose of this section is to describe how to obtain information on
the structure of an rcwa group and on its action on the underlying ring.
The easiest way to get a little (but really only <E>a very little</E>!)
information on the group structure is a dedicated method for the operation
<C>StructureDescription</C>:

<ManSection>
  <Meth Name="StructureDescription" Arg="G" Label="for an rcwa group"/>
  <Returns>
    a string which sometimes gives a little glimpse of the structure
    of the rcwa group&nbsp;<A>G</A>.
  </Returns>
  <Description>
    The attribute <C>StructureDescription</C> for finite groups is
    documented in the &GAP; Reference Manual. Therefore we describe here
    only issues which are specific to infinite groups, and in particular
    to rcwa groups. <P/>

    Wreath products are denoted by&nbsp;<C>wr</C>, and free products
    are denoted by&nbsp;<C>*</C>. The infinite cyclic group (&ZZ;,+) is
    denoted by&nbsp;<C>Z</C>, the infinite dihedral group is denoted
    by&nbsp;<C>D0</C> and free groups of rank <M>2,3,4,\dots</M>
    are denoted by&nbsp;<C>F2</C>, <C>F3</C>, <C>F4</C>,&nbsp;<M>\dots</M>.
    While for finite groups the symbol&nbsp;<C>.</C> is used to denote a
    non-split extension, for rcwa groups in general it stands for an
    extension which may be split or not.
    For wild groups in most cases it happens that there is a large section
    on which no structural information can be obtained. Such sections of the
    group with unknown structure are denoted by <C>&lt;unknown&gt;</C>.
    In general, the structure of a section denoted by <C>&lt;unknown&gt;</C>
    can be very complicated and very difficult to exhibit.
<Example>
<![CDATA[
gap> G := Group(ClassTransposition(0,2,1,4),ClassShift(0,5));;
gap> StructureDescription(G);
"(Z x Z x Z x Z x Z x Z x Z) . (C2 x S7)"
gap> G := Group(ClassTransposition(0,2,1,4),
>               ClassShift(2,4),ClassReflection(1,2));;
gap> StructureDescription(G:short);
"Z^2.((S3xS3):2)"
gap> F2 := Image(IsomorphismRcwaGroup(FreeGroup(2)));;
gap> PSL2Z := Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(3),
>                                                    CyclicGroup(2))));;
gap> G := DirectProduct(PSL2Z,F2);
<wild rcwa group over Z with 4 generators>
gap> StructureDescription(G);
"(C3 * C2) x F2"
gap> G := WreathProduct(G,CyclicGroup(IsRcwaGroupOverZ,infinity));
<wild rcwa group over Z with 5 generators>
gap> StructureDescription(G);
"((C3 * C2) x F2) wr Z"
gap> Collatz := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);;
gap> G := Group(Collatz,ClassShift(0,1));;
gap> StructureDescription(G:short);
"<unknown>.Z"
]]>
</Example>
  </Description>
</ManSection>

The extent to which the structure of an rcwa group can be exhibited
automatically is severely limited. In general, one can find out much more
about the structure of a given rcwa group in an interactive session using
the functionality described in the rest of this section and elsewhere in
this manual. <P/>

<Index Key="Size" Subkey="for an rcwa group"><C>Size</C></Index>

The order of an rcwa group can be computed by the operation <C>Size</C>.
An rcwa group is finite if and only if it is tame and its action on a
suitably chosen respected partition (see&nbsp;<Ref Attr="RespectedPartition"
Label="of a tame rcwa group"/>) is faithful.
Hence the problem of computing the order of an rcwa group reduces to
the problem of deciding whether it is tame, the problem of deciding whether
it acts faithfully on a respected partition and the problem of computing the
order of the finite permutation group induced on the respected partition.

<Example>
<![CDATA[
gap> G := Group(ClassTransposition(0,2,1,2),ClassTransposition(1,3,2,3),
>               ClassReflection(0,5));
<rcwa group over Z with 3 generators>
gap> Size(G);
46080
]]>
</Example>

<Index Key="IsomorphismPermGroup" Subkey="for a finite rcwa group">
  <C>IsomorphismPermGroup</C>
</Index>

For a finite rcwa group, an isomorphism to a permutation group can be
computed by <C>IsomorphismPermGroup</C>:

<Example>
<![CDATA[
gap> G := Group(ClassTransposition(0,2,1,2),ClassTransposition(0,3,1,3));;
gap> IsomorphismPermGroup(G);
[ ( 0(2), 1(2) ), ( 0(3), 1(3) ) ] -> [ (1,2)(3,4)(5,6), (1,2)(4,5) ]
]]>
</Example>

<Index Key="rcwa group" Subkey="membership test">rcwa group</Index>
<Index Key="OrbitLengthBound"><C>OrbitLengthBound</C></Index>

In general the membership problem for rcwa groups is algorithmically
unsolvable, see Corollary&nbsp;4.5 in&nbsp;<Cite Key="Kohl09"/>.
A consequence of this is that a membership test <Q><C>g in G</C></Q> may
run into an infinite loop if the rcwa permutation <C>g</C> is not an
element of the rcwa group <C>G</C>. For tame rcwa groups however
membership can always be decided. For wild rcwa groups, membership can
very often be decided quite quick as well, but -- as said -- not always. 
Anyway, if <C>g</C> is contained in <C>G</C>, the membership test will
eventually always return <C>true</C>, provided that there are sufficient
computing resources available (memory etc.). <P/>

On Info level&nbsp;2 of <C>InfoRCWA</C> the membership test provides
information on reasons why the given rcwa permutation is an element of
the given rcwa group or&nbsp;not. <P/>

The membership test <Q><C>g in G</C></Q> recognizes an option
<C>OrbitLengthBound</C>. If this option is set, it returns <C>false</C>
once it has computed balls of size exceeding <C>OrbitLengthBound</C>
about 1 and <C>g</C> in <C>G</C>, and these balls are still disjoint.
Note however that due to the algorithmic unsolvability of the membership
problem, &RCWA; has no means to check the correctness of such bound
in a given case. So the correct use of this option has to remain within
the full responsibility of the user.

<Example>
<![CDATA[
gap> G := Group(ClassShift(0,3),ClassTransposition(0,3,2,6));;
gap>  ClassShift(2,6)^7 * ClassTransposition(0,3,2,6)
>   * ClassShift(0,3)^-3 in G;
true
gap> ClassShift(0,1) in G;
false
]]>
</Example>

<Index Key="rcwa group" Subkey="conjugacy problem">rcwa group</Index>
<Index Key="IsConjugate" Subkey="for elements of RCWA(R)">
  <C>IsConjugate</C>
</Index>
<Index Key="IsConjugate" Subkey="for elements of CT(R)">
  <C>IsConjugate</C>
</Index>

The conjugacy problem for rcwa groups is difficult, and &RCWA; provides
only methods to solve it in some reasonably easy cases.

<Example>
<![CDATA[
gap> IsConjugate(RCWA(Integers),
>                ClassTransposition(0,2,1,4),ClassShift(0,1));
false
gap> IsConjugate(CT(Integers),ClassTransposition(0,2,1,6),
>                             ClassTransposition(1,4,0,8));
true
gap> g := RepresentativeAction(CT(Integers),ClassTransposition(0,2,1,6),
>                                           ClassTransposition(1,4,0,8));
<rcwa permutation of Z with modulus 48>
gap> ClassTransposition(0,2,1,6)^g = ClassTransposition(1,4,0,8);
true
]]>
</Example>

<Index Key="IsTame" Subkey="for an rcwa group"><C>IsTame</C></Index>
There is a property <C>IsTame</C> which indicates whether an rcwa group
is tame or not:

<Example>
<![CDATA[
gap> G := Group(ClassTransposition(0,2,1,4),ClassShift(1,3));;
gap> H := Group(ClassTransposition(0,2,1,6),ClassShift(1,3));;
gap> IsTame(G);
true
gap> IsTame(H);
false
]]>
</Example>

<Index Key="IsSolvable" Subkey="for an rcwa group"><C>IsSolvable</C></Index>
<Index Key="IsPerfect"  Subkey="for an rcwa group"><C>IsPerfect</C></Index>
<Index Key="DerivedSubgroup" Subkey="of an rcwa group">
  <C>DerivedSubgroup</C>
</Index>
<Index Key="Index" Subkey="for rcwa groups"><C>Index</C></Index>
<Index Key="IsomorphismMatrixGroup" Subkey="for an rcwa group">
  <C>IsomorphismMatrixGroup</C>
</Index>
<Index Key="Exponent" Subkey="of an rcwa group"><C>Exponent</C></Index>

For tame rcwa groups, there are methods for <C>IsSolvable</C> and
<C>IsPerfect</C> available, and usually derived subgroups and subgroup
indices can be computed as well. Linear representations of tame groups
over the rationals can be determined by the operation
<C>IsomorphismMatrixGroup</C>. Testing a wild group for solvability
or perfectness is currently not always feasible, and wild groups
have in general no faithful finite-dimensional linear representations.
There is a method for <C>Exponent</C> available, which works basically
for any rcwa group.

<Example>
<![CDATA[
gap> G := Group(ClassTransposition(0,2,1,4),ClassShift(1,2));;
gap> IsPerfect(G);
false
gap> IsSolvable(G);
true
gap> D1 := DerivedSubgroup(G);; D2 := DerivedSubgroup(D1);;
gap> IsAbelian(D2);
true
gap> Index(G,D1); Index(D1,D2);
infinity
9
gap> StructureDescription(G); StructureDescription(D1);
"(Z x Z x Z) . S3"
"(Z x Z) . C3"
gap> Q := D1/D2;
Group([ (), (1,2,4)(3,5,7)(6,8,9), (1,3,6)(2,5,8)(4,7,9) ])
gap> StructureDescription(Q); 
"C3 x C3"
gap> Exponent(G);
infinity
gap> phi := IsomorphismMatrixGroup(G);;
gap> Display(Image(phi,ClassTransposition(0,2,1,4)));
[ [     0,     0,   1/2,  -1/2,     0,     0 ], 
  [     0,     0,     0,     1,     0,     0 ], 
  [     2,     1,     0,     0,     0,     0 ], 
  [     0,     1,     0,     0,     0,     0 ], 
  [     0,     0,     0,     0,     1,     0 ], 
  [     0,     0,     0,     0,     0,     1 ] ]
]]>
</Example>

When investigating a group, a basic task is to find relations among
the generators:

<ManSection>
  <Meth Name="EpimorphismFromFpGroup"
        Arg="G, r" Label="for an rcwa group and a search radius"/>
  <Meth Name="EpimorphismFromFpGroup"
        Arg="G, r, maxparts"
        Label="for rcwa group, search radius and bound on number of affine parts"/>
  <Returns>
    an epimorphism from a finitely presented group to the
    rcwa group&nbsp;<A>G</A>.
  </Returns>
  <Description>
    The argument <A>r</A> is the <Q>search radius</Q>, i.e. the
    radius of the ball around&nbsp;1 which is scanned for relations.
    In general, the larger <A>r</A> is chosen the smaller the kernel
    of the returned epimorphism is. If the group&nbsp;<A>G</A> has
    finite presentations, the kernel will in principle get trivial
    provided that <A>r</A> is chosen large enough.
    If the optional argument <A>maxparts</A> is given, it limits the
    search space to elements with at most <A>maxparts</A> affine parts.
<Example>
<![CDATA[
gap> a := ClassTransposition(2,4,3,4);;
gap> b := ClassTransposition(4,6,8,12);;
gap> c := ClassTransposition(3,4,4,6);;
gap> G := SparseRep(Group(a,b,c));
<(2(4),3(4)),(4(6),8(12)),(3(4),4(6))>
gap> phi := EpimorphismFromFpGroup(G,6);
#I  there are 3 generators and 12 relators of total length 330
#I  there are 3 generators and 11 relators of total length 312
[ a, b, c ] -> [ ( 2(4), 3(4) ), ( 4(6), 8(12) ), ( 3(4), 4(6) ) ]
gap> RelatorsOfFpGroup(Source(phi));
[ a^2, b^2, c^2, (b*c)^3, (a*b)^6, (a*b*c*b)^3, (a*c*b*c)^3, 
  (a*b*a*c)^12, ((a*b)^2*a*c)^12, (a*b*(a*c)^2)^12, (a*b*c*a*c*b)^12 ]
]]>
</Example>
  </Description>
</ManSection>

A related very common task is to factor group elements into generators:

<ManSection>
  <Meth Name ="PreImagesRepresentative" Arg="phi, g"
        Label="for an epi. from a free group to an rcwa group"/>
  <Returns>
    a representative of the set of preimages of&nbsp;<A>g</A> under
    the epimorphism&nbsp;<A>phi</A> from a free group to an rcwa group.
  </Returns>
  <Description>
    The epimorphism <A>phi</A> must map the generators of the free
    group to the generators of the rcwa group one-by-one. <P/>

    This method can be used for factoring elements of rcwa groups
    into generators. The implementation is based on
    <C>RepresentativeActionPreImage</C>, see 
    <Ref Oper="RepresentativeAction"
         Label="G, source, destination, action"/>. <P/>

    <Index Key="PreImagesRepresentatives"
           Subkey="for an epi. from a free group to an rcwa group">
      <C>PreImagesRepresentatives</C>
    </Index>

    Quite frequently, computing several preimages is not harder than
    computing just one, i.e. often several preimages are found
    simultaneously. The operation <C>PreImagesRepresentatives</C>
    takes care of this. It takes the same arguments as
    <C>PreImagesRepresentative</C> and returns a list of preimages.
    If multiple preimages are found, their quotients give rise to nontrivial
    relations among the generators of the image of&nbsp;<A>phi</A>.
<Example>
<![CDATA[
gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; SetName(a,"a");
gap> b := ClassShift(0,1);; SetName(b,"b");
gap> G := Group(a,b);; # G = <<Collatz permutation>, n -> n + 1>
gap> phi := EpimorphismFromFreeGroup(G);;
gap> g := Comm(a^2*b^4,a*b^3); # a sample element to be factored
<rcwa permutation of Z with modulus 8>
gap> PreImagesRepresentative(phi,g); # -> a factorization of g
b^-3*(b^-1*a^-1)^2*b^3*a*b^-1*a*b^3
gap> g = b^-4*a^-1*b^-1*a^-1*b^3*a*b^-1*a*b^3; # check
true
gap> g := Comm(a*b,Comm(a,b^3));
<rcwa permutation of Z with modulus 8>
gap> pre := PreImagesRepresentatives(phi,g);
[ (b^-1*a^-1)^2*b^2*(b*a)^2*b^-2, b^-1*(a^-1*b)^2*b^2*(a*b^-1)^2*b^-1 ]
gap> rel := pre[1]/pre[2]; # -> a nontrivial relation
(b^-1*a^-1)^2*b^3*a*b^2*a^-1*b^-2*(b^-1*a)^2*b
gap> rel^phi;
IdentityMapping( Integers )
]]>
</Example>
  </Description>
</ManSection>

</Section>

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

<Section Label="sec:ActionOnR">
<Heading>
  The natural action of an rcwa group on the underlying ring
</Heading>

Knowing a natural permutation representation of a group usually helps
significantly in computing in it and in obtaining results on its structure.
This holds particularly for the natural action of an rcwa group on its
underlying ring. In this section we describe &RCWA;'s functionality
related to this action. <P/>

<Index Key="Support" Subkey="of an rcwa group"><C>Support</C></Index>
<Index Key="MovedPoints" Subkey="of an rcwa group"><C>MovedPoints</C></Index>
<Index Key="IsTransitive" Subkey="for an rcwa group, on its underlying ring">
  <C>IsTransitive</C>
</Index>

The support, i.e. the set of moved points, of an rcwa group can be
determined by <C>Support</C> or <C>MovedPoints</C> (these are synonyms).
Testing for transitivity on the underlying ring or on a union of residue
classes thereof is often feasible:

<Example>
<![CDATA[
gap> G := Group(ClassTransposition(1,2,0,4),ClassShift(0,2));;
gap> IsTransitive(G,Integers);
true
]]>
</Example>

<Alt Only="LaTeX">
<Index Key="IsTransitiveOnNonnegativeIntegersInSupport"
       Subkey="for an rcwa group over Z">
  <C>IsTransitiveOnNonnegativeIntegersIn- Support</C>
</Index>
<Index Key="TryIsTransitiveOnNonnegativeIntegersInSupport"
       Subkey="for an rcwa group over Z and a search limit">
  <C>TryIsTransitiveOnNonnegativeIntegers- InSupport</C>
</Index>
</Alt>
<Alt Not="LaTeX">
<Index Key="IsTransitiveOnNonnegativeIntegersInSupport"
       Subkey="for an rcwa group over Z">
  <C>IsTransitiveOnNonnegativeIntegersInSupport</C>
</Index>
<Index Key="TryIsTransitiveOnNonnegativeIntegersInSupport"
       Subkey="for an rcwa group over Z and a search limit">
  <C>TryIsTransitiveOnNonnegativeIntegersInSupport</C>
</Index>
</Alt>
<Index Key="TransitivityCertificate"
       Subkey="for an rcwa group over Z and a search limit">
  <C>TransitivityCertificate</C>
</Index>
<Index Key="TryToComputeTransitivityCertificate"
       Subkey="for an rcwa group over Z and a search limit">
  <C>TryToComputeTransitivityCertificate</C>
</Index>
<Index Key="SimplifiedCertificate"
       Subkey="for a transitivity certificate of an rcwa groups over Z">
  <C>SimplifiedCertificate</C>
</Index>

Groups generated by class transpositions of the integers act on the set of
nonnegative integers. There is a property
<C>IsTransitiveOnNonnegativeIntegersInSupport(<A>G</A>)</C> which indicates
whether such group acts transitively on the set of nonnegative integers in
its support. Since such transitivity test is a computationally hard problem,
methods may fail. If <C>IsTransitiveOnNonnegativeIntegersInSupport</C>
returns <C>true</C>, an attribute <C>TransitivityCertificate</C> is set;
this is a record containing components <C>phi</C>, <C>words</C>,
<C>classes</C>, <C>smallpointbound</C>, <C>status</C> and <C>complete</C>
as follows:
<List>

  <Mark><C>phi</C></Mark>
  <Item>
    is an epimorphism from a free group to <A>G</A> which maps generators
    to generators.
  </Item>

  <Mark><C>words</C>, <C>classes</C></Mark>
  <Item>
    two lists. -- <C>words[i]</C> is a preimage under <C>phi</C> of
    an element of <A>G</A> which maps all sufficiently large positive
    integers in the residue classes <C>classes[i]</C> to smaller
    nonnegative integers.
  </Item>

  <Mark><C>smallpointbound</C></Mark>
  <Item>
    in addition to finding a list of group elements <M>g_i</M> such that
    for any large enough integer <M>n</M> in the support of <A>G</A> there
    is some <M>g_i</M> such that <M>n^{g_i} &lt; n</M>, for verifying
    transitivity it was necessary to check that all integers less than or
    equal to <C>smallpointbound</C> in the support of <A>G</A> lie in the
    same orbit.
  </Item>

  <Mark><C>status</C></Mark>
  <Item>
    the string <C>"transitive"</C> in case all checks have been completed
    successfully.
  </Item>

  <Mark><C>complete</C></Mark>
  <Item>
    <C>true</C> in case all checks have been completed successfully.
  </Item>

</List>
Parts of this information for possibly intransitive groups can be
obtained by the operation
<C>TryToComputeTransitivityCertificate(<A>G</A>,<A>searchlimit</A>)</C>,
where <A>searchlimit</A> is the maximum radius about a point within
which smaller points are searched and taken into consideration.
This operation interprets an option <C>abortdensity</C> -- if set,
the operation returns the data computed so far once the density of
the set of positive integers in the support of <A>G</A> for which no
group element is found which maps them to smaller integers reaches
or drops below <C>abortdensity</C>. A simplified certificate can be
obtained via <C>SimplifiedCertificate(<A>cert</A>)</C>.
<Example>
<![CDATA[
gap> G := Group(List([[0,2,1,2],[0,3,2,3],[1,2,2,4]],
>                    ClassTransposition));
<(0(2),1(2)),(0(3),2(3)),(1(2),2(4))>
gap> IsTransitiveOnNonnegativeIntegersInSupport(G);
true
gap> TransitivityCertificate(G);
rec( 
  classes := [ [ 1(2) ], [ 2(6) ], [ 6(12), 10(12) ], [ 0(12) ], 
      [ 4(12) ] ], complete := true, 
  phi := [ a, b, c ] -> [ ( 0(2), 1(2) ), ( 0(3), 2(3) ), ( 1(2), 2(4) ) 
     ], smallpointbound := 4, status := "transitive", 
  words := [ a, b, c, b*c, a*b ] )
gap> SimplifiedCertificate(last);
rec( classes := [ [ 1(2) ], [ 2(4) ], [ 4(12) ], [ 0(12), 8(12) ] ], 
  complete := true, 
  phi := [ a, b, c ] -> [ ( 0(2), 1(2) ), ( 0(3), 2(3) ), ( 1(2), 2(4) ) 
     ], smallpointbound := 4, status := "transitive", 
  words := [ a, c, a*b, b*c ] )
gap> G := Group(List([[0,2,1,2],[1,2,2,4],[1,4,2,6]],
>                    ClassTransposition));              # '3n+1 group'
<(0(2),1(2)),(1(2),2(4)),(1(4),2(6))>
gap> cert := TryToComputeTransitivityCertificate(G,10);
rec(
  classes := [ [ 1(2) ], [ 2(4) ], [ 4(32) ], [ 8(24), 44(48), 20(96) ], 
      [ 0(24), 16(24) ] ], complete := false, 
  phi := [ a, b, c ] -> [ ( 0(2), 1(2) ), ( 1(2), 2(4) ), ( 1(4), 2(6) ) 
     ], remaining := [ 12(48), 28(48), 52(96), 84(96) ], 
  smallpointbound := 42, status := "unclear", 
  words := [ a, b, (a*c)^2*b*a*b, c, a*c*b ] )
gap> Union(Flat(cert.classes));
<union of 90 residue classes (mod 96) (6 classes)>
gap> Difference(Integers,Union(Flat(cert.classes)));
12(48) U 28(48) U 52(96) U 84(96)
gap> cert := TryToComputeTransitivityCertificate(G,20); # try larger bound
rec(
  classes := [ [ 1(2) ], [ 2(4) ], [ 4(32) ], [ 8(24), 44(48), 20(96) ], 
      [ 0(24), 16(24) ], [ 12(768), 268(768) ], [ 28(768), 540(768) ] ], 
  complete := false, 
  phi := [ a, b, c ] -> [ ( 0(2), 1(2) ), ( 1(2), 2(4) ), ( 1(4), 2(6) ) 
     ], 
  remaining := [ 52(96), 84(96), 60(192), 108(192), 124(192), 172(192), 
      76(384), 204(384), 220(384), 348(384), 156(768), 396(768), 
      412(768), 652(768) ], smallpointbound := 1074, status := "unclear", 
  words := [ a, b, (a*c)^2*b*a*b, c, a*c*b, (a*c)^3*b*c*b*a*b, 
      (a*c)^4*b*a*b*a*b ] )
gap> Difference(Integers,Union(Flat(cert.classes)));
<union of 44 residue classes (mod 768) (14 classes)>
gap> Intersection([0..100],last);
[ 52, 60, 76, 84 ]
]]>
</Example>

Further, there are methods to compute orbits under the
action of an rcwa group:

<ManSection>
  <Heading> Orbit (for an rcwa group and either a point or a set) </Heading>
  <Meth Name="Orbit" Arg="G, point" Label="for an rcwa group and a point"/>
  <Meth Name="Orbit" Arg="G, set"   Label="for an rcwa group and a set"/>
  <Returns>
    the orbit of the point&nbsp;<A>point</A> respectively the
    set&nbsp;<A>set</A> under the natural action of the rcwa
    group&nbsp;<A>G</A> on its underlying ring.
  </Returns>
  <Description>
    The second argument can either be an element or a subset of
    the underlying ring of the rcwa group&nbsp;<A>G</A>.
    Since orbits under the action of rcwa groups can be finite
    or infinite, and since infinite orbits are not necessarily
    residue class unions, the orbit may either be returned in
    the form of a list, in the form of a residue class union
    or in the form of an orbit object. It is possible to loop over
    orbits returned as orbit objects, they can be compared and
    there is a membership test for them. However note that equality
    and membership for such orbits cannot always be decided.
<Example>
<![CDATA[
gap> G := Group(ClassShift(0,2),ClassTransposition(0,3,1,3));
<rcwa group over Z with 2 generators>
gap> Orbit(G,0);
Z \ 5(6)
gap> Orbit(G,5);
[ 5 ]
gap> Orbit(G,ResidueClass(0,2));
[ 0(2), 1(6) U 2(6) U 3(6), 1(3) U 3(6), 0(3) U 1(6), 0(3) U 4(6), 
  1(3) U 0(6), 0(3) U 2(6), 0(6) U 1(6) U 2(6), 2(6) U 3(6) U 4(6), 
  1(3) U 2(6) ]
gap> Length(Orbit(G,ResidueClass(0,4)));
80
gap> G := Group(ClassTransposition(0,2,1,2),ClassTransposition(0,2,1,4),
>               ClassReflection(0,3));
<rcwa group over Z with 3 generators>
gap> orb := Orbit(G,2);
<orbit of 2 under <wild rcwa group over Z with 3 generators>>
gap> 1015808 in orb;
true
gap> First(orb,n->ForAll([n,n+2,n+6,n+8,n+30,n+32,n+36,n+38],IsPrime));
-19
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Oper Name="GrowthFunctionOfOrbit" Arg="G, n, r_max, size_max"
   Label="for an rcwa group, a point and bounds on radius and sphere size"/>
  <Meth Name="GrowthFunctionOfOrbit" Arg="orb, r_max, size_max"
   Label="for an rcwa group orbit and bounds on radius and sphere size"/>
  <Returns>
    a list whose (<M>r+1</M>)-th entry is the size of the sphere of
    radius <M>r</M> about <A>n</A> under the action of the group <A>G</A>,
    where the argument <A>r_max</A> is the largest possible radius to be
    considered, and the computation stops once the sphere size exceeds
    <A>size_max</A>.
  </Returns>
  <Description>
     An option <C>"small"</C> is interpreted -- see example below.
     In place of the group <A>G</A> and the point <A>n</A>, one can pass as
     first argument also an rcwa group orbit object <A>orb</A>.
<Example>
<![CDATA[
gap> G := Group(List([[0,4,1,4],[0,3,5,6],[0,4,5,6]],ClassTransposition));
<(0(4),1(4)),(0(3),5(6)),(0(4),5(6))>
gap> GrowthFunctionOfOrbit(G,18,100,20);
[ 1, 1, 2, 3, 4, 3, 4, 4, 4, 4, 3, 3, 3, 4, 3, 4, 4, 5, 5, 6, 8, 6, 5, 
  5, 4, 3, 3, 4, 4, 4, 3, 3, 5, 4, 5, 6, 5, 2, 3, 3, 2, 3, 3, 4, 5, 4, 
  4, 4, 6, 5, 5, 3, 4, 2, 3, 4, 4, 2, 3, 4, 4, 2, 3, 3, 4, 3, 5, 3, 5, 
  4, 5, 6, 5, 3, 4, 5, 6, 5, 4, 3, 5, 4, 5, 5, 4, 4, 5, 5, 3, 4, 5, 3, 
  3, 4, 5, 4, 2, 3, 4, 4, 4 ]
gap> last = GrowthFunctionOfOrbit(Orbit(G,18),100,20);
true
gap> GrowthFunctionOfOrbit(G,18,20,20:small:=[0..100]);
rec( smallpoints := [ 18, 24, 25, 27, 30, 32, 33, 36, 37, 39, 40, 41, 
      42, 44, 45, 48, 49, 51, 52, 53, 56, 57, 59, 60, 61, 64, 65, 66, 
      68, 69, 71, 75, 76, 77, 80, 81, 83, 88, 89, 92, 93, 95, 100 ], 
  spheresizes := [ 1, 1, 2, 3, 4, 3, 4, 4, 4, 4, 3, 3, 3, 4, 3, 4, 4, 5, 
      5, 6, 8 ] )
gap> G := Group(List([[0,2,1,2],[1,2,2,4],[1,4,2,6]],ClassTransposition));
<(0(2),1(2)),(1(2),2(4)),(1(4),2(6))>
gap> GrowthFunctionOfOrbit(G,0,100,10000);
[ 1, 1, 1, 1, 1, 1, 1, 2, 3, 3, 4, 5, 7, 6, 7, 9, 12, 14, 19, 21, 28, 
  29, 37, 42, 55, 57, 72, 78, 99, 113, 148, 164, 215, 226, 288, 344, 
  462, 478, 612, 686, 894, 985, 1284, 1416, 1847, 2018, 2620, 2902, 
  3786, 4167, 5432, 5958, 7749, 8568, 11178 ]
]]>
</Example>
  </Description>
</ManSection>

<Index Key="DistanceToNextSmallerPointInOrbit">
  <C>DistanceToNextSmallerPointInOrbit</C>
</Index>

Given an rcwa group <A>G</A> over &ZZ; and an integer <A>n</A>,
<C>DistanceToNextSmallerPointInOrbit(</C><A>G</A><C>,</C><A>n</A><C>)</C>
computes the smallest number <M>d</M> such that there is a product <M>g</M>
of <M>d</M> generators or inverses of generators of <A>G</A> which maps
<A>n</A> to an integer with absolute value less than |<A>n</A>|, provided
that the orbit of <A>n</A> contains such integer.

&RCWA; provides a function to draw pictures of orbits of rcwa groups
on&nbsp;<M>&ZZ;^2</M>. The pictures are written to files in bitmap-
(bmp-) format. The author has successfully tested this feature both under
Linux and under Windows, and the generated pictures can be processed
further with many common graphics programs:

<ManSection>
  <Func Name="DrawOrbitPicture"
        Arg="G, p0, bound, h, w, colored, palette, filename"
        Label="G, p0, bound, h, w, colored, palette, filename"/>
  <Returns> nothing. </Returns>
  <Description>
    Draws a picture of the orbit(s) of the point(s) <A>p0</A> under the
    action of the group <A>G</A> on&nbsp;<M>&ZZ;^2</M>.
    The argument <A>p0</A> is either one point or a list of points.
    The argument <A>bound</A> denotes the bound to which the ball about
    <A>p0</A> is to be computed, in terms of absolute values of coordinates.
    The size of the generated picture is <A>h</A>&nbsp;x&nbsp;<A>w</A> pixels.
    The argument <A>colored</A> is a boolean which indicates whether a 24-bit
    true color picture or a monochrome picture should be generated.
    In the former case, <A>palette</A> must be a list of triples of integers
    in the range <M>0, \dots, 255</M>, denoting the RGB values of the colors
    to be used. In the latter case, <A>palette</A> is not used, and any value
    can be passed. The picture is written in bitmap- (bmp-) format to a file
    named <A>filename</A>. This is done using the utility function
    <C>SaveAsBitmapPicture</C> from &ResClasses;.
<Log>
<![CDATA[
gap> PSL2Z := Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(2),
>                                                    CyclicGroup(3))));;
gap> DrawOrbitPicture(PSL2Z,[0,1],2000,512,512,false,fail,"example1.bmp");
gap> DrawOrbitPicture(PSL2Z,Combinations([1..4],2),2000,512,512,true,
>                     [[255,0,0],[0,255,0],[0,0,255]],"example2.bmp");
]]>
</Log>
  </Description>
</ManSection>

The pictures drawn in the examples are shown on &RCWA;'s webpage. <P/>

Finite orbits give rise to finite quotients of a group, and finite cycles
can help to check for conjugacy. Therefore it is important to be able
to determine them:

<ManSection>
  <Heading>
    ShortOrbits (for rcwa groups) &amp; ShortCycles (for rcwa permutations)
  </Heading>
  <Oper Name="ShortOrbits" Arg="G, S, maxlng"
        Label="for rcwa group, set of points and bound on length"/>
  <Oper Name="ShortOrbits" Arg="G, S, maxlng, maxn"
        Label="for rcwa group, set of points and bounds on length and points"/>
  <Oper Name="ShortCycles" Arg="g, S, maxlng"
        Label="for rcwa permutation, set of points and bound on length"/>
  <Oper Name="ShortCycles" Arg="g, S, maxlng, maxn"
        Label="for rcwa permutation, set of points and bounds on length and points"/>
  <Oper Name="ShortCycles" Arg="g, maxlng"
        Label="for rcwa permutation and bound on length"/>
  <Returns>
    in the first form a list of all orbits of the rcwa group&nbsp;<A>G</A>
    of length at most <A>maxlng</A> which intersect non-trivially with the
    set&nbsp;<A>S</A>.
    In the second form a list of all orbits of the rcwa group&nbsp;<A>G</A>
    of length at most <A>maxlng</A> which intersect non-trivially with
    the set&nbsp;<A>S</A> and which, in terms of euclidean norm, do not
    exceed <A>maxn</A>.
    In the third form a list of all cycles of the rcwa permutation <A>g</A>
    of length at most&nbsp;<A>maxlng</A> which intersect non-trivially with
    the set&nbsp;<A>S</A>.
    In the fourth form a list of all cycles of the rcwa permutation <A>g</A>
    of length at most&nbsp;<A>maxlng</A> which intersect non-trivially with
    the set&nbsp;<A>S</A> and which, in terms of euclidean norm, do not
    exceed <A>maxn</A>.
    In the fifth form a list of all cycles of the rcwa permutation <A>g</A>
    of length at most <A>maxlng</A> which do not correspond to cycles
    consisting of residue classes.
  </Returns>
  <Description>
    The operation <Ref Oper="ShortOrbits"
    Label="for rcwa group, set of points and bound on length"/> recognizes
    an option <A>finite</A>. If this option is set, it is assumed that all
    orbits are finite, in order to speed up the computation. If furthermore
    <A>maxlng</A> is negative, a list of <E>all</E> orbits which intersect
    non-trivially with&nbsp;<A>S</A> is returned. <P/>

    <Index Key="CyclesOnFiniteOrbit"><C>CyclesOnFiniteOrbit</C></Index>

    There is an operation
    <C>CyclesOnFiniteOrbit(</C><A>G</A><C>,</C><A>g</A><C>,</C><A>n</A><C>)</C>
    which returns a list of all cycles of the rcwa permutation <A>g</A> on the
    orbit of the point <A>n</A> under the action of the rcwa group <A>G</A>.
    Here <A>g</A> is assumed to be an element of <A>G</A>, and the orbit
    of <A>n</A> is assumed to be finite.
<Example>
<![CDATA[
gap> G := Group(ClassTransposition(1,4,2,4)*ClassTransposition(1,4,3,4),
>               ClassTransposition(3,9,6,18)*ClassTransposition(1,6,3,9));;
gap> List(ShortOrbits(G,[-15..15],100),
>         orb->StructureDescription(Action(G,orb)));
[ "A15", "A4", "1", "1", "C3", "1", "((C2 x C2 x C2) : C7) : C3", "1", 
  "1", "C3", "A19" ]
gap> ShortCycles(mKnot(7),[1..100],20);
[ [ 1 ], [ 2 ], [ 3 ], [ 4 ], [ 5 ], [ 6 ], [ 7, 8 ], [ 9, 10 ], 
  [ 11, 12 ], [ 13, 14, 16, 18, 20, 22, 19, 17, 15 ], [ 21, 24 ], 
  [ 23, 26 ], [ 25, 28, 32, 36, 31, 27, 30, 34, 38, 33, 29 ], 
  [ 35, 40 ], [ 37, 42, 48, 54, 47, 41, 46, 52, 45, 39, 44, 50, 43 ], 
  [ 77, 88, 100, 114, 130, 148, 127, 109, 124, 107, 122, 105, 120, 103, 
      89 ] ]
gap> G := Group(List([[0,2,1,2],[0,5,4,5],[1,4,0,6]],ClassTransposition));;
gap> CyclesOnFiniteOrbit(G,G.1*G.2,0);
[ [ 0, 1, 4, 9, 8, 5 ], [ 6, 7 ], [ 10, 11, 14, 19, 18, 15 ], [ 12, 13 ] ]
gap> List(CyclesOnFiniteOrbit(G,G.1*G.2*G.3*G.1*G.3*G.2,32),Length);
[ 3148, 3148 ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Heading>
    ShortResidueClassOrbits &amp; ShortResidueClassCycles
  </Heading>
  <Oper Name="ShortResidueClassOrbits" Arg="G, modulusbound, maxlng"
        Label="for rcwa group and bounds on modulus and length"/>
  <Oper Name="ShortResidueClassCycles" Arg="g, modulusbound, maxlng"
        Label="for rcwa permutation and bounds on modulus and length"/>
  <Returns>
    in the first form a list of all orbits of residue classes under the
    action of the rcwa group <A>G</A> which contain a residue class
    <M>r(m)</M> such that <M>m</M> divides <A>modulusbound</A> and
    which are not longer than <A>maxlng</A>.
    In the second form a list of all cycles of residue classes of the
    rcwa permutation&nbsp;<A>g</A> which contain a residue class
    <M>r(m)</M> such that <M>m</M> divides <A>modulusbound</A> and
    which are not longer than <A>maxlng</A>.
  </Returns>
  <Description>
    We are only talking about a <E>cycle</E> of residue classes of
    an rcwa permutation <M>g</M> if the restrictions of <M>g</M> to all
    contained residue classes are affine.
    Similarly we are only talking about an <E>orbit</E> of residue
    classes under the action of an rcwa group <M>G</M> if the
    restrictions of all elements of <M>G</M> to all residue classes
    in the orbit are affine. <P/>

    The returned lists may contain additional cycles, resp., orbits,
    which do not contain a residue class <M>r(m)</M> such that <M>m</M>
    divides <A>modulusbound</A>, but which happen to be found without
    additional efforts.
<Example>
<![CDATA[
gap> g := ClassTransposition(0,2,1,2)*ClassTransposition(0,4,1,6);
<rcwa permutation of Z with modulus 12>
gap> ShortResidueClassCycles(g,Mod(g)^2,20);
[ [ 2(12), 3(12) ], [ 10(12), 11(12) ], [ 4(24), 5(24), 7(36), 6(36) ], 
  [ 20(24), 21(24), 31(36), 30(36) ], 
  [ 8(48), 9(48), 13(72), 19(108), 18(108), 12(72) ], 
  [ 40(48), 41(48), 61(72), 91(108), 90(108), 60(72) ], 
  [ 16(96), 17(96), 25(144), 37(216), 55(324), 54(324), 36(216), 24(144) 
     ], 
  [ 80(96), 81(96), 121(144), 181(216), 271(324), 270(324), 180(216), 
      120(144) ] ]
gap> G := Group(List([[0,6,5,6],[1,4,4,6],[2,4,3,6]],ClassTransposition));
<(0(6),5(6)),(1(4),4(6)),(2(4),3(6))>
gap> ShortResidueClassOrbits(G,48,10);
[ [ 7(12) ], [ 8(12) ], [ 1(24), 4(36) ], [ 2(24), 3(36) ], 
  [ 12(24), 17(24), 28(36) ], [ 18(24), 23(24), 27(36) ], 
  [ 37(48), 58(72), 87(108) ], [ 38(48), 57(72), 88(108) ], 
  [ 0(48), 5(48), 10(72), 15(108) ], [ 6(48), 11(48), 9(72), 16(108) ] ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Func Name="ComputeCycleLength"
        Arg="g, n" Label="for an rcwa permutation and a point"/>
  <Returns>
    a record containing the length, the largest point and the position of the
    largest point of the cycle of the rcwa permutation <A>g</A> which contains
    the point <A>n</A>, provided that this cycle is finite.
  </Returns>
  <Description>
    If the cycle is infinite, the function will run into an infinite loop
    unless the option <C>"abortat"</C> is set to the maximum number of iterates
    to be tried before aborting. Iterates are not stored, to save memory.
    The function interprets an option <C>"notify"</C>, which defaults to 10000;
    every <Q>notify</Q> iterations, the number of binary digits of the latest
    iterate is printed. This output can be suppressed by the option <C>quiet</C>.
    The function also interprets an option <C>"small"</C>, which may be set to
    a range within which small points are recorded and returned in a component
    <C>smallpoints</C>. 
<Example>
<![CDATA[
gap> g := Product(List([[0,5,3,5],[1,2,0,6],[2,4,3,6]],
>                      ClassTransposition));
<rcwa permutation of Z with modulus 180>
gap> ComputeCycleLength(g,20:small:=[0..1000]);
n = 20: after 10000 steps, the iterate has 1919 binary digits.
n = 20: after 20000 steps, the iterate has 2908 binary digits.
n = 20: after 30000 steps, the iterate has 1531 binary digits.
n = 20: after 40000 steps, the iterate has 708 binary digits.
rec( aborted := false, g := <rcwa permutation of Z with modulus 180>, 
  length := 45961, 
  maximum := 180479928411509527091314790144929480041473309862957394384783\
0525935437431021442346166422201250935268553945158085769924448388724679753\
5271669245363980744610119632280105994423399614803956244808653465492205657\
8650363041608376587943180444494842094693691286183613056599672737336761093\
3101035841077322874883200384115281051837032147150147712534199292886436789\
7520389780289517825203780151058517520194926468391308525704499649905091899\
9667529835495635671154681958992898010506577172313321500572646883756736685\
0158653917532084531267455434808219032998691038943070902228427549279555530\
6429870190316109419051531138721361826083376315737131067799731181096142797\
4868525347003646887454985757711743327946232372385342293662007684758208408\
8635715976464060647431260835037213863991037813998261883899050447111540742\
5857187943077255493709629738212709349458790098815926920248565399938335540\
8092502449690267365120996852, maxpos := 19825, n := 20, 
  smallpoints := [ 20, 23, 66, 99, 294, 295, 298, 441, 447, 882, 890, 
      893 ] )
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Oper Name="CycleRepresentativesAndLengths" Arg="g, S"
        Label="for rcwa permutation and set of seed points"/>
  <Returns>
    a list of pairs (cycle representative, length of cycle) for all
    cycles of the rcwa permutation <A>g</A> which have a nontrivial
    intersection with the set <A>S</A>, where fixed points are omitted.
  </Returns>
  <Description>
    The rcwa permutation <A>g</A> is assumed to have only finite
    cycles. If <A>g</A> has an infinite cycle which intersects
    non-trivially with <A>S</A>, this may cause an infinite loop
    unless a cycle length limit is set via the option <C>abortat</C>.
    The output can be suppressed by the option <C>quiet</C>.
<Example>
<![CDATA[
gap> g := ClassTransposition(0,2,1,2)*ClassTransposition(0,4,1,6);;
gap> CycleRepresentativesAndLengths(g,[0..50]);
[ [ 2, 2 ], [ 4, 4 ], [ 8, 6 ], [ 10, 2 ], [ 14, 2 ], [ 16, 8 ], 
  [ 20, 4 ], [ 22, 2 ], [ 26, 2 ], [ 28, 4 ], [ 32, 10 ], [ 34, 2 ], 
  [ 38, 2 ], [ 40, 6 ], [ 44, 4 ], [ 46, 2 ], [ 50, 2 ] ]
gap> g := Product(List([[0,5,3,5],[1,2,0,6],[2,4,3,6]],
>                      ClassTransposition));
<rcwa permutation of Z with modulus 180>
gap> CycleRepresentativesAndLengths(g,[0..100]:abortat:=100000);
n = 20: after 10000 steps, the iterate has 1919 binary digits.
n = 20: after 20000 steps, the iterate has 2908 binary digits.
n = 20: after 30000 steps, the iterate has 1531 binary digits.
n = 20: after 40000 steps, the iterate has 708 binary digits.
n = 79: after 10000 steps, the iterate has 1679 binary digits.
n = 100: after 10000 steps, the iterate has 712 binary digits.
n = 100: after 20000 steps, the iterate has 2507 binary digits.
n = 100: after 30000 steps, the iterate has 3311 binary digits.
n = 100: after 40000 steps, the iterate has 3168 binary digits.
n = 100: after 50000 steps, the iterate has 3947 binary digits.
n = 100: after 60000 steps, the iterate has 4793 binary digits.
n = 100: after 70000 steps, the iterate has 5325 binary digits.
n = 100: after 80000 steps, the iterate has 6408 binary digits.
n = 100: after 90000 steps, the iterate has 7265 binary digits.
n = 100: after 100000 steps, the iterate has 7918 binary digits.
[ [ 0, 7 ], [ 5, 3 ], [ 7, 7159 ], [ 11, 9 ], [ 19, 342 ],
  [ 20, 45961 ], [ 25, 3 ], [ 26, 21 ], [ 29, 2 ], [ 31, 3941 ],
  [ 34, 19 ], [ 37, 7 ], [ 40, 5 ], [ 41, 7 ], [ 46, 3 ], [ 49, 2 ],
  [ 59, 564 ], [ 61, 577 ], [ 65, 3 ], [ 67, 23 ], [ 71, 41 ],
  [ 79, 16984 ], [ 80, 5 ], [ 85, 3 ], [ 86, 3 ], [ 89, 2 ], [ 91, 9 ],
  [ 94, 1355 ], [ 97, 7 ], [ 100, fail ] ]
]]>
</Example>
  </Description>
</ManSection>

Often one also wants to know which residue classes an rcwa mapping
or an rcwa group fixes setwise:

<ManSection>
  <Oper Name="FixedResidueClasses" Arg="g, maxmod"
        Label="for rcwa mapping and bound on modulus"/>
  <Oper Name="FixedResidueClasses" Arg="G, maxmod"
        Label="for rcwa group and bound on modulus"/>
  <Returns>
    the set of residue classes with modulus greater than 1 and less
    than or equal to <A>maxmod</A> which the rcwa mapping <A>g</A>,
    respectively the rcwa group <A>G</A>, fixes setwise. 
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> FixedResidueClasses(ClassTransposition(0,2,1,4),8);
[ 2(3), 3(4), 4(5), 6(7), 3(8), 7(8) ]
gap> FixedResidueClasses(Group(ClassTransposition(0,2,1,4),
>                              ClassTransposition(0,3,1,3)),12);
[ 2(3), 8(9), 11(12) ]
]]>
</Example>
  </Description>
</ManSection>

Frequently one needs to compute balls of certain radius around points or
group elements, be it to estimate the growth of a group, be it to see how
an orbit looks like, be it to search for a group element with certain
properties or be it for other purposes:

<ManSection>
  <Heading>
    Ball (for group, element and radius or group, point, radius and action)
  </Heading>
  <Meth Name ="Ball" Arg="G, g, r"
        Label="for group, element and radius"/>
  <Meth Name ="Ball" Arg="G, p, r, action"
        Label="for group, point, radius and action"/>
  <Meth Name ="Ball" Arg="G, p, r"
        Label="for group, point and radius"/>
  <Returns>
    the ball of radius&nbsp;<A>r</A> around the element&nbsp;<A>g</A> in
    the group&nbsp;<A>G</A>, respectively
    the ball of radius&nbsp;<A>r</A> around the point&nbsp;<A>p</A> under
    the action&nbsp;<A>action</A> of the group&nbsp;<A>G</A>, respectively
    the ball of radius&nbsp;<A>r</A> around the point&nbsp;<A>p</A> under
    the action&nbsp;<C>OnPoints</C> of the group&nbsp;<A>G</A>, 
  </Returns>
  <Description>
    All balls are understood with respect to
    <C>GeneratorsOfGroup(<A>G</A>)</C>.
    As membership tests can be expensive, the former method does not check
    whether <A>g</A> is indeed an element of&nbsp;<A>G</A>.
    The methods require that element- / point comparisons are cheap.
    They are not only applicable to rcwa groups.
    If the option <A>Spheres</A> is set, the ball is split up and
    returned as a list of spheres. There is a related operation
    <C>RestrictedBall(<A>G</A>,<A>g</A>,<A>r</A>,<A>modulusbound</A>)</C>
    specifically for rcwa groups which computes only those elements of the
    ball whose moduli do not exceed <A>modulusbound</A>, and which can be
    reached from <A>g</A> without computing intermediate elements whose
    moduli do exceed <A>modulusbound</A>. The latter operation interprets
    an option <C>"boundaffineparts"</C>. -- If this option is set and the
    group <A>G</A> and the element <A>g</A> are in sparse representation,
    then <A>modulusbound</A> is actually taken to be a bound on the number
    of affine parts rather than a bound on the modulus.

    <Index Key="RestrictedBall" Subkey="G, g, r, modulusbound">
      <C>RestrictedBall</C>
    </Index>

<Example>
<![CDATA[
gap> PSL2Z := Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(2),
>                                                    CyclicGroup(3))));;
gap> List([1..10],k->Length(Ball(PSL2Z,[0,1],k,OnTuples)));
[ 4, 8, 14, 22, 34, 50, 74, 106, 154, 218 ]
gap> Ball(Group((1,2),(2,3),(3,4)),(),2:Spheres);
[ [ () ], [ (3,4), (2,3), (1,2) ],
  [ (2,3,4), (2,4,3), (1,2)(3,4), (1,2,3), (1,3,2) ] ]
gap> G := Group(List([[1,2,4,6],[1,3,2,6],[2,3,4,6]],ClassTransposition));;
gap> B := RestrictedBall(G,One(G),20,36:Spheres);; # try replacing 36 by 72
gap> List(B,Length);
[ 1, 3, 6, 12, 4, 6, 6, 4, 4, 4, 6, 6, 3, 3, 2, 0, 0, 0, 0, 0, 0 ]
]]>
</Example>
  </Description>
</ManSection>

It is possible to determine group elements which map a given tuple of elements
of the underlying ring to a given other tuple, if such elements exist:

<ManSection>
  <Meth Name="RepresentativeAction" Arg="G, source, destination, action"
        Label="G, source, destination, action"/>
  <Returns>
    an element of <A>G</A> which maps <A>source</A>
    to&nbsp;<A>destination</A> under the action given by&nbsp;<A>action</A>.
  </Returns>
  <Description>
    If an element satisfying this condition does not exist, this method
    either returns <C>fail</C> or runs into an infinite loop.
    The problem whether <A>source</A> and <A>destination</A> lie in
    the same orbit under the action <A>action</A> of&nbsp;<A>G</A> is hard,
    and in its general form most likely computationally undecidable. <P/>

    <Index Key="RepresentativeActionPreImage"
           Subkey="G, source, destination, action, F">
      <C>RepresentativeActionPreImage</C>
    </Index>

    In cases where rather a word in the generators of&nbsp;<A>G</A> than
    the actual group element is needed, one should use the operation
    <C>RepresentativeActionPreImage</C> instead. This operation takes
    five arguments. The first four are the same as those of
    <C>RepresentativeAction</C>, and the fifth is a free group whose
    generators are to be used as letters of the returned word. Note that
    <C>RepresentativeAction</C> calls <C>RepresentativeActionPreImage</C>
    and evaluates the returned word. The evaluation of the word can very
    well take most of the time if <A>G</A> is wild and coefficient
    explosion occurs. <P/>

    The algorithm is based on computing balls of increasing radius
    around <A>source</A> and <A>destination</A> until they intersect
    non-trivially.
<Example>
<![CDATA[
gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; SetName(a,"a");
gap> b := ClassShift(1,4:Name:="b");; G := Group(a,b);;
gap> elm := RepresentativeAction(G,[7,4,9],[4,5,13],OnTuples);;
gap> Display(elm);

Rcwa permutation of Z with modulus 12

        /
        | n-3 if n in 1(6) U 10(12)
        | n+4 if n in 5(12) U 9(12)
 n |-> <  n+1 if n in 4(12)
        | n   if n in 0(6) U 2(6) U 3(12) U 11(12)
        |
        \

gap> List([7,4,9],n->n^elm);
[ 4, 5, 13 ]
gap> elm := RepresentativeAction(G,[6,-3,8],[-9,4,11],OnPoints);;
gap> Display(elm);

Rcwa permutation of Z with modulus 12

        /
        | 2n/3      if n in 0(6) U 3(12)
        | (4n+1)/3  if n in 2(6) U 11(12)
        | (4n-1)/3  if n in 4(6) U 7(12)
 n |-> <  (2n-8)/3  if n in 1(12)
        | (4n-17)/3 if n in 5(12)
        | (4n-15)/3 if n in 9(12)
        |
        \

gap> [6,-3,8]^elm; List([6,-3,8],n->n^elm); # `OnPoints' allows reordering
[ -9, 4, 11 ]
[ 4, -9, 11 ]
gap> F := FreeGroup("a","b");; phi := EpimorphismByGenerators(F,G);;
gap> w := RepresentativeActionPreImage(G,[10,-4,9,5],[4,5,13,-8],
>                                      OnTuples,F);
a*b^-1*a^-1*(b^-1*a)^2*b*a*b^-2*a*b*a^-1*b
gap> elm := w^phi;
<rcwa permutation of Z with modulus 324>
gap> List([10,-4,9,5],n->n^elm);
[ 4, 5, 13, -8 ]
]]>
</Example>
  </Description>
</ManSection>

Sometimes an rcwa group fixes a certain partition of the underlying ring
into unions of residue classes. If this happens, then any orbit is clearly
a subset of exactly one of these parts. Further, such a partition often
gives rise to proper quotients of the group:

<ManSection>
  <Oper Name ="ProjectionsToInvariantUnionsOfResidueClasses"
        Arg="G, m" Label="for rcwa group and modulus"/>
  <Returns>
    the projections of the rcwa group&nbsp;<A>G</A> to the unions of
    residue classes (mod&nbsp;<A>m</A>) which it fixes setwise.
  </Returns>
  <Description>
    The corresponding partition of a set of representatives for
    the residue classes (mod&nbsp;<A>m</A>) can be obtained by the
    operation <C>OrbitsModulo(<A>G</A>,<A>m</A>)</C>.
    <Index Key="OrbitsModulo" Subkey="for an rcwa group and a modulus">
      <C>OrbitsModulo</C>
    </Index>
<Example>
<![CDATA[
gap> G := Group(ClassTransposition(0,2,1,2),ClassShift(3,4));;
gap> ProjectionsToInvariantUnionsOfResidueClasses(G,4);
[ [ ( 0(2), 1(2) ), ClassShift( 3(4) ) ] -> 
    [ ( 0(4), 1(4) ), IdentityMapping( Integers ) ], 
  [ ( 0(2), 1(2) ), ClassShift( 3(4) ) ] -> 
    [ ( 2(4), 3(4) ), <rcwa permutation of Z with modulus 4> ] ]
gap> List(last,phi->Support(Image(phi)));
[ 0(4) U 1(4), 2(4) U 3(4) ]
]]>
</Example>
  </Description>
</ManSection>

Given two partitions of the underlying ring into the same number of
unions of residue classes, there is always an rcwa permutation which
maps the one to the other:

<ManSection>
  <Meth Name="RepresentativeAction" Arg="RCWA(R), P1, P2"
        Label="for RCWA(R) and 2 partitions of R into residue classes"/>
  <Returns>
    an element of RCWA(<M>R</M>) which maps the partition&nbsp;<A>P1</A>
    to&nbsp;<A>P2</A>.
  </Returns>
  <Description>
    The arguments <A>P1</A> and <A>P2</A> must be partitions of the
    underlying ring <M>R</M> into the same number of unions of residue
    classes.
    The method for <M>R = &ZZ;</M> recognizes the option <C>IsTame</C>,
    which can be used to demand a tame result. If this option is set and
    there is no tame rcwa permutation which maps <A>P1</A> to&nbsp;<A>P2</A>,
    the method runs into an infinite loop. This happens if the condition
    in Theorem&nbsp;2.8.9 in&nbsp;<Cite Key="Kohl05"/> is not satisfied.
    If the option <C>IsTame</C> is not set and the partitions <A>P1</A>
    and <A>P2</A> both consist entirely of single residue classes, then
    the returned mapping is affine on any residue class in&nbsp;<A>P1</A>.
<Example>
<![CDATA[
gap> P1 := AllResidueClassesModulo(3);
[ 0(3), 1(3), 2(3) ]
gap> P2 := List([[0,2],[1,4],[3,4]],ResidueClass);
[ 0(2), 1(4), 3(4) ]
gap> elm := RepresentativeAction(RCWA(Integers),P1,P2);
<rcwa permutation of Z with modulus 3>
gap> P1^elm = P2;
true
gap> IsTame(elm);
false
gap> elm := RepresentativeAction(RCWA(Integers),P1,P2:IsTame);
<tame rcwa permutation of Z with modulus 24>
gap> P1^elm = P2;
true
gap> elm := RepresentativeAction(RCWA(Integers),
>             [ResidueClass(1,3),
>              ResidueClassUnion(Integers,3,[0,2])],
>             [ResidueClassUnion(Integers,5,[2,4]),
>              ResidueClassUnion(Integers,5,[0,1,3])]);
<rcwa permutation of Z with modulus 6>
gap> [ResidueClass(1,3),ResidueClassUnion(Integers,3,[0,2])]^elm;
[ 2(5) U 4(5), Z \ 2(5) U 4(5) ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Oper Name="CollatzLikeMappingByOrbitTree" Arg="G, n, min_r, max_r"
        Label="for rcwa group, root point and range of radii"/>
  <Returns>
    either an rcwa mapping <M>f</M> which maps the sphere of radius
    <M>r</M> about <A>n</A> under the action of <A>G</A> into the sphere
    of radius <M>r-1</M> about <A>n</A> for every <M>r</M> ranging from
    <A>min_r</A> to <A>max_r</A>, or <C>fail</C>.
  </Returns>
  <Description>
    Obviously not for every rcwa group and every root point a mapping
    <M>f</M> with these properties exists, and if it exists, it
    usually depends on the choice of generators of the group.
<Example>
<![CDATA[
gap> G := Group(ClassTransposition(0,2,1,2),ClassTransposition(1,2,2,4),
>               ClassTransposition(1,4,2,6));;
gap> G := SparseRep(G);;
gap> f := CollatzLikeMappingByOrbitTree(G,0,4,10);
<rcwa mapping of Z with modulus 4 and 4 affine parts>
gap> Display(f);

Rcwa mapping of Z with modulus 4 and 4 affine parts

        /
        | n+1      if n in 0(4)
        | (3n+1)/2 if n in 1(4)
 n |-> <  n/2      if n in 2(4)
        | n-1      if n in 3(4)
        |
        \

gap> B := Ball(G,0,15:Spheres);
[ [ 0 ], [ 1 ], [ 2 ], [ 3 ], [ 6 ], [ 7 ], [ 14 ], [ 9, 15 ], [ 8, 18, 30 ], 
  [ 5, 19, 31 ], [ 4, 10, 38, 62 ], [ 11, 25, 39, 41, 63 ], 
  [ 22, 24, 40, 50, 78, 82, 126 ], [ 23, 33, 51, 79, 83, 127 ], 
  [ 32, 46, 66, 102, 158, 166, 254 ], 
  [ 21, 47, 67, 103, 105, 159, 167, 169, 255 ] ]
gap> List([3..15],i->IsSubset(B[i-1],B[i]^f));
[ true, true, true, true, true, true, true, true, true, true, true, true,
  true ]
gap> Trajectory(f,52,[0,1]);
[ 52, 53, 80, 81, 122, 61, 92, 93, 140, 141, 212, 213, 320, 321, 482, 241, 
  362, 181, 272, 273, 410, 205, 308, 309, 464, 465, 698, 349, 524, 525, 788, 
  789, 1184, 1185, 1778, 889, 1334, 667, 666, 333, 500, 501, 752, 753, 1130, 
  565, 848, 849, 1274, 637, 956, 957, 1436, 1437, 2156, 2157, 3236, 3237, 
  4856, 4857, 7286, 3643, 3642, 1821, 2732, 2733, 4100, 4101, 6152, 6153, 
  9230, 4615, 4614, 2307, 2306, 1153, 1730, 865, 1298, 649, 974, 487, 486, 
  243, 242, 121, 182, 91, 90, 45, 68, 69, 104, 105, 158, 79, 78, 39, 38, 19, 
  18, 9, 14, 7, 6, 3, 2, 1 ]
]]>
</Example>
  </Description>
</ManSection>

</Section>

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

<Section Label="sec:MethodsForTameGroups">
<Heading>
  Special attributes of tame residue-class-wise affine groups
</Heading>

There are a couple of attributes which a priori make only sense for tame
rcwa groups. With their help, various structural information about a given
such group can be obtained.
We have already seen above that there are for example methods for
<C>IsSolvable</C>, <C>IsPerfect</C> and <C>DerivedSubgroup</C> available
for tame rcwa groups, while testing wild groups for solvability or
perfectness is currently not always feasible. The purpose of this section
is to describe the specific attributes of tame groups which are needed for
these computations.

<ManSection>
  <Heading>
    RespectedPartition (of a tame rcwa group or -permutation)
  </Heading>
  <Attr Name="RespectedPartition"
        Arg="G" Label="of a tame rcwa group"/>
  <Attr Name="RespectedPartition"
        Arg="g" Label="of a tame rcwa permutation"/>
  <Returns>
    a shortest and coarsest possible respected partition
    of the rcwa group <A>G</A> / of the rcwa permutation&nbsp;<A>g</A>.
  </Returns>
  <Description>
    A tame element <M>g</M>&nbsp;<M>\in</M>&nbsp;RCWA(<M>R</M>) permutes a
    partition of&nbsp;<M>R</M> into finitely many residue classes on all of
    which it is affine.
    Given a tame group <M>G</M>&nbsp;<M>&lt;</M>&nbsp;RCWA(<M>R</M>),
    there is a common such partition for all elements of&nbsp;<M>G</M>.
    We call the mentioned partitions <E>respected partitions</E>
    of&nbsp;<M>g</M> or&nbsp;<M>G</M>, respectively. <P/>

    An rcwa group or an rcwa permutation has a respected partition
    if and only if it is tame. This holds either by definition or by
    Theorem&nbsp;2.5.8 in&nbsp;<Cite Key="Kohl05"/>, depending on how
    one introduces the notion of tameness. <P/>

    <Index Key="RespectsPartition" Subkey="for an rcwa group">
      <C>RespectsPartition</C>
    </Index>
    <Index Key="RespectsPartition" Subkey="for an rcwa permutation">
      <C>RespectsPartition</C>
    </Index>
    There is an operation <C>RespectsPartition(<A>G</A>,<A>P</A>)</C> /
    <C>RespectsPartition(<A>g</A>,<A>P</A>)</C>, which tests whether
    <A>G</A> or&nbsp;<A>g</A> respects a given partition&nbsp;<A>P</A>.
    The permutation induced by <A>g</A> on&nbsp;<C>P</C> can be computed
    efficiently by <C>PermutationOpNC(<A>g</A>,P,OnPoints)</C>.
    <Index Key="PermutationOpNC" Subkey="g, P, OnPoints">
      <C>PermutationOpNC</C>
    </Index>
<Example>
<![CDATA[
gap> G := Group(ClassTransposition(0,4,1,6),ClassShift(0,2));
<rcwa group over Z with 2 generators>
gap> IsTame(G);
true
gap> Size(G);
infinity
gap> P := RespectedPartition(G);
[ 0(4), 2(4), 1(6), 3(6), 5(6) ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Heading>
    ActionOnRespectedPartition &amp; KernelOfActionOnRespectedPartition
  </Heading>
  <Attr Name="ActionOnRespectedPartition"
        Arg="G" Label="for a tame rcwa group"/>
  <Attr Name="KernelOfActionOnRespectedPartition"
        Arg="G" Label="for a tame rcwa group"/>
  <Attr Name="RankOfKernelOfActionOnRespectedPartition"
        Arg="G" Label="for a tame rcwa group"/>
  <Returns>
    the action of the tame rcwa group&nbsp;<A>G</A> on
    <C>RespectedPartition(<A>G</A>)</C>, the kernel of
    this action or the rank of the latter, respectively.
  </Returns>
  <Description>
    The method for <C>KernelOfActionOnRespectedPartition</C> uses the
    package <Package>Polycyclic</Package>&nbsp;<Cite Key="Polycyclic"/>.

    The rank of the largest free abelian subgroup of the kernel of the
    action of&nbsp;<A>G</A> on its stored respected partition is
    <C>RankOfKernelOfActionOnRespectedPartition(<A>G</A>)</C>.
<Example>
<![CDATA[
gap> G := Group(ClassTransposition(0,4,1,6),ClassShift(0,2));;
gap> H := ActionOnRespectedPartition(G);
Group([ (1,3), (1,2) ])
gap> H = Action(G,P);
true
gap> Size(H);
6
gap> K := KernelOfActionOnRespectedPartition(G);
<rcwa group over Z with 3 generators>
gap> RankOfKernelOfActionOnRespectedPartition(G);
3
gap> Index(G,K);
6
gap> List(GeneratorsOfGroup(K),Factorization);
[ [ ClassShift( 0(4) ) ], [ ClassShift( 2(4) ) ], [ ClassShift( 1(6) ) ] ]
gap> Image(IsomorphismPcpGroup(K));
Pcp-group with orders [ 0, 0, 0 ]
]]>
</Example>
  </Description>
</ManSection>

Let <M>G</M> be a tame rcwa group over&nbsp;&ZZ;, let <M>\mathcal{P}</M>
be a respected partition of&nbsp;<M>G</M> and put <M>m := |\mathcal{P}|</M>.
Then there is an rcwa permutation <M>g</M> which maps <M>\mathcal{P}</M>
to the partition of&nbsp;&ZZ; into the residue classes (mod&nbsp;<M>m</M>),
and the conjugate <M>G^g</M> of&nbsp;<M>G</M> under such a permutation
is integral (cf. <Cite Key="Kohl05"/>, Theorem&nbsp;2.5.14). <P/>

<Index Key="IntegralConjugate" Subkey="of a tame rcwa group">
  <C>IntegralConjugate</C>
</Index>
<Index Key="IntegralConjugate" Subkey="of a tame rcwa permutation">
  <C>IntegralConjugate</C>
</Index>
<Index Key="IntegralizingConjugator" Subkey="of a tame rcwa group">
  <C>IntegralizingConjugator</C>
</Index>
<Index Key="IntegralizingConjugator" Subkey="of a tame rcwa permutation">
  <C>IntegralizingConjugator</C>
</Index>

The conjugate <M>G^g</M> can be determined by the operation
<C>IntegralConjugate</C>, and the conjugating permutation&nbsp;<M>g</M>
can be determined by the operation <C>IntegralizingConjugator</C>.
Both operations are applicable to rcwa permutations as well.
Note that a tame rcwa group does not determine its integral conjugate
uniquely.

<Example>
<![CDATA[
gap> G := Group(ClassTransposition(0,4,1,6),ClassShift(0,2));;
gap> G^IntegralizingConjugator(G) = IntegralConjugate(G);
true
gap> RespectedPartition(G);
[ 0(4), 2(4), 1(6), 3(6), 5(6) ]
gap> RespectedPartition(G)^IntegralizingConjugator(G);
[ 0(5), 1(5), 2(5), 3(5), 4(5) ]
gap> last = RespectedPartition(IntegralConjugate(G));
true
]]>
</Example>

</Section>

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

<Section Label="sec:Random">
<Heading>Generating pseudo-random elements of RCWA(R) and CT(R)</Heading>

<Index Key="Random" Subkey="RCWA(R)"><C>Random</C></Index>
<Index Key="Random" Subkey="CT(R)"><C>Random</C></Index>
There are methods for the operation <C>Random</C> for RCWA(<M>R</M>)
and CT(<M>R</M>). These methods are designed to be suitable for generating
interesting examples. No particular distribution is guaranteed.

<Log>
<![CDATA[
gap> elm := Random(RCWA(Integers));;
gap> Display(elm);

Rcwa permutation of Z with modulus 180

        /
        | 6n+12     if n in 2(10) U 4(10) U 6(10) U 8(10)
        | 3n+3      if n in 1(20) U 5(20) U 9(20) U 17(20)
        | 6n+10     if n in 0(10)
        | (n+1)/2   if n in 15(60) U 27(60) U 39(60) U 51(60)
        | (n+7)/2   if n in 19(60) U 31(60) U 43(60) U 55(60)
        | 3n+1      if n in 13(20)
        | (-n+17)/6 if n in 23(180) U 35(180) U 59(180) U 71(180) U 
 n |-> <                    95(180) U 131(180) U 143(180) U 179(180)
        | (-n-1)/6  if n in 11(180) U 47(180) U 83(180) U 155(180)
        | (-n+7)/2  if n in 3(60)
        | (n+3)/2   if n in 7(60)
        | (n-17)/6  if n in 107(180)
        | (-n+11)/6 if n in 119(180)
        | (-n+29)/6 if n in 167(180)
        |
        \
]]>
</Log>

The elements which are returned by this method are obtained by
multiplying class shifts (see <Ref Func="ClassShift" Label="r, m"/>),
class reflections (see <Ref Func="ClassReflection" Label="r, m"/>) and
class transpositions (see <Ref Func="ClassTransposition"
                          Label="r1, m1, r2, m2"/>).
These factors can be retrieved by factoring:

<Log>
<![CDATA[
gap> Factorization(elm);
[ ClassTransposition(0,2,3,4), ClassTransposition(1,2,4,6), ClassShift(0,2), 
  ClassShift(1,3), ClassReflection(2,5), ClassReflection(1,3), 
  ClassReflection(1,2) ]
]]>
</Log>

</Section>

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

<Section Label="sec:CategoriesOfRcwaGroups">
<Heading>The categories of residue-class-wise affine groups</Heading>

<ManSection>
  <Filt Name="IsRcwaGroup" Arg="G"/>
  <Filt Name="IsRcwaGroupOverZ" Arg="G"/>
  <Filt Name="IsRcwaGroupOverZ_pi" Arg="G"/>
  <Filt Name="IsRcwaGroupOverGFqx" Arg="G"/>
  <Returns>
    <C>true</C> if <A>G</A> is an rcwa group,
    an rcwa group over the ring of integers,
    an rcwa group over a semilocalization of the ring of integers or
    an rcwa group over a polynomial ring in one variable over a finite field,
    respectively, and <C>false</C> otherwise.
  </Returns>
  <Description>

    <Index Key="IsRcwaGroupOverZOrZ_pi">
      <C>IsRcwaGroupOverZOrZ&uscore;pi</C>
    </Index>

    Often the same methods can be used for rcwa groups over the ring of
    integers and over its semilocalizations. For this reason there is
    a category <C>IsRcwaGroupOverZOrZ&uscore;pi</C> which is the union of
    <C>IsRcwaGroupOverZ</C> and <C>IsRcwaGroupOverZ&uscore;pi</C>. <P/>

    <Index Key="IsNaturalRCWA"><C>IsNaturalRCWA</C></Index>
    <Index Key="IsNaturalCT"><C>IsNaturalCT</C></Index>

    To allow distinguishing the groups RCWA(<M>R</M>) and CT(<M>R</M>) from
    others, they have the characteristic property <C>IsNaturalRCWA</C> or
    <C>IsNaturalCT</C>, respectively.

  </Description>
</ManSection>

</Section>

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

</Chapter>

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