<!-- #################################################################### -->
<!-- ##                                                                ## -->
<!-- ##  rcwagrp.xml         RCWA documentation           Stefan Kohl  ## -->
<!-- ##                                                                ## -->
<!-- ##  $Id: rcwagrp.xml,v 1.113 2006/09/26 14:10:25 stefan Exp $     ## -->
<!-- ##                                                                ## -->
<!-- #################################################################### -->

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

This chapter describes the functionality provided by this package for
computing with residue class-wise affine groups.

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

<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>

Residue class-wise affine groups can be constructed using either
<C>Group</C>, <C>GroupByGenerators</C> or <C>GroupWithGenerators</C>
as usual, cp. the &GAP; reference manual.

<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>

<Index Key="View" Subkey="G"><C>View</C></Index>
<Index Key="Display" Subkey="G"><C>Display</C></Index>
<Index Key="Print" Subkey="G"><C>Print</C></Index>
<Index Key="String" Subkey="G"><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.
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 in the way described above. It is handled as a special case:

<ManSection>
  <Func Name="RCWA" Arg="R" Label="R"/>
  <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)
]]>
</Example>

<Alt Only="LaTeX">\pagebreak[4]</Alt>

<Example>
<![CDATA[
gap> One(RCWA_Z); Size(RCWA_Z); IsFinitelyGeneratedGroup(RCWA_Z);
IdentityMapping( Integers )
infinity
false
gap> IsSolvable(RCWA_Z) or IsPerfect(RCWA_Z);
false
gap> Centre(RCWA_Z);
Trivial rcwa group over Z
gap> IsSubgroup(RCWA_Z,G);
true
]]>
</Example>
  </Description>
</ManSection>

There is a method for the operation <C>Random</C> which
generates pseudo-random elements of RCWA(<M>\Z</M>) --
see Section&nbsp;<Ref Label="sec:Random"/>. <P/>

Another way of constructing an rcwa group is taking the image of an
rcwa representation:

<ManSection>
  <Attr Name="IsomorphismRcwaGroupOverZ" Arg="G" Label="G"/>
  <Attr Name="IsomorphismRcwaGroup" Arg="G" Label="G"/>
  <Returns>
    A monomorphism from the group <A>G</A> to&nbsp;RCWA(<M>\Z</M>).
  </Returns>
  <Description>
    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&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,<M>\mathbb{C}</M>) to RCWA(<M>\mathbb{Z}</M>). <P/>

    In case <A>G</A> is a finite-degree permutation group,
    the image under a specific embedding can be obtained by
    <C>RcwaGroupByPermGroup(<A>G</A>)</C>.
    <Index Key="RcwaGroupByPermGroup" Subkey="G">
      <C>RcwaGroupByPermGroup</C>
    </Index>
    The resulting group&nbsp;<C>H</C> satisfies the relation
    <C>Action(H&circum;ClassShift(0,1),[1..LargestMovedPoint(<A>G</A>)])
    =&nbsp;G</C>.
<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 ] -> [ <bijective rcwa mapping of Z with modulus 12>,
  <bijective rcwa mapping of Z with modulus 24>,
  <bijective rcwa mapping of Z with modulus 12>,
  <bijective rcwa mapping of Z with modulus 72>,
  <bijective rcwa mapping of Z with modulus 36> ]
gap> IsomorphismRcwaGroup(FreeGroup(2));
[ f1, f2 ] -> [ <wild bijective rcwa mapping of Z with modulus 8>,
  <wild bijective rcwa mapping of Z with modulus 8> ]
gap> F2 := Image(last);
<wild rcwa group over Z with 2 generators>
]]>
</Example>
  </Description>
</ManSection>

<Alt Only="LaTeX">\pagebreak[4]</Alt>

<ManSection>
  <Meth Name="StructureDescription" Arg="G" Label="G"/>
  <Returns>
    A string which describes the structure of the rcwa group&nbsp;<A>G</A>
    to some extent.
  </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 <M>(\Z,+)</M> 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 complicate 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.
<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>

</Section>

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

<Section Label="sec:DirectProductsAndWreathProducts">
<Heading>Direct products and wreath products</Heading>

The class of groups which can faithfully be represented as rcwa groups
is closed under forming direct products, wreath products with finite
groups and wreath products with the infinite cyclic group <M>(\Z,+)</M>.
For information on how direct products and wreath products of subgroups
of RCWA(<M>\Z</M>) are embedded in RCWA(<M>\Z</M>), see
Section&nbsp;<Ref Label="sec:RestrictionAndInduction"/> below.

<Alt Only="LaTeX">\pagebreak[4]</Alt>

<ManSection>
  <Meth Name="DirectProduct" Arg="G1, G2, ..." Label="G1, G2, ..."/>
  <Returns>
    An rcwa group isomorphic to the direct product of the rcwa groups
    over&nbsp;<M>\Z</M> given as arguments.
  </Returns>
  <Description>
    There is certainly no unique or canonical way to embed a direct
    product of rcwa groups into RCWA(<M>\Z</M>). 
    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="G, f"/>),
    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>
  <Meth Name="WreathProduct" Arg="G, P" Label="G, P"/>
  <Meth Name="WreathProduct" Arg="G, Z" Label="G, Z"/>
  <Returns>
    An rcwa group isomorphic to the wreath product of the rcwa
    group&nbsp;<A>G</A> over&nbsp;<M>\mathbb{Z}</M> with the finite
    permutation group&nbsp;<A>P</A>, resp. with the infinite cyclic
    group&nbsp;<A>Z</A>.
  </Returns>
  <Description>
    The first-mentioned method embeds the <C>DegreeAction(<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>DegreeAction(<A>P</A>)</C>.
    The second-mentioned method restricts
    (<M>\rightarrow</M>&nbsp;<Ref Oper="Restriction" Label="G, f"/>)
    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 bijective rcwa mapping of Z with modulus 8>,
  <wild bijective rcwa mapping of Z with modulus 8> ] ->
