  
  [1X3. Residue-Class-Wise Affine Groups[0X
  
  In  this  chapter,  we  describe  how to construct residue-class-wise affine
  groups and how to compute with them.
  
  
  [1X3.1 Constructing residue-class-wise affine groups[0X
  
  As  any  other  groups  in  [5XGAP[0X,  residue-class-wise  affine  groups  can be
  constructed by [10XGroup[0X, [10XGroupByGenerators[0X or [10XGroupWithGenerators[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassTransposition(0,2,1,4),ClassShift(0,5));[0X
    [4X<rcwa group over Z with 2 generators>[0X
    [4Xgap> IsTame(G); Size(G); IsSolvable(G); IsPerfect(G);[0X
    [4Xtrue[0X
    [4Xinfinity[0X
    [4Xfalse[0X
    [4Xfalse[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  There  are  methods for the operations [10XView[0X, [10XDisplay[0X, [10XPrint[0X and [10XString[0X which
  are  applicable  to rcwa groups. All rcwa groups over a ring R are subgroups
  of  RCWA(R). The group RCWA(R) itself is not finitely generated, thus cannot
  be constructed as described above. It is handled as a special case:
  
  [1X3.1-1 RCWA[0X
  
  [2X> RCWA( [0X[3XR[0X[2X ) ________________________________________________________[0Xfunction
  [6XReturns:[0X  The group RCWA([3XR[0X) of all residue-class-wise affine permutations of
            the ring [3XR[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> RCWA_Z := RCWA(Integers);[0X
    [4XRCWA(Z)[0X
    [4Xgap> IsSubgroup(RCWA_Z,G);[0X
    [4Xtrue[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  Examples  of  rcwa  permutations  can  be  obtained via [10XRandom(RCWA([3XR[0X))[0X, see
  Section [14X3.5[0X.
  
  We  denote  the  group which is generated by all class transpositions of the
  ring R by CT(R). This group is handled as a special case as well:
  
  [1X3.1-2 CT[0X
  
  [2X> CT( [0X[3XR[0X[2X ) __________________________________________________________[0Xfunction
  [6XReturns:[0X  The  group CT([3XR[0X) which is generated by all class transpositions of
            the ring R.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> CT_Z := CT(Integers);[0X
    [4XCT(Z)[0X
    [4Xgap> IsSimple(CT_Z); # One of a longer list of stored attributes/properties.[0X
    [4Xtrue[0X
    [4Xgap> IsSubgroup(CT_Z,G);[0X
    [4Xfalse[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  Another  way  of  constructing  an rcwa group is taking the image of an rcwa
  representation:
  
  [1X3.1-3 IsomorphismRcwaGroup[0X
  
  [2X> IsomorphismRcwaGroup( [0X[3XG, R[0X[2X ) ____________________________________[0Xattribute
  [2X> IsomorphismRcwaGroup( [0X[3XG[0X[2X ) _______________________________________[0Xattribute
  [6XReturns:[0X  A   monomorphism  from  the  group  [3XG[0X  to RCWA([3XR[0X)  or  to RCWA(Z),
            respectively.
  
  The  best-supported case is [3XR[0X = Z. 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 (cp.
  e.g.  Section II.B.  in [dlH00]),  and  the  method  for free groups uses an
  adaptation  of the construction given on page 27 in [dlH00] from PSL(2,C) to
  RCWA(Z).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> F := FreeProduct(Group((1,2)(3,4),(1,3)(2,4)),Group((1,2,3)),[0X
    [4X>                     SymmetricGroup(3));[0X
    [4X<fp group on the generators [ f1, f2, f3, f4, f5 ]>[0X
    [4Xgap> IsomorphismRcwaGroup(F);[0X
    [4X[ f1, f2, f3, f4, f5 ] -> [ <bijective rcwa mapping of Z with modulus 12>,[0X
    [4X  <bijective rcwa mapping of Z with modulus 24>,[0X
    [4X  <bijective rcwa mapping of Z with modulus 12>,[0X
    [4X  <bijective rcwa mapping of Z with modulus 72>,[0X
    [4X  <bijective rcwa mapping of Z with modulus 36> ][0X
    [4Xgap> IsomorphismRcwaGroup(FreeGroup(2));[0X
    [4X[ f1, f2 ] -> [ <wild bijective rcwa mapping of Z with modulus 8>,[0X
    [4X  <wild bijective rcwa mapping of Z with modulus 8> ][0X
    [4Xgap> F2 := Image(last);[0X
    [4X<wild rcwa group over Z with 2 generators>[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  The  class of groups which can faithfully be represented as rcwa groups over
  the  integers  is  closed  under taking direct products, under taking wreath
  products  with  finite  groups  and  under  taking  wreath products with the
  infinite cyclic group (Z,+). Therefore these operations can be used to build
  rcwa groups as well:
  
  [1X3.1-4 DirectProduct[0X
  
  [2X> DirectProduct( [0X[3XG1, G2, ...[0X[2X ) _______________________________________[0Xmethod
  [6XReturns:[0X  An  rcwa group isomorphic to the direct product of the rcwa groups
            over Z given as arguments.
  
  There  is  certainly no unique or canonical way to embed a direct product of
  rcwa  groups  into  RCWA(Z). This method chooses to embed the groups [3XG1[0X, [3XG2[0X,
  [3XG3[0X ... via restrictions by n -> mn, n -> mn+1, n -> mn+2 ... (-> [2XRestriction[0X
  ([14X3.1-6[0X)), where m denotes the number of groups given as arguments.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> F2 := Image(IsomorphismRcwaGroup(FreeGroup(2)));;[0X
    [4Xgap> F2xF2 := DirectProduct(F2,F2);[0X
    [4X<wild rcwa group over Z with 4 generators>[0X
    [4Xgap> Image(Projection(F2xF2,1)) = F2;[0X
    [4Xtrue[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X3.1-5  WreathProduct  (for an rcwa group over Z, with a permutation group or[0X
  [1X(Z,+))[0X
  
  [2X> WreathProduct( [0X[3XG, P[0X[2X ) ______________________________________________[0Xmethod
  [2X> WreathProduct( [0X[3XG, Z[0X[2X ) ______________________________________________[0Xmethod
  [6XReturns:[0X  An rcwa group isomorphic to the wreath product of the rcwa group [3XG[0X
            over Z  with  the  finite permutation group [3XP[0X or with the infinite
            cyclic group [3XZ[0X, respectively.
  
  The  first-mentioned  method  embeds the [10XDegreeAction([3XP[0X)[0Xth direct power of [3XG[0X
  using  the  method  for  [10XDirectProduct[0X, and lets the permutation group [3XP[0X act
  naturally  on  the  set  of  residue  classes  modulo  [10XDegreeAction([3XP[0X)[0X.  The
  second-mentioned  method  restricts  (-> [2XRestriction[0X ([14X3.1-6[0X)) the group [3XG[0X to
  the  residue  class 3(4),  and  maps  the  generator  of the infinite cyclic
  group [3XZ[0X to [10XClassTransposition(0,2,1,2) * ClassTransposition(0,2,1,4)[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> F2 := Image(IsomorphismRcwaGroup(FreeGroup(2)));;[0X
    [4Xgap> F2wrA5 := WreathProduct(F2,AlternatingGroup(5));;[0X
    [4Xgap> Embedding(F2wrA5,1);[0X
    [4X[ <wild bijective rcwa mapping of Z with modulus 8>,[0X
    [4X  <wild bijective rcwa mapping of Z with modulus 8> ] ->[0X
    [4X[ <wild bijective rcwa mapping of Z with modulus 40>,[0X
    [4X  <wild bijective rcwa mapping of Z with modulus 40> ][0X
    [4Xgap> Embedding(F2wrA5,2);[0X
    [4X[ (1,2,3,4,5), (3,4,5) ] ->[0X
    [4X[ <bijective rcwa mapping of Z with modulus 5, of order 5>,[0X
    [4X  <bijective rcwa mapping of Z with modulus 5, of order 3> ][0X
    [4Xgap> ZwrZ := WreathProduct(Group(ClassShift(0,1)),Group(ClassShift(0,1)));[0X
    [4X<wild rcwa group over Z with 2 generators>[0X
    [4Xgap> Embedding(ZwrZ,1);[0X
    [4X[ ClassShift(0,1) ] ->[0X
    [4X[ <tame bijective rcwa mapping of Z with modulus 4, of order infinity> ][0X
    [4Xgap> Embedding(ZwrZ,2);[0X
    [4X[ ClassShift(0,1) ] -> [ <wild bijective rcwa mapping of Z with modulus 4> ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  Many  of  the  above  group constructions are based on certain monomorphisms
  from  the  group  RCWA(R)  into  itself.  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  [13Xrestriction  monomorphisms[0X.  The
  following operation computes images of rcwa mappings and -groups under them:
  
  
  [1X3.1-6  Restriction  (of  an  rcwa  mapping  or  -group, by an injective rcwa[0X
  [1Xmapping)[0X
  
  [2X> Restriction( [0X[3Xg, f[0X[2X ) _____________________________________________[0Xoperation
  [2X> Restriction( [0X[3XG, f[0X[2X ) _____________________________________________[0Xoperation
  [6XReturns:[0X  The restriction of the rcwa mapping [3Xg[0X (respectively the rcwa group
            [3XG[0X) by the injective rcwa mapping [3Xf[0X.
  
  By definition, the [13Xrestriction[0X g_f of an rcwa mapping [3Xg[0X by an injective rcwa
  mapping [3Xf[0X  is the unique rcwa mapping which satisfies the equation f * g_f =
  g  *  f  and which fixes the complement of the image of [3Xf[0X pointwise. If [3Xf[0X is
  bijective, the restriction of [3Xg[0X by [3Xf[0X is just the conjugate of [3Xg[0X under [3Xf[0X.
  
  The [13Xrestriction[0X of an rcwa group [3XG[0X by an injective rcwa mapping [3Xf[0X is defined
  as  the group whose elements are the restrictions of the elements of [3XG[0X by [3Xf[0X.
  The  restriction  of [3XG[0X  by [3Xf[0X acts on the image of [3Xf[0X and fixes its complement
  pointwise.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> F2tilde := Restriction(F2,RcwaMapping([[5,3,1]]));[0X
    [4X<wild rcwa group over Z with 2 generators>[0X
    [4Xgap> Support(F2tilde);[0X
    [4X3(5)[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X3.1-7 Induction (of an rcwa mapping or -group, by an injective rcwa mapping)[0X
  
  [2X> Induction( [0X[3Xg, f[0X[2X ) _______________________________________________[0Xoperation
  [2X> Induction( [0X[3XG, f[0X[2X ) _______________________________________________[0Xoperation
  [6XReturns:[0X  The  induction  of the rcwa mapping [3Xg[0X (respectively the rcwa group
            [3XG[0X) by the injective rcwa mapping [3Xf[0X.
  
  [13XInduction[0X    is   the   right   inverse   of   restriction,   i.e.   it   is
  [10XInduction(Restriction([3Xg[0X,[3Xf[0X),[3Xf[0X) = [3Xg[0X[0X and [10XInduction(Restriction([3XG[0X,[3Xf[0X),[3Xf[0X) = [3XG[0X[0X. The
  mapping [3Xg[0X  respectively  the  group [3XG[0X must not move points outside the image
  of [3Xf[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> Induction(F2tilde,RcwaMapping([[5,3,1]])) = F2;[0X
    [4Xtrue[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  Basic attributes of an rcwa group which are derived from the coefficients of
  its  elements  are [10XModulus[0X, [10XMultiplier[0X, [10XDivisor[0X and [10XPrimeSet[0X. The [13Xmodulus[0X 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 [13Xmultiplier[0X
  respectively  [13Xdivisor[0X  of  an  rcwa  group  is  the  lcm  of the multipliers
  respectively  divisors  of its elements in case such an lcm exists and infty
  otherwise.  The [13Xprime set[0X of an rcwa group is the union of the prime sets of
  its  elements.  There  are shorthands [10XMod[0X, [10XMult[0X and [10XDiv[0X defined for [10XModulus[0X,
  [10XMultiplier[0X  and  [10XDivisor[0X,  respectively.  An  rcwa  group is called [13Xintegral[0X
  respectively  [13Xclass-wise  order-preserving[0X  if  all  of its elements are so.
  There    are    corresponding   methods   available   for   [10XIsIntegral[0X   and
  [10XIsClassWiseOrderPreserving[0X.  There  is  a  property  [10XIsSignPreserving[0X, which
  indicates  whether  a given rcwa group over Z acts on the set of nonnegative
  integers. The latter holds for any subgroup of CT(Z).
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassTransposition(0,2,1,2),ClassTransposition(1,3,2,6),  [0X
    [4X>               ClassReflection(2,4));[0X
    [4X<rcwa group over Z with 3 generators>[0X
    [4Xgap> List([Modulus,Multiplier,Divisor,PrimeSet,IsIntegral,[0X
    [4X>          IsClassWiseOrderPreserving,IsSignPreserving],f->f(G));[0X
    [4X[ 24, 2, 2, [ 2, 3 ], false, false, false ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X3.2 Basic routines for investigating residue-class-wise affine groups[0X
  
  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 some information on the group structure is a dedicated
  method for the operation [10XStructureDescription[0X:
  
  [1X3.2-1 StructureDescription[0X
  
  [2X> StructureDescription( [0X[3XG[0X[2X ) __________________________________________[0Xmethod
  [6XReturns:[0X  A string which describes the structure of the rcwa group [3XG[0X to some
            extent.
  
  The  attribute  [10XStructureDescription[0X  for finite groups is documented in the
  [5XGAP[0X  Reference  Manual.  Therefore  we  describe  here only issues which are
  specific to infinite groups, and in particular to rcwa groups.
  
  Wreath  products  are denoted by [10Xwr[0X, and free products are denoted by [10X*[0X. The
  infinite  cyclic group (Z,+) is denoted by [10XZ[0X, the infinite dihedral group is
  denoted  by [10XD0[0X  and  free  groups  of rank 2,3,4,dots are denoted by [10XF2[0X, [10XF3[0X,
  [10XF4[0X, dots. While for finite groups the symbol [10X.[0X 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 [10X<unknown>[0X. In
  general,  the  structure  of  a  section  denoted  by  [10X<unknown>[0X can be very
  complicated  and  very  difficult  to  exhibit.  While for isomorphic finite
  groups  always  the  same  structure description is computed, this cannot be
  guaranteed for isomorphic rcwa groups.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassTransposition(0,2,1,4),ClassShift(0,5));;[0X
    [4Xgap> StructureDescription(G);[0X
    [4X"(Z x Z x Z x Z x Z x Z x Z) . (C2 x S7)"[0X
    [4Xgap> G := Group(ClassTransposition(0,2,1,4),[0X
    [4X>               ClassShift(2,4),ClassReflection(1,2));;[0X
    [4Xgap> StructureDescription(G:short);[0X
    [4X"Z^2.((S3xS3):2)"[0X
    [4Xgap> F2 := Image(IsomorphismRcwaGroup(FreeGroup(2)));;[0X
    [4Xgap> PSL2Z := Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(3),[0X
    [4X>                                                    CyclicGroup(2))));;[0X
    [4Xgap> G := DirectProduct(PSL2Z,F2);[0X
    [4X<wild rcwa group over Z with 4 generators>[0X
    [4Xgap> StructureDescription(G);[0X
    [4X"(C3 * C2) x F2"[0X
    [4Xgap> G := WreathProduct(G,CyclicGroup(IsRcwaGroupOverZ,infinity));[0X
    [4X<wild rcwa group over Z with 5 generators>[0X
    [4Xgap> StructureDescription(G);[0X
    [4X"((C3 * C2) x F2) wr Z"[0X
    [4Xgap> Collatz := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);;[0X
    [4Xgap> G := Group(Collatz,ClassShift(0,1));;[0X
    [4Xgap> StructureDescription(G:short);[0X
    [4X"<unknown>.Z"[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  However  the extent to which the structure of an rcwa group can be exhibited
  automatically  is  certainly 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.
  
  The  order  of  an rcwa group can be computed by the operation [10XSize[0X. An rcwa
  group  is  finite  if  and  only  if it is tame and its action on a suitably
  chosen  respected  partition  (see [2XRespectedPartition[0X  ([14X3.4-1[0X)) 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.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassTransposition(0,2,1,2),ClassTransposition(1,3,2,3),[0X
    [4X>               ClassReflection(0,5));[0X
    [4X<rcwa group over Z with 3 generators>[0X
    [4Xgap> Size(G);[0X
    [4X46080[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  For  a  finite  rcwa  group,  an  isomorphism  to a permutation group can be
  computed by [10XIsomorphismPermGroup[0X:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassTransposition(0,2,1,2),ClassTransposition(0,3,1,3));;[0X
    [4Xgap> IsomorphismPermGroup(G);[0X
    [4X[ ClassTransposition(0,2,1,2), ClassTransposition(0,3,1,3) ] -> [0X
    [4X[ (1,2)(3,4)(5,6), (1,2)(4,5) ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  Next  we say a few words about the membership test for rcwa groups. For tame
  rcwa  groups,  membership  or non-membership can always be decided. For wild
  groups,  membership  or non-membership can very often be decided quite quick
  as  well,  but  not  always. On Info level 2 of [10XInfoRCWA[0X the membership test
  provides information on reasons why the given rcwa permutation is an element
  of the given rcwa group or not.
  
  The  direct  product  of  two  free  groups  of  rank 2  can  faithfully  be
  represented  as  an  rcwa  group.  According to [Mih58] this implies that in
  general   the   membership   problem  for  rcwa  groups  is  algorithmically
  undecidable.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassShift(0,3),ClassTransposition(0,3,2,6));;[0X
    [4Xgap> ClassShift(2,6)^7*ClassTransposition(0,3,2,6)*ClassShift(0,3)^-3 in G;[0X
    [4Xtrue[0X
    [4Xgap> ClassShift(0,1) in G;[0X
    [4Xfalse[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  The  conjugacy  problem for rcwa groups is difficult, and [5XRCWA[0X provides only
  methods to solve it in some reasonably easy cases.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> IsConjugate(RCWA(Integers),ClassTransposition(0,2,1,4),ClassShift(0,1));[0X
    [4Xfalse[0X
    [4Xgap> IsConjugate(CT(Integers),ClassTransposition(0,2,1,6),[0X
    [4X>                             ClassTransposition(1,4,0,8));[0X
    [4Xtrue[0X
    [4Xgap> g := RepresentativeAction(CT(Integers),ClassTransposition(0,2,1,6),[0X
    [4X>                                           ClassTransposition(1,4,0,8));[0X
    [4X<bijective rcwa mapping of Z with modulus 48>[0X
    [4Xgap> ClassTransposition(0,2,1,6)^g = ClassTransposition(1,4,0,8);[0X
    [4Xtrue[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  The  number  of  conjugacy  classes of RCWA(Z) of elements of given order is
  known,  cp.  Corollary 2.7.1 (b)  in [Koh05].  It  can  be determined by the
  function [10XNrConjugacyClassesOfRCWAZOfOrder[0X:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> List([2,105],NrConjugacyClassesOfRCWAZOfOrder);[0X
    [4X[ infinity, 218 ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  There  is a property [10XIsTame[0X which indicates whether an rcwa group is tame or
  not:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassTransposition(0,2,1,4),ClassShift(1,3));;[0X
    [4Xgap> H := Group(ClassTransposition(0,2,1,6),ClassShift(1,3));;[0X
    [4Xgap> IsTame(G);[0X
    [4Xtrue[0X
    [4Xgap> IsTame(H);[0X
    [4Xfalse[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  For  tame  rcwa  groups,  there  are  methods  for  [10XIsSolvable[0X and [10XIsPerfect[0X
  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 [10XIsomorphismMatrixGroup[0X. 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  [10XExponent[0X available, which works
  basically for any rcwa group.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassTransposition(0,2,1,4),ClassShift(1,2));;[0X
    [4Xgap> IsPerfect(G);[0X
    [4Xfalse[0X
    [4Xgap> IsSolvable(G);[0X
    [4Xtrue[0X
    [4Xgap> D1 := DerivedSubgroup(G);; D2 := DerivedSubgroup(D1);;[0X
    [4Xgap> IsAbelian(D2);[0X
    [4Xtrue[0X
    [4Xgap> Index(G,D1); Index(D1,D2);[0X
    [4Xinfinity[0X
    [4X9[0X
    [4Xgap> StructureDescription(G); StructureDescription(D1);[0X
    [4X"(Z x Z x Z) . S3"[0X
    [4X"(Z x Z) . C3"[0X
    [4Xgap> Q := D1/D2;[0X
    [4XGroup([ (), (1,2,4)(3,5,7)(6,8,9), (1,3,6)(2,5,8)(4,7,9) ])[0X
    [4Xgap> StructureDescription(Q); [0X
    [4X"C3 x C3"[0X
    [4Xgap> Exponent(G);[0X
    [4Xinfinity[0X
    [4Xgap> phi := IsomorphismMatrixGroup(G);;[0X
    [4Xgap> Display(Image(phi,ClassTransposition(0,2,1,4)));[0X
    [4X[ [     0,     0,   1/2,  -1/2,     0,     0 ], [0X
    [4X  [     0,     0,     0,     1,     0,     0 ], [0X
    [4X  [     2,     1,     0,     0,     0,     0 ], [0X
    [4X  [     0,     1,     0,     0,     0,     0 ], [0X
    [4X  [     0,     0,     0,     0,     1,     0 ], [0X
    [4X  [     0,     0,     0,     0,     0,     1 ] ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  When  investigating  a  group,  a  basic task is to find relations among the
  generators:
  
  [1X3.2-2 EpimorphismFromFpGroup[0X
  
  [2X> EpimorphismFromFpGroup( [0X[3XG, r[0X[2X ) _____________________________________[0Xmethod
  [6XReturns:[0X  An  epimorphism  from  a  finitely  presented  group  to  the rcwa
            group [3XG[0X.
  
  The  argument [3Xr[0X is the "search radius", i.e. the radius of the ball around 1
  which  is  scanned  for  relations.  In  general, the larger [3Xr[0X is chosen the
  smaller the kernel of the returned epimorphism is. If the group [3XG[0X has finite
  presentations,  the  kernel will in principle get trivial provided that [3Xr[0X is
  chosen large enough.
  
  Both  the  performance  and  the  returned epimorphism depend on whether the
  package [5XFR[0X [Bar07] is present or not.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> a := ClassTransposition(2,4,3,4 :Name:="a");;[0X
    [4Xgap> b := ClassTransposition(4,6,8,12:Name:="b");;[0X
    [4Xgap> c := ClassTransposition(3,4,4,6 :Name:="c");;[0X
    [4Xgap> G := Group(a,b,c);[0X
    [4X<rcwa group over Z with 3 generators>[0X
    [4Xgap> phi := EpimorphismFromFpGroup(G,6);[0X
    [4X[ a, b, c ] -> [ a, b, c ][0X
    [4Xgap> RelatorsOfFpGroup(Source(phi));[0X
    [4X[ a^2, b^2, c^2, c*b*c*b*c*b, c*b*c*a*c*b*c*a*c*b*c*a, [0X
    [4X  b*a*b*a*b*a*b*a*b*a*b*a ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  A related very common task is to factor group elements into generators:
  
  [1X3.2-3 PreImagesRepresentative[0X
  
  [2X> PreImagesRepresentative( [0X[3Xphi, g[0X[2X ) __________________________________[0Xmethod
  [6XReturns:[0X  A   representative   of  the  set  of  preimages  of [3Xg[0X  under  the
            epimorphism [3Xphi[0X from a free group to an rcwa group.
  
  The  epimorphism  [3Xphi[0X  must  map  the  generators  of  the free group to the
  generators of the rcwa group one-by-one.
  
  This  method  can  be  used  for  factoring  elements  of  rcwa  groups into
  generators. The implementation is based on [10XRepresentativeActionPreImage[0X, see
  [2XRepresentativeAction[0X ([14X3.3-4[0X).
  
  Quite  frequently,  computing several preimages is not harder than computing
  just  one,  i.e.  often  several  preimages  are  found  simultaneously. The
  operation  [10XPreImagesRepresentatives[0X  takes  care  of this. It takes the same
  arguments  as  [10XPreImagesRepresentative[0X  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 [3Xphi[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; SetName(a,"a");[0X
    [4Xgap> b := ClassShift(0,1:Name:="b");;[0X
    [4Xgap> G := Group(a,b);; # G = <<Collatz permutation>, n -> n + 1>[0X
    [4Xgap> phi := EpimorphismFromFreeGroup(G);;[0X
    [4Xgap> g := Comm(a^2*b^4,a*b^3); # a sample element to be factored[0X
    [4X<bijective rcwa mapping of Z with modulus 8>[0X
    [4Xgap> PreImagesRepresentative(phi,g); # -> a factorization of g[0X
    [4Xb^-4*a^-1*b^-1*a^-1*b^3*a*b^-1*a*b^3[0X
    [4Xgap> g = b^-4*a^-1*b^-1*a^-1*b^3*a*b^-1*a*b^3; # check[0X
    [4Xtrue[0X
    [4Xgap> g := Comm(a*b,Comm(a,b^3));[0X
    [4X<bijective rcwa mapping of Z with modulus 8>[0X
    [4Xgap> pre := PreImagesRepresentatives(phi,g);[0X
    [4X[ b^-1*a^-1*b^-1*a^-1*b^3*a*b*a*b^-2, b^-1*a^-1*b*a^-1*b^3*a*b^-1*a*b^-2 ][0X
    [4Xgap> rel := CyclicallyReducedWord(pre[1]/pre[2]); # -> a nontrivial relation[0X
    [4Xb^-1*a^-1*b^3*a*b^2*a^-1*b^-3*a*b^-1[0X
    [4Xgap> rel^phi;[0X
    [4XIdentityMapping( Integers )[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X3.3 The natural action of an rcwa group on the underlying ring[0X
  
  Knowing  a  natural  permutation  representation  of  a  group usually helps
  significantly  in  computing  with  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 [5XRCWA[0X's functionality
  related to this action.
  
  The  support,  i.e.  the  set  of  moved  points,  of  an  rcwa group can be
  determined by [10XSupport[0X or [10XMovedPoints[0X (these are synonyms). There are methods
  to compute orbits under the action of an rcwa group:
  
  
  [1X3.3-1 Orbit (for an rcwa group and either a point or a set)[0X
  
  [2X> Orbit( [0X[3XG, point[0X[2X ) __________________________________________________[0Xmethod
  [2X> Orbit( [0X[3XG, set[0X[2X ) ____________________________________________________[0Xmethod
  [6XReturns:[0X  The  orbit  of  the point [3Xpoint[0X respectively the set [3Xset[0X under the
            natural action of the rcwa group [3XG[0X on its underlying ring.
  
  The  second  argument can either be an element or a subset of the underlying
  ring  of  the rcwa group [3XG[0X. 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.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassShift(0,2),ClassTransposition(0,3,1,3));[0X
    [4X<rcwa group over Z with 2 generators>[0X
    [4Xgap> Orbit(G,0);[0X
    [4XZ \ 5(6)[0X
    [4Xgap> Orbit(G,5);[0X
    [4X[ 5 ][0X
    [4Xgap> Orbit(G,ResidueClass(0,2));[0X
    [4X[ 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), [0X
    [4X  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), [0X
    [4X  1(3) U 2(6) ][0X
    [4Xgap> G := Group(ClassTransposition(0,2,1,2),ClassTransposition(0,2,1,4),[0X
    [4X>               ClassReflection(0,3));[0X
    [4X<rcwa group over Z with 3 generators>[0X
    [4Xgap> orb1 := Orbit(G,2); orb2 := Orbit(G,999);[0X
    [4X<orbit of 2 under <wild rcwa group over Z with 3 generators>>[0X
    [4X<orbit of 999 under <wild rcwa group over Z with 3 generators>>[0X
    [4Xgap> 1 in orb1;[0X
    [4Xfalse[0X
    [4Xgap> 1015808 in orb1;[0X
    [4Xtrue[0X
    [4Xgap> orb1 = orb2;[0X
    [4Xtrue[0X
    [4Xgap> First(orb1,n->ForAll([n,n+2,n+6,n+8,n+30,n+32,n+36,n+38],IsPrime));[0X
    [4X-19[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [5XRCWA[0X  permits  drawing  pictures  of  orbits  of  rcwa  groups  on Z^2,  see
  Section [14X3.6[0X.  Testing  for  transitivity  on  the  underlying  ring is often
  feasible:
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassTransposition(1,2,0,4),ClassShift(0,2));;[0X
    [4Xgap> IsTransitive(G,Integers);[0X
    [4Xtrue[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  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:
  
  
  [1X3.3-2 ShortOrbits (for rcwa groups) & ShortCycles (for rcwa permutations)[0X
  
  [2X> ShortOrbits( [0X[3XG, S, maxlng[0X[2X ) _____________________________________[0Xoperation
  [2X> ShortCycles( [0X[3Xg, S, maxlng[0X[2X ) _____________________________________[0Xoperation
  [2X> ShortCycles( [0X[3Xg, maxlng[0X[2X ) ________________________________________[0Xoperation
  [6XReturns:[0X  In  the first form a list of all finite orbits of the rcwa group [3XG[0X
            of  length  at  most  [3Xmaxlng[0X which intersect nontrivially with the
            set [3XS[0X.
  
            In  the second form a list of all cycles of the rcwa permutation [3Xg[0X
            of  length  at  most [3Xmaxlng[0X  which intersect nontrivially with the
            set [3XS[0X.
  
            In  the  third form a list of all cycles of the rcwa permutation [3Xg[0X
            of  length  at  most  [3Xmaxlng[0X  which  do  not  correspond to cycles
            consisting of residue classes.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassTransposition(1,4,2,4)*ClassTransposition(1,4,3,4),[0X
    [4X>               ClassTransposition(3,9,6,18)*ClassTransposition(1,6,3,9));;[0X
    [4Xgap> List(ShortOrbits(G,[-15..15],100),orb->StructureDescription(Action(G,orb)));[0X
    [4X[ "A15", "A4", "1", "1", "C3", "1", "((C2 x C2 x C2) : C7) : C3", "1", "1", [0X
    [4X  "C3", "A19" ][0X
    [4Xgap> ShortCycles(mKnot(7),[1..100],20);[0X
    [4X[ [ 1 ], [ 2 ], [ 3 ], [ 4 ], [ 5 ], [ 6 ], [ 7, 8 ], [ 9, 10 ], [ 11, 12 ], [0X
    [4X  [ 13, 14, 16, 18, 20, 22, 19, 17, 15 ], [ 21, 24 ], [ 23, 26 ], [0X
    [4X  [ 25, 28, 32, 36, 31, 27, 30, 34, 38, 33, 29 ], [ 35, 40 ], [0X
    [4X  [ 37, 42, 48, 54, 47, 41, 46, 52, 45, 39, 44, 50, 43 ], [0X
    [4X  [ 77, 88, 100, 114, 130, 148, 127, 109, 124, 107, 122, 105, 120, 103, 89 ] ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  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:
  
  
  [1X3.3-3  Ball  (for  group,  element  and  radius  or group, point, radius and[0X
  [1Xaction)[0X
  
  [2X> Ball( [0X[3XG, g, r[0X[2X ) ____________________________________________________[0Xmethod
  [2X> Ball( [0X[3XG, p, r, action[0X[2X ) ____________________________________________[0Xmethod
  [6XReturns:[0X  The  ball  of  radius [3Xr[0X  around  the  element [3Xg[0X  in  the  group [3XG[0X,
            respectively  the  ball  of  radius [3Xr[0X around the point [3Xp[0X under the
            action [3Xaction[0X of the group [3XG[0X.
  
  All balls are understood with respect to [10XGeneratorsOfGroup([3XG[0X)[0X. As membership
  tests can be expensive, the former method does not check whether [3Xg[0X is indeed
  an  element  of [3XG[0X. The methods require that element- / point comparisons are
  cheap. They are not only applicable to rcwa groups. If the option [3XSpheres[0X is
  set, the ball is splitted up and returned as a list of spheres.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> PSL2Z := Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(2),[0X
    [4X>                                                    CyclicGroup(3))));;[0X
    [4Xgap> List([1..10],k->Length(Ball(PSL2Z,[0,1],k,OnTuples)));[0X
    [4X[ 4, 8, 14, 22, 34, 50, 74, 106, 154, 218 ][0X
    [4Xgap> Ball(Group((1,2),(2,3),(3,4)),(),2:Spheres);[0X
    [4X[ [ () ], [ (3,4), (2,3), (1,2) ],[0X
    [4X  [ (2,3,4), (2,4,3), (1,2)(3,4), (1,2,3), (1,3,2) ] ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  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:
  
  [1X3.3-4 RepresentativeAction[0X
  
  [2X> RepresentativeAction( [0X[3XG, source, destination, action[0X[2X ) _____________[0Xmethod
  [6XReturns:[0X  An  element of [3XG[0X which maps [3Xsource[0X to [3Xdestination[0X under the action
            given by [3Xaction[0X.
  
  If  an  element satisfying this condition does not exist, this method either
  returns  [10Xfail[0X  or runs into an infinite loop. The problem whether [3Xsource[0X and
  [3Xdestination[0X  lie in the same orbit under the action [3Xaction[0X of [3XG[0X is hard, and
  in its general form most likely computationally undecidable.
  
  In  cases  where  rather a word in the generators of [3XG[0X than the actual group
  element is needed, one should use the operation [10XRepresentativeActionPreImage[0X
  instead. This operation takes five arguments. The first four are the same as
  those  of  [10XRepresentativeAction[0X,  and  the  fifth  is  a  free  group  whose
  generators  are  to  be  used  as  letters  of  the returned word. Note that
  [10XRepresentativeAction[0X  calls  [10XRepresentativeActionPreImage[0X  and evaluates the
  returned  word.  The  evaluation  of the word can very well take most of the
  time if [3XG[0X is wild and coefficient explosion occurs.
  
  The algorithm is based on computing balls of increasing radius around [3Xsource[0X
  and [3Xdestination[0X until they intersect nontrivially.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; SetName(a,"a");[0X
    [4Xgap> b := ClassShift(1,4:Name:="b");; G := Group(a,b);;[0X
    [4Xgap> elm := RepresentativeAction(G,[7,4,9],[4,5,13],OnTuples);;[0X
    [4Xgap> Display(elm);[0X
    [4X[0X
    [4XBijective rcwa mapping of Z with modulus 12[0X
    [4X[0X
    [4X               n mod 12                |                 n^f[0X
    [4X---------------------------------------+--------------------------------------[0X
    [4X   0  2  3  6  8 11                    | n[0X
    [4X   1  7 10                             | n - 3[0X
    [4X   4                                   | n + 1[0X
    [4X   5  9                                | n + 4[0X
    [4X[0X
    [4Xgap> List([7,4,9],n->n^elm);[0X
    [4X[ 4, 5, 13 ][0X
    [4Xgap> elm := RepresentativeAction(G,[6,-3,8],[-9,4,11],OnPoints);;[0X
    [4Xgap> Display(elm);[0X
    [4X[0X
    [4XBijective rcwa mapping of Z with modulus 12[0X
    [4X[0X
    [4X               n mod 12                |                 n^f[0X
    [4X---------------------------------------+--------------------------------------[0X
    [4X   0  3  6                             | 2n/3[0X
    [4X   1                                   | (2n - 8)/3[0X
    [4X   2  8 11                             | (4n + 1)/3[0X
    [4X   4  7 10                             | (4n - 1)/3[0X
    [4X   5                                   | (4n - 17)/3[0X
    [4X   9                                   | (4n - 15)/3[0X
    [4X[0X
    [4Xgap> [6,-3,8]^elm; List([6,-3,8],n->n^elm); # `OnPoints' permits reordering.[0X
    [4X[ -9, 4, 11 ][0X
    [4X[ 4, -9, 11 ][0X
    [4Xgap> F := FreeGroup("a","b");; phi := EpimorphismByGenerators(F,G);;[0X
    [4Xgap> w := RepresentativeActionPreImage(G,[10,-4,9,5],[4,5,13,-8],OnTuples,F);[0X
    [4Xa*b^-1*a^-1*b^-1*a*b^-1*a*b*a*b^-2*a*b*a^-1*b[0X
    [4Xgap> elm := w^phi;[0X
    [4X<bijective rcwa mapping of Z with modulus 324>[0X
    [4Xgap> List([10,-4,9,5],n->n^elm);[0X
    [4X[ 4, 5, 13, -8 ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  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:
  
  [1X3.3-5 Projections[0X
  
  [2X> Projections( [0X[3XG, m[0X[2X ) _____________________________________________[0Xoperation
  [6XReturns:[0X  The  projections  of  the  rcwa  group [3XG[0X  to the unions of residue
            classes (mod [3Xm[0X) which it fixes setwise.
  
  The  corresponding  partition  of  a  set of representatives for the residue
  classes (mod [3Xm[0X) can be obtained by the operation [10XOrbitsModulo([3XG[0X,[3Xm[0X)[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassTransposition(0,2,1,2),ClassShift(3,4));;[0X
    [4Xgap> Projections(G,4);[0X
    [4X[ [ ClassTransposition(0,2,1,2), ClassShift(3,4) ] ->[0X
    [4X    [ <bijective rcwa mapping of Z with modulus 4>,[0X
    [4X      IdentityMapping( Integers ) ],[0X
    [4X  [ ClassTransposition(0,2,1,2), ClassShift(3,4) ] ->[0X
    [4X    [ <bijective rcwa mapping of Z with modulus 4>,[0X
    [4X      <bijective rcwa mapping of Z with modulus 4> ] ][0X
    [4Xgap> List(last,phi->Support(Image(phi)));[0X
    [4X[ 0(4) U 1(4), 2(4) U 3(4) ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  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:
  
  [1X3.3-6 RepresentativeAction[0X
  
  [2X> RepresentativeAction( [0X[3XRCWA(R), P1, P2[0X[2X ) ____________________________[0Xmethod
  [6XReturns:[0X  An element of RCWA(R) which maps the partition [3XP1[0X to [3XP2[0X.
  
  The arguments [3XP1[0X and [3XP2[0X must be partitions of the underlying ring R into the
  same  number  of  unions of residue classes. The method for R = Z recognizes
  the option [10XIsTame[0X, which can be used to demand a tame result. If this option
  is set and there is no tame rcwa permutation which maps [3XP1[0X to [3XP2[0X, the method
  runs  into  an infinite loop. This happens if the condition in Theorem 2.8.9
  in [Koh05]  is  not  satisfied.  If  the  option  [10XIsTame[0X  is not set and the
  partitions  [3XP1[0X  and [3XP2[0X both consist entirely of single residue classes, then
  the returned mapping is affine on any residue class in [3XP1[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> P1 := AllResidueClassesModulo(3);[0X
    [4X[ 0(3), 1(3), 2(3) ][0X
    [4Xgap> P2 := List([[0,2],[1,4],[3,4]],ResidueClass);[0X
    [4X[ 0(2), 1(4), 3(4) ][0X
    [4Xgap> elm := RepresentativeAction(RCWA(Integers),P1,P2);[0X
    [4X<bijective rcwa mapping of Z with modulus 3>[0X
    [4Xgap> P1^elm = P2;[0X
    [4Xtrue[0X
    [4Xgap> IsTame(elm);[0X
    [4Xfalse[0X
    [4Xgap> elm := RepresentativeAction(RCWA(Integers),P1,P2:IsTame);[0X
    [4X<tame bijective rcwa mapping of Z with modulus 24>[0X
    [4Xgap> P1^elm = P2;[0X
    [4Xtrue[0X
    [4Xgap> elm := RepresentativeAction(RCWA(Integers),[0X
    [4X>             [ResidueClass(1,3),Union(ResidueClass(0,3),ResidueClass(2,3))],[0X
    [4X>             [Union(ResidueClass(2,5),ResidueClass(4,5)),[0X
    [4X>              Union(ResidueClass(0,5),ResidueClass(1,5),ResidueClass(3,5))]);[0X
    [4X<bijective rcwa mapping of Z with modulus 6>[0X
    [4Xgap> [ResidueClass(1,3),Union(ResidueClass(0,3),ResidueClass(2,3))]^elm;[0X
    [4X[ 2(5) U 4(5), Z \ 2(5) U 4(5) ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X3.4 Special attributes of tame residue-class-wise affine groups[0X
  
  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 [10XIsSolvable[0X, [10XIsPerfect[0X and [10XDerivedSubgroup[0X 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.
  
  
  [1X3.4-1 RespectedPartition (of a tame rcwa group or -permutation)[0X
  
  [2X> RespectedPartition( [0X[3XG[0X[2X ) _________________________________________[0Xattribute
  [2X> RespectedPartition( [0X[3Xg[0X[2X ) _________________________________________[0Xattribute
  [6XReturns:[0X  A  respected  partition  of  the  rcwa  group  [3XG[0X  /  of  the  rcwa
            permutation [3Xg[0X.
  
  A  tame  element  g in RCWA(R)  permutes a partition of R into finitely many
  residue  classes  on  all  of  which  it  is  affine.  Given  a  tame  group
  G < RCWA(R), there is a common such partition for all elements of G. We call
  the mentioned partitions [13Xrespected partitions[0X of g or G, respectively.
  
  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 2.5.8
  in [Koh05], depending on how one introduces the notion of tameness.
  
  Related  attributes  are [10XRespectedPartitionShort[0X and [10XRespectedPartitionLong[0X.
  The  first  of  these  denotes  a  respected partition consisting of residue
  classes r(m) where m divides the modulus of [3XG[0X or [3Xg[0X, respectively. The second
  denotes  a  respected partition consisting of residue classes r(m) where the
  modulus of [3XG[0X (respectively [3Xg[0X) divides m.
  
  There is an operation [10XRespectsPartition([3XG[0X,[3XP[0X)[0X / [10XRespectsPartition([3Xg[0X,[3XP[0X)[0X, which
  tests  whether  [3XG[0X or [3Xg[0X respects a given partition [3XP[0X. The permutation induced
  by [3Xg[0X on [10XP[0X can be computed efficiently by [10XPermutationOpNC([3Xg[0X,P,OnPoints)[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassTransposition(0,4,1,6),ClassShift(0,2));[0X
    [4X<rcwa group over Z with 2 generators>[0X
    [4Xgap> IsTame(G);[0X
    [4Xtrue[0X
    [4Xgap> Size(G);[0X
    [4Xinfinity[0X
    [4Xgap> P := RespectedPartition(G);[0X
    [4X[ 3(6), 5(6), 0(8), 2(8), 4(8), 6(8), 1(12), 7(12) ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X3.4-2 ActionOnRespectedPartition & KernelOfActionOnRespectedPartition[0X
  
  [2X> ActionOnRespectedPartition( [0X[3XG[0X[2X ) _________________________________[0Xattribute
  [2X> KernelOfActionOnRespectedPartition( [0X[3XG[0X[2X ) _________________________[0Xattribute
  [6XReturns:[0X  The  action  of  the tame rcwa group [3XG[0X on [10XRespectedPartition([3XG[0X)[0X or
            the kernel of this action, respectively.
  
  The   method   for   [10XKernelOfActionOnRespectedPartition[0X   uses  the  package
  [5XPolycyclic[0X [EN06].  The  rank  of  the  largest free abelian subgroup of the
  kernel  of the action of [3XG[0X on its stored respected partition can be computed
  by [10XRankOfKernelOfActionOnRespectedPartition([3XG[0X)[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassTransposition(0,4,1,6),ClassShift(0,2));;[0X
    [4Xgap> H := ActionOnRespectedPartition(G);[0X
    [4XGroup([ (3,7)(5,8), (3,4,5,6) ])[0X
    [4Xgap> H = Action(G,P);[0X
    [4Xtrue[0X
    [4Xgap> Size(H);[0X
    [4X48[0X
    [4Xgap> K := KernelOfActionOnRespectedPartition(G);[0X
    [4X<rcwa group over Z with 3 generators>[0X
    [4Xgap> RankOfKernelOfActionOnRespectedPartition(G);[0X
    [4X3[0X
    [4Xgap> Index(G,K);[0X
    [4X48[0X
    [4Xgap> List(GeneratorsOfGroup(K),Factorization);[0X
    [4X[ [ ClassShift(0,4)^2 ], [ ClassShift(2,4)^2 ], [ ClassShift(1,6)^2 ] ][0X
    [4Xgap> Image(IsomorphismPcpGroup(K));[0X
    [4XPcp-group with orders [ 0, 0, 0 ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  Let  G  be  a  tame rcwa group over Z, let mathcalP be a respected partition
  of G and put m := |mathcalP|. Then there is an rcwa permutation g which maps
  mathcalP  to  the  partition  of Z into the residue classes (mod m), and the
  conjugate  G^g  of G  under  such  a  permutation  is integral (cp. [Koh05],
  Theorem 2.5.14).
  
  The  conjugate G^g can be determined by the operation [10XIntegralConjugate[0X, and
  the   conjugating   permutation g   can   be  determined  by  the  operation
  [10XIntegralizingConjugator[0X. Both operations are applicable to rcwa permutations
  as  well.  Note  that  a  tame  rcwa  group  does not determine its integral
  conjugate uniquely.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> G := Group(ClassTransposition(0,4,1,6),ClassShift(0,2));;[0X
    [4Xgap> G^IntegralizingConjugator(G) = IntegralConjugate(G);[0X
    [4Xtrue[0X
    [4Xgap> RespectedPartition(G);[0X
    [4X[ 3(6), 5(6), 0(8), 2(8), 4(8), 6(8), 1(12), 7(12) ][0X
    [4Xgap> RespectedPartition(G)^IntegralizingConjugator(G);[0X
    [4X[ 0(8), 1(8), 2(8), 3(8), 4(8), 5(8), 6(8), 7(8) ][0X
    [4Xgap> last = RespectedPartition(IntegralConjugate(G));[0X
    [4Xtrue[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X3.5 Generating pseudo-random elements of RCWA(R) and CT(R)[0X
  
  There  are  methods  for  the  operation [10XRandom[0X for RCWA(R) and CT(R). These
  methods  are designed to be suitable for generating interesting examples. No
  particular distribution is guaranteed.
  
  [4X-----------------------------  Log  ------------------------------[0X
    [4X[0X
    [4Xgap> elm := Random(RCWA(Integers));;[0X
    [4Xgap> Display(elm);[0X
    [4X[0X
    [4XBijective rcwa mapping of Z with modulus 12[0X
    [4X[0X
    [4X               n mod 12                |                 n^f[0X
    [4X---------------------------------------+--------------------------------------[0X
    [4X   0  2  4  6  8 10                    | 3n + 2[0X
    [4X   1  5  9                             | -n + 2[0X
    [4X   3  7                                | (n - 7)/2[0X
    [4X  11                                   | (-n + 20)/3[0X
    [4X[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  The  elements  which are returned by this method are obtained by multiplying
  class    shifts   (see   [2XClassShift[0X   ([14X2.2-1[0X)),   class   reflections   (see
  [2XClassReflection[0X  ([14X2.2-2[0X))  and  class transpositions (see [2XClassTransposition[0X
  ([14X2.2-3[0X)). These factors can be retrieved by factoring:
  
  [4X-----------------------------  Log  ------------------------------[0X
    [4X[0X
    [4Xgap> Factorization(elm);[0X
    [4X[ ClassTransposition(0,2,3,4), ClassTransposition(3,4,4,6),[0X
    [4X  ClassShift(0,2)^-1, ClassReflection(3,4), ClassReflection(1,4) ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  There  is  an  auxiliary  function [10XClassPairs([[3XR[0X,] [3Xm[0X)[0X, which is used in this
  context.  In its one-argument form, this function returns a list of 4-tuples
  (r_1,m_1,r_2,m_2)  of  integers  corresponding  to  the  unordered  pairs of
  disjoint  residue  classes  r_1(m_1) and r_2(m_2) with m_1, m_2 <= m. In its
  two-argument form, it does "the equivalent" for the ring [3XR[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> List(ClassPairs(4),ClassTransposition);[0X
    [4X[ ClassTransposition(0,2,1,2), ClassTransposition(0,2,1,4),[0X
    [4X  ClassTransposition(0,2,3,4), ClassTransposition(0,3,1,3),[0X
    [4X  ClassTransposition(0,3,2,3), ClassTransposition(0,4,1,4),[0X
    [4X  ClassTransposition(0,4,2,4), ClassTransposition(0,4,3,4),[0X
    [4X  ClassTransposition(1,2,0,4), ClassTransposition(1,2,2,4),[0X
    [4X  ClassTransposition(1,3,2,3), ClassTransposition(1,4,2,4),[0X
    [4X  ClassTransposition(1,4,3,4), ClassTransposition(2,4,3,4) ][0X
    [4Xgap> List(last,TransposedClasses);[0X
    [4X[ [ 0(2), 1(2) ], [ 0(2), 1(4) ], [ 0(2), 3(4) ], [ 0(3), 1(3) ],[0X
    [4X  [ 0(3), 2(3) ], [ 0(4), 1(4) ], [ 0(4), 2(4) ], [ 0(4), 3(4) ],[0X
    [4X  [ 1(2), 0(4) ], [ 1(2), 2(4) ], [ 1(3), 2(3) ], [ 1(4), 2(4) ],[0X
    [4X  [ 1(4), 3(4) ], [ 2(4), 3(4) ] ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X3.6 Drawing pictures of orbits on Z^2[0X
  
  [5XRCWA[0X  permits drawing pictures of orbits of rcwa groups on Z^2. 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 produced
  pictures can be processed further with many common graphics programs.
  
  [1X3.6-1 DrawOrbitPicture[0X
  
  [2X> DrawOrbitPicture( [0X[3XG, p0, r, h, w, colored, palette, filename[0X[2X ) ___[0Xfunction
  [6XReturns:[0X  Nothing.
  
  Draws  a  picture of the orbit(s) of the point(s) [3Xp0[0X under the action of the
  group [3XG[0X on Z^2. The argument [3Xp0[0X is either one point or a list of points. The
  argument [3Xr[0X denotes the radius of the ball around [3Xp0[0X to be computed. The size
  of  the  created  picture is [3Xh[0X x [3Xw[0X pixels. The argument [3Xcolored[0X is a boolean
  which  indicates whether a 24-bit True-Color picture or a monochrome picture
  should  be  drawn.  In the former case, [3Xpalette[0X must be a list of triples of
  integers  in the range 0, dots, 255, denoting the RGB values of colors to be
  used.  In the latter case, [3Xpalette[0X is not used, and any value can be passed.
  The picture is written in bitmap- (bmp-) format to a file named [3Xfilename[0X.
  
  [4X-----------------------------  Log  ------------------------------[0X
    [4X[0X
    [4Xgap> PSL2Z := Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(2),[0X
    [4X>                                                    CyclicGroup(3))));;[0X
    [4Xgap> DrawOrbitPicture(PSL2Z,[0,1],20,512,512,false,fail,"~/images/example1.bmp");[0X
    [4Xgap> DrawOrbitPicture(PSL2Z,Combinations([1..4],2),20,512,512,true,[0X
    [4X>                     [[255,0,0],[0,255,0],[0,0,255]],"~/images/example2.bmp");[0X
    [4Xgap> G := Group(ClassShift(0,1),ClassTransposition(1,2,0,4));;[0X
    [4Xgap> DrawOrbitPicture(G,[0,1],20,512,512,true,[0X
    [4X>                     List([1..20],i->[255-12*i,255-12*i,255]),[0X
    [4X>                     "~/images/example3.bmp");[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [2XDrawOrbitPicture[0X makes use of the following utility function:
  
  [1X3.6-2 SaveAsBitmapPicture[0X
  
  [2X> SaveAsBitmapPicture( [0X[3Xpicture, filename[0X[2X ) _________________________[0Xfunction
  [6XReturns:[0X  Nothing.
  
  Writes  the  pixel  matrix  [3Xpicture[0X  to  a bitmap- (bmp-) picture file named
  [3Xfilename[0X.  The  filename  should  include  the entire pathname. The argument
  [3Xpicture[0X  can  be  a GF(2) matrix, in which case a monochrome picture file is
  generated.  In  this  case,  zeros stand for black pixels and ones stand for
  white  pixels.  The argument [3Xpicture[0X can also be an integer matrix, in which
  case  a  24-bit  True  Color  picture  file  is generated. In this case, the
  entries  of  the  matrix are supposed to be integers n = 65536 * red + 256 *
  green  +  blue in the range 0, dots, 2^24-1 specifying the RGB values of the
  colors of the pixels.
  
  The    picture    can    be   read   back   into   [5XGAP[0X   by   the   function
  [10XReadFromBitmapPicture([3Xfilename[0X)[0X.
  
  [4X-----------------------------  Log  ------------------------------[0X
    [4X[0X
    [4Xgap> color   := n->32*(n mod 8)+256*32*(Int(n/8) mod 8)+65536*32*Int(n/64);;[0X
    [4Xgap> picture := List([1..512],y->List([1..512],x->color(Gcd(x,y)-1)));;[0X
    [4Xgap> SaveAsBitmapPicture(picture,"~/images/gcd.bmp");[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  The pictures created in the examples are shown on [5XRCWA[0X's webpage.
  
  
  [1X3.7 Some general utility functions[0X
  
  [5XRCWA[0X  introduces  a couple of small utility functions which can be used in a
  more  general  context: The function [10XGeneratorsAndInverses([3XG[0X)[0X returns a list
  of  generators  of  [3XG[0X  and their inverses, [10XEpimorphismByGenerators([3XG[0X,[3XH[0X)[0X is a
  shorthand                 for                 [10XGroupHomomorphismByImages([3XG[0X,[3XH[0X,
  GeneratorsOfGroup([3XG[0X),GeneratorsOfGroup([3XH[0X))[0X  (there  is also an [10XNC[0X version of
  this),  the  function [10XListOfPowers([3Xg[0X,[3Xexp[0X)[0X returns the list [10X[[3Xg[0X,[3Xg[0X^2,...,[3Xg[0X^[3Xexp[0X][0X
  of  powers  of [3Xg[0X,  the  function  [10XAllProducts([3Xl[0X,[3Xk[0X)[0X  returns  the list of all
  products of [3Xk[0X entries of the list [3Xl[0X, the function [10XDifferencesList([3Xl[0X)[0X returns
  the  list  of  differences  of  consecutive  entries  of the list [3Xl[0X, and the
  function [10XFloatQuotients([3Xl[0X)[0X returns the list of floating point approximations
  of quotients of consecutive entries of the list [3Xl[0X.
  
  
  [1X3.8 The categories of residue-class-wise affine groups[0X
  
  [1X3.8-1 IsRcwaGroup[0X
  
  [2X> IsRcwaGroup( [0X[3XG[0X[2X ) ___________________________________________________[0Xfilter
  [2X> IsRcwaGroupOverZ( [0X[3XG[0X[2X ) ______________________________________________[0Xfilter
  [2X> IsRcwaGroupOverZ_pi( [0X[3XG[0X[2X ) ___________________________________________[0Xfilter
  [2X> IsRcwaGroupOverGFqx( [0X[3XG[0X[2X ) ___________________________________________[0Xfilter
  [6XReturns:[0X  [10Xtrue[0X  if  [3XG[0X  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 [10Xfalse[0X otherwise.
  
  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
  [10XIsRcwaGroupOverZOrZ_pi[0X   which   is   the   union  of  [10XIsRcwaGroupOverZ[0X  and
  [10XIsRcwaGroupOverZ_pi[0X.
  
  To  allow distinguishing the groups RCWA(R) and CT(R) from others, they have
  the characteristic property [10XIsNaturalRCWA[0X or [10XIsNaturalCT[0X, respectively.
  