[ <wild bijective rcwa mapping of Z with modulus 40>,
  <wild bijective rcwa mapping of Z with modulus 40> ]
gap> Embedding(F2wrA5,2);
[ (1,2,3,4,5), (3,4,5) ] ->
[ <bijective rcwa mapping of Z with modulus 5, of order 5>,
  <bijective rcwa mapping of Z with modulus 5, of order 3> ]
gap> ZwrZ := WreathProduct(Group(ClassShift(0,1)),Group(ClassShift(0,1)));
<wild rcwa group over Z with 2 generators>
gap> Embedding(ZwrZ,1);
[ ClassShift(0,1) ] ->
[ <tame bijective rcwa mapping of Z with modulus 4, of order infinity> ]
gap> Embedding(ZwrZ,2);
[ ClassShift(0,1) ] -> [ <wild bijective rcwa mapping of Z with modulus 4> ]
]]>
</Example>
  </Description>
</ManSection>

</Section>

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

<Section Label="sec:MembershipTest">
<Heading>
  The membership test
</Heading>

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

There is a method for the operation <C>in</C>.
Given an rcwa group&nbsp;<C>G</C> and an rcwa mapping&nbsp;<C>g</C>, this
method tries to decide whether <C>g</C> is an element of&nbsp;<C>G</C> or
not. It can always decide this question if <C>G</C> is tame.
For wild groups this is sometimes not the case. On Info level&nbsp;2 of
<C>InfoRCWA</C> the method gives information on reasons why <C>g</C> is
an element of&nbsp;<C>G</C> or&nbsp;not. <P/>

The direct product of two free groups of rank&nbsp;2 can faithfully be
represented as an rcwa group. According to&nbsp;<Cite Key="Mihailova58"/>
this implies that in general the membership problem for rcwa groups is
algorithmically undecidable.

<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>

</Section>

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

<Section Label="sec:AttributesAndProperties">
<Heading>Basic attributes and properties of rcwa groups</Heading>

<Index Key="Size" Subkey="G"><C>Size</C></Index>
There is a method available for 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="G"/>)
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.

<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="Modulus" Subkey="G"><C>Modulus</C></Index>
<Index Key="Mod" Subkey="G"><C>Mod</C></Index>
<Index Key="ModulusOfRcwaGroup" Subkey="G"><C>ModulusOfRcwaGroup</C></Index>
<Index Key="Multiplier" Subkey="G"><C>Multiplier</C></Index>
<Index Key="Mult" Subkey="G"><C>Mult</C></Index>
<Index Key="Divisor" Subkey="G"><C>Divisor</C></Index>
<Index Key="Div" Subkey="G"><C>Div</C></Index>
<Index Key="PrimeSet" Subkey="G"><C>PrimeSet</C></Index>

Basic attributes derived from the affine partial mappings of the elements of
an rcwa group and their coefficients 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 in case such an lcm exists and 0 otherwise.
The <E>multiplier</E> resp. <E>divisor</E> of an rcwa group is the lcm
of the multipliers resp. 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> resp. <C>Divisor</C>. 
Technically, the modulus of an rcwa group is stored as an attribute
<C>ModulusOfRcwaGroup</C>. <P/>

<Index Key="rcwa group" Subkey="integral">rcwa group</Index>
<Index Key="rcwa group" Subkey="class-wise order-preserving">
  rcwa group
</Index>

<Index Key="IsTame" Subkey="G"><C>IsTame</C></Index>
<Index Key="IsIntegral" Subkey="G"><C>IsIntegral</C></Index>
<Index Key="IsClassWiseOrderPreserving" Subkey="G">
  <C>IsClassWiseOrderPreserving</C>
</Index>

A tame rcwa group, i.e. one with modulus&nbsp;0, has the property
<C>IsTame</C>. An rcwa group is called <E>integral</E> resp.
<E>class-wise order-preserving</E> if all of its elements are so.
There are corresponding methods available for <C>IsIntegral</C>
and <C>IsClassWiseOrderPreserving</C>.

<Example>
<![CDATA[
gap> g1 := RcwaMapping((1,2),[1..2]);;
gap> g2 := RcwaMapping((1,2,3),[1..3]);;
gap> g3 := RcwaMapping((1,2,3,4,5),[1..5]);;
gap> List([g1,g2,g3],Modulus);
[ 2, 3, 5 ]
gap> G := Group(g1,g2,g3);;
gap> Size(G);
265252859812191058636308480000000
gap> List([Modulus,Multiplier,Divisor,PrimeSet,
>          IsIntegral,IsClassWiseOrderPreserving],f->f(G));
[ 30, 1, 1, [ 2, 3, 5 ], true, true ]
]]>
</Example>

</Section>

<Alt Only="LaTeX">\pagebreak[4]</Alt>

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

<Section Label="sec:PermutationAndMatrixReps">
<Heading>
  Permutation- and matrix representations
</Heading>

<ManSection>
  <Meth Name="IsomorphismPermGroup" Arg="G" Label="G"/>
  <Returns>
    An isomorphism from the finite rcwa group&nbsp;<A>G</A> to
    a finite-degree permutation group.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> IsomorphismPermGroup(Group(ClassTransposition(0,2,1,2),
>                               ClassTransposition(0,3,1,3)));
[ ClassTransposition(0,2,1,2), ClassTransposition(0,3,1,3) ] -> 
[ (1,2)(3,4)(5,6), (1,2)(4,5) ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Attr Name="IsomorphismMatrixGroup" Arg="G" Label="G"/>
  <Returns>
    An isomorphism from the rcwa group&nbsp;<A>G</A> to a matrix group,
    provided that <A>G</A> embeds into a matrix group and that there is
    a suitable method available. Both conditions are fulfilled if
    <A>G</A> is tame.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> G := Group(ClassTransposition(0,2,1,4),ClassShift(2,4));
<rcwa group over Z with 2 generators>
gap> phi := IsomorphismMatrixGroup(G);;
gap> FieldOfMatrixGroup(Image(phi));
Rationals
gap> DegreeOfMatrixGroup(Image(phi));
10
gap> Display(GeneratorsOfGroup(Image(phi))[1]*One(GF(5)));
 . . . . . . 3 2 . .
 . . . . . . . 1 . .
 . . . . . . . . 3 2
 . . . . . . . . . 1
 . . . . 1 . . . . .
 . . . . . 1 . . . .
 2 1 . . . . . . . .
 . 1 . . . . . . . .
 . . 2 1 . . . . . .
 . . . 1 . . . . . .
gap> Display(GeneratorsOfGroup(Image(phi))[2]*One(GF(5)));
 1 . . . . . . . . .
 . 1 . . . . . . . .
 . . 1 4 . . . . . .
 . . . 1 . . . . . .
 . . . . 1 . . . . .
 . . . . . 1 . . . .
 . . . . . . 1 . . .
 . . . . . . . 1 . .
 . . . . . . . . 1 .
 . . . . . . . . . 1
]]>
</Example>
  </Description>
</ManSection>

</Section>

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

<Section Label="sec:ElementFactorization">
<Heading>
  Factoring elements into generators
</Heading>

<ManSection>
  <Meth Name ="PreImagesRepresentative" Arg="phi, g" Label="phi, g"/>
  <Returns>
    A representative of the set of preimages of&nbsp;<A>g</A> under
    the homomorphism&nbsp;<A>phi</A> from a free group to an rcwa group
    over&nbsp;<M>\mathbb{Z}</M>.
  </Returns>
  <Description>
    This method can be used for factoring elements of rcwa groups
    over <M>\mathbb{Z}</M> into generators. It can also be used for finding
    nontrivial relations among the generators if the respective group is not
    free and the method returns a factorization which does not happen to be
    equal to one which is already known.
    The homomorphism <A>phi</A> must map the generators of the free
    group to the generators of the rcwa group one-by-one.
    This method is also suitable for wild groups. The implementation
    is based on <Ref Oper="RepresentativeActionPreImage"
                     Label="G, src, dest, act, F"/>.
<Example>
<![CDATA[
gap> a  := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; # Collatz' permutation.
gap> nu := RcwaMapping([[1,1,1]]);;                  # n -> n + 1.
gap> SetName(nu,"nu"); SetName(a,"a"); # For displaying purposes.
gap> G  := Group(a,nu);
<rcwa group over Z with 2 generators>
gap> phi := EpimorphismFromFreeGroup(G);
[ a, nu ] -> [ a, nu ]
gap> F := Source(phi);
<free group on the generators [ a, nu ]>
gap> w := Comm(F.1^2*F.2^4,F.1*F.2^3);
nu^-4*a^-2*nu^-3*a*nu^4*a*nu^3
gap> g := w^phi;
<bijective rcwa mapping of Z with modulus 8>
gap> pre := PreImagesRepresentative(phi,g);
nu^-4*a^-1*nu^-1*a^-1*nu^3*a*nu^-1*a*nu^3
gap> rel := w/pre; # pre <> w --> We have a nontrivial relation!
nu^-4*a^-2*nu^-3*a*nu^5*a^-1*nu^-3*a*nu*a*nu^4
gap> rel := rel^(F.2^-4*F.1^-1); # Cyclically reduced form.
a^-1*nu^-3*a*nu^5*a^-1*nu^-3*a*nu
gap> rel^phi;
IdentityMapping( Integers )
]]>
</Example>
  </Description>
</ManSection>

<Alt Only="LaTeX">\pagebreak[4]</Alt>

<ManSection>
  <Oper Name ="PreImagesRepresentatives" Arg="phi, g" Label="phi, g"/>
  <Returns>
    A list of representatives of the set of preimages of&nbsp;<A>g</A>
    under the homomorphism&nbsp;<A>phi</A> from a free group to an rcwa
    group over&nbsp;<M>\mathbb{Z}</M>.
  </Returns>
  <Description>
    Quite frequently, computing several preimages is not harder than
    computing just one, i.e. often several preimages are found
    simultaneously. This operation is called by
    <Ref Meth ="PreImagesRepresentative" Label="phi, g"/>,
    which simply chooses the shortest representative.
    For a slightly more concise description see there.
<Example>
<![CDATA[
gap> w := Comm(F.1*F.2,Comm(F.1,F.2^2)); # We continue the example above.
nu^-1*a^-1*nu^-2*a^-1*nu^2*a^2*nu*a^-1*nu^-2*a*nu^2
gap> g := w^phi;
<bijective rcwa mapping of Z with modulus 16>
gap> pre := PreImagesRepresentatives(phi,g);
[ nu^-1*a^-2*nu^-2*a*nu^2*a*nu^-1*a^-1*nu^2*a,
  nu^-1*a^-1*nu^-2*a^-1*nu^2*a^2*nu^-1*a^-1*nu^2*a ]
gap> rel := pre[1]/pre[2];
nu^-1*a^-2*nu^-2*a*nu^2*a^-1*nu^-2*a*nu^2*a*nu
gap> rel := (rel^(F.2^-1*F.1^-1))^-1; # Cyclically reduced form.
nu^-2*a^-1*nu^2*a*nu^-2*a^-1*nu^2*a
gap> rel^phi;
IdentityMapping( Integers )
]]>
</Example>
    </Description>
  </ManSection>

</Section>

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

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

<Index Key="Support" Subkey="G"><C>Support</C></Index>
<Index Key="MovedPoints" Subkey="G"><C>MovedPoints</C></Index>

The support, i.e. set of moved points, of an rcwa group can be determined
by <C>Support</C> or <C>MovedPoints</C> (these are synonyms).
Sometimes testing for transitivity on the underlying ring is feasible.
This is e.g. the case for tame groups over&nbsp;<M>\Z</M>.
Further it is often 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="IsTransitive" Arg="G, Integers" Label="G, Integers"/>
  <Returns>
    <C>true</C> if the rcwa group&nbsp;<A>G</A> acts transitively
    on&nbsp;<M>\Z</M> and <C>false</C> otherwise.
  </Returns>
  <Description>
    If <A>G</A> is wild, this may fail or run into an infinite loop.
<Example>
<![CDATA[
gap> G := Group(ClassTransposition(1,2,0,4),ClassShift(0,2));;
gap> IsTransitive(G,Integers);
true
]]>
</Example>
  </Description>
</ManSection>

<Alt Only="LaTeX">\pagebreak[4]</Alt>

<ManSection>
  <Meth Name="RepresentativeAction"
        Arg="G, src, dest, act" Label="G, src, dest, act"/>
  <Returns>
    An element of <A>G</A> which maps <A>src</A> to&nbsp;<A>dest</A>
    under the action given by&nbsp;<A>act</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 to decide whether <A>src</A> and <A>dest</A> lie in the
    same orbit under the action of <A>G</A> in general seems to be hard.
    The method is based on <Ref Oper="RepresentativeActionPreImage"
    Label="G, src, dest, act, F"/>, and it basically just computes an image
    under an epimorphism. As this involves multiplications of rcwa mappings,
    this can be quite expensive if the group <A>G</A> is wild, the preimage
    is a rather long word and coefficient explosion happens to occur.
<Example>
<![CDATA[
gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; # Collatz' permutation.
gap> G := Group(a,ClassShift(1,4));
<rcwa group over Z with 2 generators>
gap> elm := RepresentativeAction(G,[7,4,9],[4,5,13],OnTuples);
<bijective rcwa mapping of Z with modulus 12>
gap> Display(elm);

Bijective rcwa mapping of Z with modulus 12

               n mod 12                |                 n^f
---------------------------------------+--------------------------------------
   0  2  3  6  8 11                    | n
   1  7 10                             | n - 3
   4                                   | n + 1
   5  9                                | n + 4

gap> List([7,4,9],n->n^elm);
[ 4, 5, 13 ]
gap> elm := RepresentativeAction(G,[5,4,9],[13,5,4],OnTuples);
<bijective rcwa mapping of Z with modulus 9>
gap> Display(elm);

Bijective rcwa mapping of Z with modulus 9

                n mod 9                |                 n^f
---------------------------------------+--------------------------------------
  0                                    | 4n/9
  1                                    | (8n - 26)/9
  2                                    | (8n + 2)/9
  3                                    | (8n + 3)/9
  4                                    | (16n - 19)/9
  5                                    | (16n + 37)/9
  6                                    | (8n + 33)/9
  7                                    | (16n - 49)/9
  8                                    | (16n + 7)/9

gap> RepresentativeAction(G,[7,4,9],[4,5,8],OnTuples);
<bijective rcwa mapping of Z with modulus 256>
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Oper Name="RepresentativeActionPreImage"
        Arg="G, src, dest, act, F" Label="G, src, dest, act, F"/>
  <Returns>
    The result of
    <C>RepresentativeAction(<A>G</A>,<A>src</A>,<A>dest</A>,<A>act</A>)</C>
    as word in generators.
  </Returns>
  <Description>
    The argument <A>F</A> is a free group whose generators are used as
    letters of the returned word. Note that the dependency is just in the
    opposite direction than suggested above (<C>RepresentativeAction</C>
    calls <C>RepresentativeActionPreImage</C>) and that the evaluation
    of the word sometimes takes much more time than its determination.
    For this reason, <C>RepresentativeActionPreImage</C> is sometimes
    much faster than <C>RepresentativeAction</C>.
    The used algorithm is based on computing balls of increasing radius
    around <A>src</A> and <A>dest</A> until they intersect nontrivially.
    It avoids multiplying rcwa mappings.
    Of course the other warnings given in the description of
    <Ref Meth="RepresentativeAction" Label="G, src, dest, act"/>
    apply to this operation as well.
<Example>
<![CDATA[
gap> g := ClassTransposition(0,2,1,2)*ClassShift(0,3);;      SetName(g,"g");
gap> h := ClassTransposition(3,4,4,6)*ClassReflection(0,4);; SetName(h,"h");
gap> G := Group(g,h);;
gap> F := FreeGroup("g","h");; phi := EpimorphismByGenerators(F,G);;
gap> w1 := RepresentativeActionPreImage(G,[1,2,3,4],[2,3,5,7],OnPoints,F);
h^-1*g^3*h^-1*g^-1*h^-2
gap> elm1 := w1^phi;
<bijective rcwa mapping of Z with modulus 864>
gap> List([1,2,3,4],n->n^elm1); # `OnPoints' permits reordering
[ 2, 7, 3, 5 ]
gap> w2 := RepresentativeActionPreImage(G,[1,2,3,4],[2,3,5,7],OnTuples,F);
g*h^-1*g^-1*h^-1*g^-2*h*g^-2*h^2*g^-1*h*g
gap> elm2 := w2^phi;
<bijective rcwa mapping of Z with modulus 432>
gap> List([1,2,3,4],n->n^elm2); # `OnTuples' does not permit reordering
[ 2, 3, 5, 7 ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Meth Name="RepresentativeAction" Arg="RCWA_Z, P1, P2"
                                    Label="RCWA( Integers ), P1, P2"/>
  <Returns>
    An element of RCWA(<M>\Z</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 disjoint unions of
    residue classes.
    The method recognizes the option <C>IsTame</C>. If this option
    is set, the returned mapping is tame provided that there is a tame
    mapping which satisfies the given condition.
    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 := List([[0,3],[1,3],[2,9],[5,9],[8,9]],ResidueClass);
[ 0(3), 1(3), 2(9), 5(9), 8(9) ]
gap> P2 := List([[0,2],[1,8],[5,16],[3,4],[13,16]],ResidueClass);
[ 0(2), 1(8), 5(16), 3(4), 13(16) ]
gap> elm := RepresentativeAction(RCWA(Integers),P1,P2);
<bijective rcwa mapping of Z with modulus 9>
]]>
</Example>

<Alt Only="LaTeX">\pagebreak[4]</Alt>

<Example>
<![CDATA[
gap> P1^elm = P2;
true
gap> Display(elm);

Bijective rcwa mapping of Z with modulus 9

                n mod 9                |                 n^f
---------------------------------------+--------------------------------------
  0 3 6                                | 2n/3
  1 4 7                                | (8n - 5)/3
  2                                    | (16n + 13)/9
  5                                    | (4n + 7)/9
  8                                    | (16n - 11)/9

gap> elm := RepresentativeAction(RCWA(Integers),P1,P2:IsTame);
<tame bijective rcwa mapping of Z with modulus 1152>
gap> P := RespectedPartition(elm);;
gap> Length(P);
313
gap> elm := RepresentativeAction(RCWA(Integers),
>             [ResidueClass(1,3),Union(ResidueClass(0,3),ResidueClass(2,3))],
>             [Union(ResidueClass(2,5),ResidueClass(4,5)),
>              Union(ResidueClass(0,5),ResidueClass(1,5),ResidueClass(3,5))]);
<bijective rcwa mapping of Z with modulus 6>
gap> [ResidueClass(1,3),Union(ResidueClass(0,3),ResidueClass(2,3))]^elm;
[ 2(5) U 4(5), Z \ 2(5) U 4(5) ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Oper Name="ShortOrbits" Arg="G, S, maxlng" Label="G, S, maxlng"/>
  <Oper Name="ShortCycles" Arg="g, S, maxlng" Label="G, S, maxlng"/>
  <Returns>
    A list of all finite orbits of the rcwa group&nbsp;<A>G</A> resp.
    of all finite cycles of the bijective rcwa mapping <A>g</A> of
    length at most&nbsp;<A>maxlng</A> which intersect nontrivially with
    the set&nbsp;<A>S</A>.
  </Returns>
  <Description>
<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(5),[1..100],20);
[ [ 1 ], [ 2 ], [ 3 ], [ 4 ], [ 5, 6 ], [ 7, 8 ], 
  [ 9, 10, 12, 14, 16, 13, 11 ], [ 15, 18 ], 
  [ 17, 20, 24, 28, 23, 19, 22, 26, 21 ], 
  [ 45, 54, 64, 76, 61, 49, 58, 47, 56 ], 
  [ 59, 70, 84, 100, 120, 144, 172, 206, 165, 198, 159, 190, 228, 183, 147, 
      176, 141, 113, 91, 73 ] ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Oper Name ="Projections" Arg="G, m" Label="G, m"/>
  <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 setwisely.
  </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="G, m"><C>OrbitsModulo</C></Index>
<Example>
<![CDATA[
gap> G := Group(ClassTransposition(0,2,1,2),ClassShift(3,4));;
gap> Projections(G,4);
[ [ ClassTransposition(0,2,1,2), ClassShift(3,4) ] ->
    [ <bijective rcwa mapping of Z with modulus 4>,
      IdentityMapping( Integers ) ],
  [ ClassTransposition(0,2,1,2), ClassShift(3,4) ] ->
    [ <bijective rcwa mapping of Z with modulus 4>,
      <bijective rcwa mapping 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>

<ManSection>
  <Meth Name ="Ball" Arg="G, p, d, act" Label="G, p, d, act"/>
  <Meth Name ="Ball" Arg="G, g, d" Label="G, g, d"/>
  <Returns>
    The ball of radius&nbsp;<A>d</A> around the point&nbsp;<A>p</A> under
    the action&nbsp;<A>act</A> of the group&nbsp;<A>G</A>, resp. the ball
    of radius&nbsp;<A>d</A> around the element&nbsp;<A>g</A> in the
    group&nbsp;<A>G</A>.
  </Returns>
  <Description>
    All balls are understood w.r.t. <C>GeneratorsOfGroup(<A>G</A>)</C>.
    As element tests can be expensive, the latter method does not check
    whether <A>g</A> is indeed an element of&nbsp;<A>G</A>.
    The methods require that point comparisons resp. element comparisons
    are cheap. They are not only applicable to rcwa groups.
<Example>
<![CDATA[
gap> PSL2Z := Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(3),
>                                                    CyclicGroup(2))));
<wild rcwa group over Z with 2 generators>
gap> List([1..10],k->Length(Ball(PSL2Z,0,k,OnPoints)));
[ 3, 4, 6, 8, 12, 16, 24, 32, 48, 64 ]
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);
[ (), (3,4), (2,3), (2,3,4), (2,4,3), (1,2), (1,2)(3,4), (1,2,3), (1,3,2) ]
]]>
</Example>
  </Description>
</ManSection>

</Section>

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

<Section Label="sec:ConjugacyInRCWA_Z">
<Heading>Conjugacy in RCWA(Z)</Heading>

<ManSection>
  <Meth Name="IsConjugate" Arg="RCWA(Integers), f, g"
                           Label="RCWA(Integers), f, g"/>
  <Returns>
    <C>true</C> if the bijective rcwa mappings <A>f</A> and&nbsp;<A>g</A>
    are conjugate in RCWA(<M>\Z</M>), and <C>false</C> otherwise.
  </Returns>
  <Description>
    The author does not know a general way to solve the conjugacy problem
    for elements of RCWA(<M>\Z</M>), thus the method may fail or run into
    an infinite loop.
<Example>
<![CDATA[
gap> IsConjugate(RCWA(Integers),ClassTransposition(0,2,1,4),
>                               ClassTransposition(1,2,0,4));
true
gap> IsConjugate(RCWA(Integers),ClassTransposition(0,2,1,4),ClassShift(0,1));
false
]]>
</Example>
  </Description>
</ManSection>

<Index Key="ShortCycles" Subkey="f, maxlng"><C>ShortCycles</C></Index>
In its 2-argument form, <C>ShortCycles(<A>f</A>,<A>maxlng</A>)</C>
returns a list of all cycles of <A>f</A> of length at most <A>maxlng</A>
which do not correspond to cycles consisting of residue classes. The
cycles are sorted by increasing length. If for some value of <A>maxlng</A>
the lists <C>List(ShortCycles(<A>f</A>,<A>maxlng</A>),Length)</C> and
<C>List(ShortCycles(<A>g</A>,<A>maxlng</A>),Length)</C> differ, then
<A>f</A> and <A>g</A> are clearly not conjugate.

<Example>
<![CDATA[
gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; # Collatz' permutation.
gap> ShortCycles(a,5);
[ [ 0 ], [ 1 ], [ -1 ], [ 2, 3 ], [ -3, -2 ], [ 4, 5, 7, 9, 6 ],
  [ -9, -6, -4, -5, -7 ] ]
]]>
</Example>

<ManSection>
  <Meth Name="RepresentativeAction" Arg="RCWA(Integers), f, g"
                                    Label="RCWA(Integers), f, g"/>
  <Returns>
    An rcwa mapping&nbsp;<C>x</C> such that
    <C><A>f</A>&circum;x = <A>g</A></C>, if such an <C>x</C>
    exists and <C>fail</C> otherwise.
  </Returns>
  <Description>
    This method may fail for the same reasons as
    <Ref Meth="IsConjugate" Label="RCWA(Integers), f, g"/>.
<Example>
<![CDATA[
gap> rep := RepresentativeAction(RCWA(Integers),ClassTransposition(0,2,1,4),
>                                               ClassTransposition(1,2,0,4));
<bijective rcwa mapping of Z with modulus 32>
gap> ClassTransposition(0,2,1,4)^rep = ClassTransposition(1,2,0,4); # check
true
gap> Factorization(rep);
[ ClassTransposition(0,2,3,16), ClassTransposition(1,4,11,16),
  ClassTransposition(2,8,3,16), ClassTransposition(6,8,11,16),
  ClassTransposition(1,2,2,8), ClassTransposition(0,4,6,8) ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Func Name="NrConjugacyClassesOfRCWAZOfOrder" Arg="ord" Label="ord"/>
  <Returns>
    The number of conjugacy classes of RCWA(<M>\Z</M>) of elements
    of order&nbsp;<A>ord</A>, as given in Corollary&nbsp;2.7.1&nbsp;(b)
    in&nbsp;<Cite Key="Kohl05"/>.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> List([2,105],NrConjugacyClassesOfRCWAZOfOrder);
[ infinity, 218 ]
]]>
</Example>
  </Description>
</ManSection>

</Section>

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

<Section Label="sec:RestrictionAndInduction">
<Heading>Restriction and induction</Heading>

There are monomorphisms from the group RCWA(<M>\Z</M>) into itself.
The support of the image of such a monomorphism is the image of a given
injective rcwa mapping. Therefore these monomorphisms are called
<E>restriction monomorphisms</E>. Taking images of rcwa groups under
restrictions by rcwa mappings with pairwise distinct images permits
forming their direct product and their wreath product with some finite
permutation group, regardless of whether they are tame or not
(cp. Section&nbsp;<Ref Label="sec:DirectProductsAndWreathProducts"/>).

<ManSection>
  <Oper Name="Restriction" Arg="g, f" Label="g, f"/>
  <Oper Name="Restriction" Arg="G, f" Label="G, f"/>
  <Returns>
    The <E>restriction</E> of the rcwa mapping <A>g</A> resp. the
    rcwa group <A>G</A> by the injective rcwa mapping&nbsp;<A>f</A>.
  </Returns>
  <Description>
    By definition, the restriction <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 restriction 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>
  <Oper Name ="Induction" Arg="g, f" Label = "g, f"/>
  <Oper Name ="Induction" Arg="G, f" Label = "G, f"/>
  <Returns>
    The <E>induction</E> of the rcwa mapping <A>g</A> resp. the rcwa
    group <A>G</A> by the injective rcwa mapping&nbsp;<A>f</A>.
  </Returns>
  <Description>
    By definition, induction is the right inverse of restriction.
    This means that it is
    <C>Induction(Restriction(<A>g</A>,<A>f</A>),<A>f</A>) = <A>g</A></C>
    resp.
    <C>Induction(Restriction(<A>G</A>,<A>f</A>),<A>f</A>) = <A>G</A></C>.
    The mapping&nbsp;<A>g</A> resp. 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>

</Section>

<Alt Only="LaTeX">\pagebreak[4]</Alt>

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

<Section Label="sec:Random">
<Heading>Getting pseudo-random elements of RCWA(Z)</Heading>

<Index Key="Random" Subkey="RCWA(Z)"><C>Random</C></Index>
There is a method for the operation <C>Random</C> for RCWA(<M>\Z</M>).
This method is designed to be suitable for generating interesting
examples. No particular distribution is guaranteed.

<Log>
<![CDATA[
gap> elm := Random(RCWA(Integers));
<bijective rcwa mapping of Z with modulus 60>
gap> Display(elm);

Bijective rcwa mapping of Z with modulus 12

               n mod 12                |                 n^f
---------------------------------------+--------------------------------------
   0  2  4  6  8 10                    | 3n + 2
   1  5  9                             | -n + 2
   3  7                                | (n - 7)/2
  11                                   | (-n + 20)/3

]]>
</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(3,4,4,6),
  ClassShift(0,2)^-1, ClassReflection(3,4), ClassReflection(1,4) ]
]]>
</Log>

An auxiliary function which is used in this context for choosing the
class transpositions is <C>ClassPairs(<A>m</A>)</C>.
<Index Key="ClassPairs" Subkey="m"><C>ClassPairs</C></Index>
This function returns a list of 4-tuples <M>(r_1,m_1,r_2,m_2)</M>
of integers corresponding to the pairs of disjoint residue classes
<M>r_1(m_1)</M> and <M>r_2(m_2)</M> with <M>m_1, m_2 \leq m</M>.

<Example>
<![CDATA[
gap> List(ClassPairs(4),ClassTransposition);
[ ClassTransposition(0,2,1,2), ClassTransposition(0,2,1,4),
  ClassTransposition(0,2,3,4), ClassTransposition(0,3,1,3),
  ClassTransposition(0,3,2,3), ClassTransposition(0,4,1,4),
  ClassTransposition(0,4,2,4), ClassTransposition(0,4,3,4),
  ClassTransposition(1,2,0,4), ClassTransposition(1,2,2,4),
  ClassTransposition(1,3,2,3), ClassTransposition(1,4,2,4),
  ClassTransposition(1,4,3,4), ClassTransposition(2,4,3,4) ]
gap> List(last,TransposedClasses);
[ [ 0(2), 1(2) ], [ 0(2), 1(4) ], [ 0(2), 3(4) ], [ 0(3), 1(3) ],
  [ 0(3), 2(3) ], [ 0(4), 1(4) ], [ 0(4), 2(4) ], [ 0(4), 3(4) ],
  [ 1(2), 0(4) ], [ 1(2), 2(4) ], [ 1(3), 2(3) ], [ 1(4), 2(4) ],
  [ 1(4), 3(4) ], [ 2(4), 3(4) ] ]
]]>
</Example>

</Section>

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

<Section Label="sec:MethodsForTameGroups">
<Heading>Special attributes for tame rcwa groups</Heading>

There is a couple of attributes which a priori make only sense for tame
rcwa groups. In the sequel, these attributes are described in detail. <P/>

With their help, various structural information about a given tame rcwa
group can be obtained. For example there are methods for <C>IsSolvable</C>
and <C>IsPerfect</C> available for tame rcwa groups, while testing wild
groups for solvability or perfectness is currently not always feasible.
It is often also possible to compute the derived subgroup of a tame
rcwa group. 

<ManSection>
  <Attr Name ="RespectedPartition" Arg="G" Label="G"/>
  <Attr Name ="RespectedPartition" Arg="g" Label="g"/>
  <Returns>
    A respected partition of the rcwa group <A>G</A> resp.
    of the rcwa mapping&nbsp;<A>g</A>.
  </Returns>
  <Description>
    A <E>respected partition</E> of&nbsp;<A>G</A> resp.&nbsp;<A>g</A>
    is a partition of the underlying ring&nbsp;<M>R</M> into a finite
    number of residue classes on which&nbsp;<A>G</A> resp. the cyclic
    group generated by&nbsp;<A>g</A> acts in a natural way as
    a permutation group, and on whose elements all elements of&nbsp;<A>G</A>
    resp. all powers of&nbsp;<A>g</A> are affine.
    Such a partition exists if and only if <A>G</A> resp. <A>g</A>
    is tame (see&nbsp;<Cite Key="Kohl05"/>, Theorem&nbsp;2.5.8). <P/>

    <Index Key="RespectedPartitionShort" Subkey="G">
      <C>RespectedPartitionShort</C>
    </Index>
    <Index Key="RespectedPartitionShort" Subkey="g">
      <C>RespectedPartitionShort</C>
    </Index>
    <Index Key="RespectedPartitionLong" Subkey="G">
      <C>RespectedPartitionLong</C>
    </Index>
    <Index Key="RespectedPartitionLong" Subkey="g">
      <C>RespectedPartitionLong</C>
    </Index>
    Related attributes are <C>RespectedPartitionShort</C> and
    <C>RespectedPartitionLong</C>. They are used to denote respected
    partitions consisting of residue classes <M>r(m)</M> where <M>m</M>
    divides the modulus of&nbsp;<A>G</A> resp. <A>g</A>, resp. where
    the modulus of <A>G</A> resp. <A>g</A> divides&nbsp;<M>m</M>. <P/>

    <Index Key="RespectsPartition" Subkey="G">
      <C>RespectsPartition</C>
    </Index>
    <Index Key="RespectsPartition" Subkey="g">
      <C>RespectsPartition</C>
    </Index>
    There is an operation <C>RespectsPartition(<A>G</A>,<A>P</A>)</C>
    resp. <C>RespectsPartition(<A>g</A>,<A>P</A>)</C>, which tests
    whether <A>G</A> resp.&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 using
    <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);
[ 3(6), 5(6), 0(8), 2(8), 4(8), 6(8), 1(12), 7(12) ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Attr Name="ActionOnRespectedPartition" Arg="G" Label="G"/>
  <Returns>
    The action of the tame rcwa group&nbsp;<A>G</A> on
    <C>RespectedPartition(<A>G</A>)</C>.
  </Returns>
  <Description>
<Example>
<![CDATA[
gap> H := ActionOnRespectedPartition(G);
Group([ (3,7)(5,8), (3,4,5,6) ])
gap> H = Action(G,P);
true
gap> StructureDescription(H);
"C2 x S4"
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Attr Name="KernelOfActionOnRespectedPartition" Arg="G" Label="G"/>
  <Attr Name="RankOfKernelOfActionOnRespectedPartition" Arg="G" Label="G"/>
  <Returns>
    The kernel of the action of the tame rcwa group&nbsp;<A>G</A> on
    <C>RespectedPartition(<A>G</A>)</C>, resp. the rank of the largest
    free abelian subgroup of this kernel.
  </Returns>
  <Description>
    The method for <C>KernelOfActionOnRespectedPartition</C> uses
    the package <Package>Polycyclic</Package>&nbsp;<Cite Key="Polycyclic"/>.
<Example>
<![CDATA[
gap> K := KernelOfActionOnRespectedPartition(G);
<rcwa group over Z with 3 generators>
gap> RankOfKernelOfActionOnRespectedPartition(G);
3
gap> Index(G,K);
48
gap> List(GeneratorsOfGroup(K),Factorization);
[ [ ClassShift(0,4)^2 ], [ ClassShift(2,4)^2 ], [ ClassShift(1,6)^2 ] ]
gap> IsomorphismPcpGroup(K);
[ <bijective rcwa mapping of Z with modulus 4>,
  <bijective rcwa mapping of Z with modulus 4>,
  <bijective rcwa mapping of Z with modulus 6> ] -> [ g6*g10, g8*g12, g14*g16
 ]
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Attr Name ="IntegralConjugate" Arg="G" Label="G"/>
  <Attr Name ="IntegralConjugate" Arg="g" Label="g"/>
  <Returns>
    Some integral conjugate of the tame rcwa group&nbsp;<A>G</A> resp.
    of the tame bijective rcwa mapping&nbsp;<A>g</A> in the group
    RCWA(<M>\Z</M>).
  </Returns>
  <Description>
    Such conjugates exist, see&nbsp;<Cite Key="Kohl05"/>,
    Theorem&nbsp;2.5.14. In general there are infinitely many of them.
    An rcwa mapping mapping&nbsp;<A>x</A> such that
    <C><A>G</A>&circum;<A>x</A>=IntegralConjugate(<A>G</A>)</C> resp.
    <C><A>g</A>&circum;<A>x</A>=IntegralConjugate(<A>g</A>)</C>
    is stored as an attribute <C>IntegralizingConjugator</C>.
    <Index Key="IntegralizingConjugator" Subkey="G">
      <C>IntegralizingConjugator</C>
    </Index>
    <Index Key="IntegralizingConjugator" Subkey="g">
      <C>IntegralizingConjugator</C>
    </Index>
<Example>
<![CDATA[
gap> IsIntegral(IntegralConjugate(G));
true
gap> G^IntegralizingConjugator(G) = IntegralConjugate(G);
true
gap> RespectedPartition(G);
[ 3(6), 5(6), 0(8), 2(8), 4(8), 6(8), 1(12), 7(12) ]
gap> RespectedPartition(G)^IntegralizingConjugator(G);
[ 0(8), 1(8), 2(8), 3(8), 4(8), 5(8), 6(8), 7(8) ]
gap> last = RespectedPartition(IntegralConjugate(G));
true
]]>
</Example>

<Alt Only="LaTeX">\pagebreak[4]</Alt>

<Example>
<![CDATA[
gap> Display(IntegralizingConjugator(G));

Bijective rcwa mapping of Z with modulus 24

               n mod 24                |                 n^f
---------------------------------------+--------------------------------------
   0  8 16                             | n + 2
   1 13                                | (2n + 16)/3
   2 10 18                             | n + 1
   3  9 15 21                          | (4n - 12)/3
   4 12 20                             | n
   5 11 17 23                          | (4n - 17)/3
   6 14 22                             | n - 1
   7 19                                | (2n + 7)/3

]]>
</Example>
  </Description>
</ManSection>

</Section>

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

<Section Label="sec:UtilityFunctions">
<Heading>Some general utility functions</Heading>

<Index Key="GeneratorsAndInverses" Subkey="G">
  <C>GeneratorsAndInverses</C>
</Index>
<Index Key="EpimorphismByGenerators" Subkey="G, H">
  <C>EpimorphismByGenerators</C>
</Index>
<Index Key="AllProducts" Subkey="l, k">
  <C>AllProducts</C>
</Index>

&RCWA; introduces a few small utility functions which can be used for
groups in general: The function <C>GeneratorsAndInverses(<A>G</A>)</C>
returns a list of generators of <A>G</A> and their inverses,
<C>EpimorphismByGenerators(<A>G</A>,<A>H</A>)</C> is
a shorthand for <C>GroupHomomorphismByImages(<A>G</A>,<A>H</A>,
GeneratorsOfGroup(<A>G</A>),GeneratorsOfGroup(<A>H</A>))</C>
(there is also an <C>NC</C> version of this) and the function
<C>AllProducts(<A>l</A>,<A>k</A>)</C> returns the list of
all products of <A>k</A> entries of the list&nbsp;<A>l</A>.

</Section>

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

<Section Label="sec:CategoriesOfRcwaGroups">
<Heading>The categories of rcwa groups</Heading>

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

    <Index Key="IsRcwaGroupOverZOrZ_pi" Subkey="G">
      <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>.

    <Index Key="IsNaturalRCWA_Z" Subkey="G">
      <C>IsNaturalRCWA&uscore;Z</C>
    </Index>
    <Index Key="IsNaturalRCWA_Z_pi" Subkey="G">
      <C>IsNaturalRCWA&uscore;Z&uscore;pi</C>
    </Index>
    <Index Key="IsNaturalRCWA_GFqx" Subkey="G">
      <C>IsNaturalRCWA&uscore;GFqx</C>
    </Index>

    To allow distinguishing the entire group RCWA(<M>R</M>) from others
    by means of the method selection, it has the characteristic property
    <C>IsNaturalRCWA&uscore;Z</C> resp. one of the properties
    <C>IsNaturalRCWA&uscore;Z&uscore;pi</C> or
    <C>IsNaturalRCWA&uscore;GFqx</C>, depending on whether <M>R</M>
    is the ring of integers, one of its semilocalizations or a univariate
    polynomial ring over a finite field.

  </Description>
</ManSection>

</Section>

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

</Chapter>

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