% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}
\usepackage{a4wide}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[latin1]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}
\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}
\definecolor{FuncColor}{rgb}{1.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,1.0}

\usepackage{fancyvrb}

\usepackage{pslatex}

\usepackage{amsxtra}\usepackage[pdftex=true,
        a4paper=true,bookmarks=false,pdftitle={Written with GAPDoc},
        pdfcreator={LaTeX with hyperref package / GAPDoc},
        colorlinks=true,backref=page,breaklinks=true,linkcolor=RoyalBlue,
        citecolor=RoyalGreen,filecolor=RoyalRed,
        urlcolor=RoyalRed,pagecolor=RoyalBlue]{hyperref}

% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
\newcommand{\Q}{\mathbb{Q}}
\newcommand{\R}{\mathbb{R}}
\newcommand{\C}{\mathbb{C}}
\newcommand{\Z}{\mathbb{Z}}
\newcommand{\N}{\mathbb{N}}
\newcommand{\F}{\mathbb{F}}

\newcommand{\GAP}{\textsf{GAP}}

\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\begin{center}{\Huge \textbf{\textsf{RCWA}\mbox{}}}\\[1cm]
\hypersetup{pdftitle=\textsf{RCWA}}
\markright{\scriptsize \mbox{}\hfill \textsf{RCWA} \hfill\mbox{}}
{\Large \textbf{Residue-Class-Wise Affine Groups\mbox{}}}\\[1cm]
{ Version 2.5.1 \mbox{}}\\[1cm]
{June 1, 2007\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\large \textbf{ Stefan Kohl    \mbox{}}}\\
\hypersetup{pdfauthor= Stefan Kohl    }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{ Stefan Kohl    } --- Email: \href{mailto://kohl@mathematik.uni-stuttgart.de} {\texttt{kohl@mathematik.uni-stuttgart.de}}\\
 --- Homepage: \href{ http://www.cip.mathematik.uni-stuttgart.de/{\textasciitilde}kohlsn/ } {\texttt{ http://www.cip.mathematik.uni-stuttgart.de/\texttt{\symbol{123}}\texttt{\symbol{92}}textasciitilde\texttt{\symbol{125}}kohlsn/ }}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 Institut f{\"u}r Geometrie und Topologie \\
 Pfaffenwaldring 57 \\
 Universit{\"a}t Stuttgart \\
 70550 Stuttgart \\
 Germany \end{minipage}
}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Abstract}
\logpage{[ 0, 0, 2 ]}
 \textsf{RCWA} is a package for \textsf{GAP} 4. It introduces a new class of groups which are accessible to computational
methods. In principle, this package can deal at least with the following types
of groups and their subgroups: 
\begin{itemize}
\item  Finite groups, and certain divisible torsion groups which they embed into. 
\item  Free groups of finite rank. 
\item  Free products of finitely many finite groups, thus in particular the modular
group PSL(2,$\Z$). 
\item  Direct products of the above groups. 
\item  Wreath products of the above groups with finite groups and with{\nobreakspace}$(\Z,+)$. 
\end{itemize}
 With substancial help of this package, the author has found a countable simple
group which has an uncountable series of simple subgroups. This simple group
is generated by involutions which interchange disjoint residue classes of the
integers. All the above groups embed into it. 

 \mbox{}}\\[1cm]
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
 {\copyright} 2003 - 2007 by Stefan Kohl. This package is distributed under the
GNU General Public License. \vspace{-1cm} \mbox{}}\\[1cm]
{\small 
\section*{Acknowledgements}
\logpage{[ 0, 0, 3 ]}
 I am very grateful to Bettina{\nobreakspace}Eick for communicating this
package and for her kind help in improving its documentation. Further I would
like to thank the two anonymous referees for their constructive criticism and
their helpful suggestions. 

 I am also very grateful to Laurent Bartholdi for his hint on how to construct
wreath products of residue-class-wise affine groups with{\nobreakspace}$(\Z,+)$. Last but not least I would like to thank all the people who have invited me
so far to give talks on the subject in their seminars and on their
conferences. \mbox{}}\\[1cm]
\newpage

\def\contentsname{Contents\logpage{[ 0, 0, 4 ]}}

\tableofcontents
\newpage

        
\chapter{\textcolor{Chapter }{About the RCWA Package}}\label{ch:AboutRCWA}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X83A8C2927FAE2C23}{}
{
  
\section{\textcolor{Chapter }{Motivation}}\label{sec:motivation}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X816FA3667FFEDC3F}{}
{
  \index{Collatz conjecture@Collatz conjecture} \index{Collatz conjecture@Collatz mapping} The development of this package has originally been inspired by the famous $3n+1$-Conjecture, which asserts that iterated application of the \emph{Collatz mapping}  
\[ T: \ \ \Z \longrightarrow \Z, \ \ \ \ n \ \longmapsto \ \begin{cases}
\frac{n}{2} & \text{if} \ \ n \ \ \text{is even}, \\ \frac{3n+1}{2} &
\text{if} \ \ n \ \ \text{is odd} \end{cases} \]
    to any given positive integer eventually yields{\nobreakspace}1
(cp.{\nobreakspace}\cite{Lagarias06}). 

 So far, no attempts have been made to investigate the structure of groups
whose elements are permutations which are ``similar to the Collatz mapping'', i.e. \emph{residue-class-wise affine}. 

 After having investigated these groups for a couple of years, the author feels
that this is a gap which is worth to be filled. }

  
\section{\textcolor{Chapter }{Purpose of this package}}\label{sec:Purpose}
\logpage{[ 1, 2, 0 ]}
\hyperdef{L}{X78FE3F9D80DB633E}{}
{
  The present scope of computational group theory essentially comprises finite
permutation groups, matrix groups, finitely presented groups, polycyclically
presented groups and automata groups. For details, we refer to{\nobreakspace}\cite{HoltEickOBrien05}. 

 The purpose of this package is twofold: 
\begin{itemize}
\item  On the one hand, it introduces a new class of groups which are accessible to
computational methods, and it therefore extends the current scope of
computational group theory as outlined above. 
\item  On the other, residue-class-wise affine groups are interesting mathematical
objects in their own right, and this package is intended to serve as a tool
for obtaining a better understanding of their rich and often complicated group
theoretical and combinatorial structure. 
\end{itemize}
 }

 \pagebreak[4]  
\section{\textcolor{Chapter }{Groups which this package can deal with}}\label{sec:GroupsWhichEmbed}
\logpage{[ 1, 3, 0 ]}
\hyperdef{L}{X82190FB67F7F3325}{}
{
  In principle this package permits to construct and investigate all groups
which have faithful representations as residue-class-wise affine groups. Among
many others, the following groups and their subgroups belong to this class: 
\begin{itemize}
\item  Finite groups, and certain divisible torsion groups which they embed into. 
\item  Free groups of finite rank. 
\item  Free products of finitely many finite groups, thus in particular the modular
group PSL(2,$\Z$). 
\item  Direct products of the above groups. 
\item  Wreath products of the above groups with finite groups and with{\nobreakspace}$(\Z,+)$. 
\end{itemize}
 This list permits already to conclude that there are finitely generated
residue-class-wise affine groups which do not have finite presentations, and
such with algorithmically unsolvable membership problem. However the list is
certainly by far not exhaustive, and using this package it is easy to
construct groups of types which are not mentioned there. 

 The group CT($\Z$) which is generated by all \emph{class transpositions} of{\nobreakspace}$\Z$ -- these are involutions which interchange two disjoint residue classes, see \texttt{ClassTransposition} (\ref{ClassTransposition:r1, m1, r2, m2}) -- is a simple group which has subgroups of all types listed above. It is
countable, but it has an uncountable series of simple subgroups which is
parametrized by the sets of odd primes. 

 Proofs of most of the results mentioned here have not yet appeared in print.
However they can be found in the preprint{\nobreakspace}\cite{Kohl06b}, which is available on the author's homepage. Descriptions of many of the
algorithms and methods which are implemented in this package can be found
in{\nobreakspace}\cite{Kohl07a}. }

  
\section{\textcolor{Chapter }{Scope of this package}}\label{sec:Scope}
\logpage{[ 1, 4, 0 ]}
\hyperdef{L}{X84BA84177E640F2B}{}
{
  This package can be applied in various ways to various different problems, and
it is just not possible to say what can be found out with its help about which
groups. The best way to get an idea about this is likely to experiment with
the examples discussed in this manual and included in the file \texttt{pkg/rcwa/examples/examples.g}. 

 Of course this package often does not provide an out-of-the-box solution for a
given problem. Quite often it is possible to find an answer for a given
question by using an interactive trial-and-error approach. 

 With substancial help of this package, the author has found the results
mentioned in Section{\nobreakspace}\ref{sec:GroupsWhichEmbed}. Interactive sessions with this package have also lead to the development of
most of the algorithms which are now implemented in it. Just to mention one
example, developing the factorization method for residue-class-wise affine
permutations (see{\nobreakspace}\texttt{FactorizationIntoCSCRCT} (\ref{FactorizationIntoCSCRCT:for an rcwa permutation of Z})) solely by means of theory would likely have been very hard. }

  }

         
\chapter{\textcolor{Chapter }{Residue-Class-Wise Affine Mappings}}\label{ch:RcwaMappings}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X7FD73FCB8510050E}{}
{
  In this chapter, we give the basic definitions, and describe how to enter
residue-class-wise affine mappings and how to compute with them. 

 How to compute with residue-class-wise affine groups is described in detail in
the next chapter. The reader is encouraged to look there already after having
read the first few pages of this chapter, and to look up definitions as he
needs to.  
\section{\textcolor{Chapter }{Basic definitions}}\label{sec:basicdefinitions}
\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X7F0B50947EEA87F8}{}
{
  \index{rcwa mapping@rcwa mapping!definition} \index{rcwa group@rcwa group!definition} Residue-class-wise affine groups, or \emph{rcwa} groups for short, are permutation groups whose elements are bijective
residue-class-wise affine mappings. 

 A mapping $f: \Z \rightarrow \Z$ is called \emph{residue-class-wise affine}, or for short an \emph{rcwa} mapping, if there is a positive integer{\nobreakspace}$m$ such that the restrictions of{\nobreakspace}$f$ to the residue classes $r(m) \in \Z/m\Z$ are all affine, i.e. given{\nobreakspace}by  
\[ f|_{r(m)}: \ r(m) \rightarrow \Z, \ \ \ n \ \mapsto \ \frac{a_{r(m)} \cdot n +
b_{r(m)}}{c_{r(m)}} \]
    for certain coefficients $a_{r(m)}, b_{r(m)}, c_{r(m)} \in \Z$ depending on{\nobreakspace}$r(m)$. \index{modulus@modulus!definition} \index{rcwa mapping@rcwa mapping!modulus} \index{multiplier@multiplier!definition} \index{rcwa mapping@rcwa mapping!multiplier} \index{divisor@divisor!definition} \index{rcwa mapping@rcwa mapping!divisor} The smallest possible $m$ is called the \emph{modulus} of{\nobreakspace}$f$. It is understood that all fractions are reduced, i.e. that $\gcd( a_{r(m)}, b_{r(m)}, c_{r(m)} ) = 1$, and that $c_{r(m)} > 0$. The lcm of the coefficients $a_{r(m)}$ is called the \emph{multiplier} of{\nobreakspace}$f$, and the lcm of the coefficients $c_{r(m)}$ is called the \emph{divisor} of{\nobreakspace}$f$. 

 It is easy to see that the residue-class-wise affine mappings
of{\nobreakspace}$\Z$ form a monoid under composition, and that the residue-class-wise affine
permutations of{\nobreakspace}$\Z$ form a countable subgroup of Sym($\Z$). We denote the former by Rcwa($\Z$), and the latter by RCWA($\Z$). 

 \index{tame@tame!rcwa mapping} \index{tame@tame!rcwa group} \index{wild@wild!rcwa mapping} \index{wild@wild!rcwa group} \index{rcwa mapping@rcwa mapping!tame} \index{rcwa group@rcwa group!tame} \index{rcwa mapping@rcwa mapping!wild} \index{rcwa group@rcwa group!wild} An rcwa mapping is called \emph{tame} if the set of moduli of its powers is bounded, or equivalently if it permutes
a partition of{\nobreakspace}$\Z$ into finitely many residue classes on all of which it is affine. An rcwa group
is called \emph{tame} if there is a common such partition for all of its elements, or equivalently
if the set of moduli of its elements is bounded. Rcwa mappings and -groups
which are not tame are called \emph{wild}. Tame rcwa mappings and -groups are something which one could call the ``trivial cases'' or ``basic building blocks'', while wild rcwa groups are the objects of primary interest. 

 The definitions of residue-class-wise affine mappings and -groups can be
generalized in an obvious way to suitable rings other than{\nobreakspace}$\Z$. In fact, this package provides also some support for residue-class-wise
affine groups over semilocalizations of{\nobreakspace}$\Z$ and over univariate polynomial rings over finite fields. The former of these
rings have been chosen as examples of rings with only finitely prime elements,
and the latter have been chosen as examples of rings with nonzero
characteristic. }

 \pagebreak[4]  
\section{\textcolor{Chapter }{Entering residue-class-wise affine mappings}}\label{sec:EnteringRcwaMappings}
\logpage{[ 2, 2, 0 ]}
\hyperdef{L}{X86BC55648302D643}{}
{
  Entering an rcwa mapping of{\nobreakspace}$\Z$ requires giving the modulus{\nobreakspace}$m$ and the coefficients $a_{r(m)}$, $b_{r(m)}$ and{\nobreakspace}$c_{r(m)}$ for $r(m)$ running over the residue classes (mod{\nobreakspace}$m$). 

 This can be done easiest by \texttt{RcwaMapping( \mbox{\texttt{\slshape coeffs}} )}, where \mbox{\texttt{\slshape coeffs}} is a list of $m$ coefficient triples \texttt{coeffs[}$r+1$\texttt{]{\nobreakspace}= [}$a_{r(m)}$, $b_{r(m)}$, $c_{r(m)}$\texttt{]}, with $r$ running from 0 to{\nobreakspace}$m-1$. 

 If some coefficient $c_{r(m)}$ is zero or if images of some integers under the mapping to be defined would
not be integers, an error message is printed and a break loop is entered. For
example, the coefficient triple \texttt{[1,4,3]} is not allowed at the first position. The reason for this is that not all
integers congruent to $1 \cdot 0 + 4 = 4${\nobreakspace}mod{\nobreakspace}$m$ are divisible by{\nobreakspace}3. 

 For the general constructor for rcwa mappings, see \texttt{RcwaMapping} (\ref{RcwaMapping:by ring, modulus and list of coefficients}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> T := RcwaMapping([[1,0,2],[3,1,2]]); # The Collatz mapping.
  <rcwa mapping of Z with modulus 2>
  gap> [ IsSurjective(T), IsInjective(T) ];
  [ true, false ]
  gap> SetName(T,"T"); Display(T);
  
  Surjective rcwa mapping of Z with modulus 2
  
                  n mod 2                |                 n^T
  ---------------------------------------+--------------------------------------
    0                                    | n/2
    1                                    | (3n + 1)/2
  
  gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]); SetName(a,"a");
  <rcwa mapping of Z with modulus 3>
  gap> IsBijective(a);
  true
  gap> Display(a); # This is Collatz' permutation:
  
  Bijective rcwa mapping of Z with modulus 3
  
                  n mod 3                |                 n^a
  ---------------------------------------+--------------------------------------
    0                                    | 2n/3
    1                                    | (4n - 1)/3
    2                                    | (4n + 1)/3
  
  gap> Support(a);
  Z \ [ -1, 0, 1 ]
  gap> Cycle(a,44);
  [ 44, 59, 79, 105, 70, 93, 62, 83, 111, 74, 99, 66 ]
  
\end{Verbatim}
 \pagebreak[4] \noindent There is computational evidence for the conjecture that any residue-class-wise
affine permutation of{\nobreakspace}$\Z$ can be factored into members of the following three series of permutations of
particularly simple structure (cp. \texttt{FactorizationIntoCSCRCT} (\ref{FactorizationIntoCSCRCT:for an rcwa permutation of Z})): 

\subsection{\textcolor{Chapter }{ClassShift (r, m)}}
\logpage{[ 2, 2, 1 ]}\nobreak
\hyperdef{L}{X86B611BD7EED62A1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ClassShift({\slshape r, m})\index{ClassShift@\texttt{ClassShift}!r, m}
\label{ClassShift:r, m}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ClassShift({\slshape cl})\index{ClassShift@\texttt{ClassShift}!cl}
\label{ClassShift:cl}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The class shift $\nu_{r(m)}$. 



 The \emph{class shift} $\nu_{r(m)}$ is the rcwa mapping of{\nobreakspace}$\Z$ which maps $n \in r(m)$ to $n + m$ and which fixes $\Z \setminus r(m)$ pointwise. 

 In the one-argument form, the argument{\nobreakspace}\mbox{\texttt{\slshape cl}} stands for the residue class{\nobreakspace}$r(m)$. Enclosing the argument list in list brackets is permitted. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Display(ClassShift(5,12));    
  
  Tame bijective rcwa mapping of Z with modulus 12, of order infinity
  
                 n mod 12                |          n^ClassShift(5,12)
  ---------------------------------------+--------------------------------------
     0  1  2  3  4  6  7  8  9 10 11     | n
     5                                   | n + 12
  
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ClassReflection (r, m)}}
\logpage{[ 2, 2, 2 ]}\nobreak
\hyperdef{L}{X7896C5417E3692B4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ClassReflection({\slshape r, m})\index{ClassReflection@\texttt{ClassReflection}!r, m}
\label{ClassReflection:r, m}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ClassReflection({\slshape cl})\index{ClassReflection@\texttt{ClassReflection}!cl}
\label{ClassReflection:cl}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The class reflection $\varsigma_{r(m)}$. 



 The \emph{class reflection} $\varsigma_{r(m)}$ is the rcwa mapping of{\nobreakspace}$\Z$ which maps $n \in r(m)$ to $-n + 2r$ and which fixes $\Z \setminus r(m)$ pointwise, where it is understood that $0 \leq r < m$. 

 In the one-argument form, the argument{\nobreakspace}\mbox{\texttt{\slshape cl}} stands for the residue class{\nobreakspace}$r(m)$. Enclosing the argument list in list brackets is permitted. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Display(ClassReflection(5,9));
  
  Bijective rcwa mapping of Z with modulus 9, of order 2
  
                  n mod 9                |        n^ClassReflection(5,9)
  ---------------------------------------+--------------------------------------
    0 1 2 3 4 6 7 8                      | n
    5                                    | -n + 10
  
  
\end{Verbatim}
 }

 \pagebreak[4] 

\subsection{\textcolor{Chapter }{ClassTransposition (r1, m1, r2, m2)}}
\logpage{[ 2, 2, 3 ]}\nobreak
\hyperdef{L}{X8716A75F7DD1C46B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ClassTransposition({\slshape r1, m1, r2, m2})\index{ClassTransposition@\texttt{ClassTransposition}!r1, m1, r2, m2}
\label{ClassTransposition:r1, m1, r2, m2}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ClassTransposition({\slshape cl1, cl2})\index{ClassTransposition@\texttt{ClassTransposition}!cl1, cl2}
\label{ClassTransposition:cl1, cl2}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The class transposition $\tau_{r_1(m_1),r_2(m_2)}$. 



 Given two disjoint residue classes $r_1(m_1)$ and $r_2(m_2)$ of the integers, the \emph{class transposition} $\tau_{r_1(m_1),r_2(m_2)}$ $\in$ RCWA($\Z$) is defined as the involution which interchanges $r_1+km_1$ and $r_2+km_2$ for any integer{\nobreakspace}$k$ and which fixes all other points. It is understood that $m_1$ and{\nobreakspace}$m_2$ are positive, that $0 \leq r_1 < m_1$ and that $0 \leq r_2 < m_2$. For a \emph{generalized class transposition}, the latter assumptions are not made. 

 The class transposition $\tau_{r_1(m_1),r_2(m_2)}$ interchanges the residue classes $r_1(m_1)$ and $r_2(m_2)$ and fixes the complement of their union pointwise. 

 \index{TransposedClasses@\texttt{TransposedClasses}!of a class transposition} In the four-argument form, the arguments \mbox{\texttt{\slshape r1}}, \mbox{\texttt{\slshape m1}}, \mbox{\texttt{\slshape r2}} and{\nobreakspace}\mbox{\texttt{\slshape m2}} stand for $r_1$, $m_1$, $r_2$ and{\nobreakspace}$m_2$, respectively. In the two-argument form, the arguments \mbox{\texttt{\slshape cl1}} and{\nobreakspace}\mbox{\texttt{\slshape cl2}} stand for the residue classes $r_1(m_1)$ and{\nobreakspace}$r_2(m_2)$, respectively. Enclosing the argument list in list brackets is permitted. The
residue classes $r_1(m_1)$ and $r_2(m_2)$ are stored as an attribute \texttt{TransposedClasses}. 

 \index{SplittedClassTransposition@\texttt{SplittedClassTransposition}!for a class transposition and a number of factors} A class transposition can be written as a product of any given number $k$ of class transpositions. Such a decomposition can be obtained by \texttt{SplittedClassTransposition(\mbox{\texttt{\slshape ct}},\mbox{\texttt{\slshape k}})}. 

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Display(ClassTransposition(1,2,8,10));
  
  Bijective rcwa mapping of Z with modulus 10, of order 2
  
                 n mod 10                |    n^ClassTransposition(1,2,8,10)
  ---------------------------------------+--------------------------------------
     0  2  4  6                          | n
     1  3  5  7  9                       | 5n + 3
     8                                   | (n - 3)/5
  
  
\end{Verbatim}
 }

 \noindent The set of all class transpositions of the ring of integers generates the
simple group CT($\Z$) mentioned in Chapter{\nobreakspace}\ref{ch:AboutRCWA}. This group has a representation as a \textsf{GAP} object -- see{\nobreakspace}\texttt{CT} (\ref{CT:the group generated by all class transpositions of a ring}). The set of all generalized class transpositions of{\nobreakspace}$\Z$ generates a simple group as well, cp.{\nobreakspace}\cite{Kohl06b}. 

 Class shifts, class reflections and class transpositions of rings $R$ other than $\Z$ are defined in an entirely analogous way -- all one needs to do is to replace $\Z$ by{\nobreakspace}$R$ and to read $<$ and $\leq$ in the sense of the ordering used by{\nobreakspace}\textsf{GAP}. They can also be entered basically as described above -- just prepend the
desired ring{\nobreakspace}$R$ to the argument list. Often also a sensible ``default ring'' ($\rightarrow$ \texttt{DefaultRing} in the \textsf{GAP} Reference Manual) is chosen if that optional first argument is omitted. 

 \pagebreak[4] On rings which have more than two units, there is another basic series of rcwa
permutations which generalizes class reflections: 

\subsection{\textcolor{Chapter }{ClassRotation (r, m, u)}}
\logpage{[ 2, 2, 4 ]}\nobreak
\hyperdef{L}{X87EB8C1C87F78A17}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ClassRotation({\slshape r, m, u})\index{ClassRotation@\texttt{ClassRotation}!r, m, u}
\label{ClassRotation:r, m, u}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ClassRotation({\slshape cl, u})\index{ClassRotation@\texttt{ClassRotation}!cl, u}
\label{ClassRotation:cl, u}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The class rotation $\rho_{r(m),u}$. 



 Given a residue class $r(m)$ and a unit{\nobreakspace}$u$ of a suitable ring{\nobreakspace}$R$, the \emph{class rotation} $\rho_{r(m),u}$ is the rcwa mapping which maps $n \in r(m)$ to $un + (1-u)r$ and which fixes $R \setminus r(m)$ pointwise. Class rotations generalize class reflections, as we have $\rho_{r(m),-1} = \varsigma_{r(m)}$. 

 \index{RotationFactor@\texttt{RotationFactor}!of a class rotation} In the two-argument form, the argument{\nobreakspace}\mbox{\texttt{\slshape cl}} stands for the residue class{\nobreakspace}$r(m)$. Enclosing the argument list in list brackets is permitted. The argument \mbox{\texttt{\slshape u}} is stored as an attribute \texttt{RotationFactor}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Display(ClassRotation(ResidueClass(Z_pi(2),2,1),1/3));
  
  Tame bijective rcwa mapping of Z_( 2 ) with modulus 2, of order infinity
  
                  n mod 2                |       n^ClassRotation(1,2,1/3)
  ---------------------------------------+--------------------------------------
    0                                    | n
    1                                    | 1/3 n + 2/3
  
  gap> x := Indeterminate(GF(8),1);; SetName(x,"x");
  gap> R := PolynomialRing(GF(8),1);;
  gap> Display(ClassRotation(1,x,Z(8)*One(R)));
  
  Bijective rcwa mapping of GF(2^3)[x] with modulus x, of order 7
  
           P mod x          |        P^(ClassRotation(Z(2)^0,x,Z(2^3)))
  --------------------------+---------------------------------------------------
   0*Z(2)   Z(2^3)          | 
   Z(2^3)^2 Z(2^3)^3        | 
   Z(2^3)^4 Z(2^3)^5        | 
   Z(2^3)^6                 | P
   Z(2)^0                   | Z(2^3)*P + Z(2^3)^3
  
  
\end{Verbatim}
 }

 \index{IsClassShift@\texttt{IsClassShift}!for an rcwa mapping} \index{IsClassReflection@\texttt{IsClassReflection}!for an rcwa mapping} \index{IsClassRotation@\texttt{IsClassRotation}!for an rcwa mapping} \index{IsClassTransposition@\texttt{IsClassTransposition}!for an rcwa mapping} \index{IsGeneralizedClassTransposition@\texttt{IsGeneralizedClassTransposition}!for an rcwa mapping} There are properties \texttt{IsClassShift}, \texttt{IsClassReflection}, \texttt{IsClassRotation}, \texttt{IsClassTransposition} and \texttt{IsGeneralizedClassTransposition}, which indicate whether a given rcwa mapping belongs to the corresponding
series. \index{Name@\texttt{Name}!for cs / cr / ct} By default, class shifts, class reflections, class transpositions and class
rotations are given descriptive names of the form \texttt{Class...(...)}. They can be given user-defined names upon creation via the option \texttt{Name}. Setting the \texttt{Name} attribute can be avoided by passing the empty string. 

 \pagebreak[4] In the sequel, a description of the general-purpose constructor for rcwa
mappings is given. This might look a bit technical on a first glance, but
knowing all possible ways of entering an rcwa mapping is by no means necessary
for understanding this manual or for using this package. 
\subsection{\textcolor{Chapter }{ RcwaMapping (the general constructor) }}\logpage{[ 2, 2, 5 ]}
\hyperdef{L}{X7D87A85584BA7E48}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping({\slshape R, m, coeffs})\index{RcwaMapping@\texttt{RcwaMapping}!by ring, modulus and list of coefficients}
\label{RcwaMapping:by ring, modulus and list of coefficients}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping({\slshape R, coeffs})\index{RcwaMapping@\texttt{RcwaMapping}!by ring and list of coefficients}
\label{RcwaMapping:by ring and list of coefficients}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping({\slshape coeffs})\index{RcwaMapping@\texttt{RcwaMapping}!by list of coefficients}
\label{RcwaMapping:by list of coefficients}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping({\slshape perm, range})\index{RcwaMapping@\texttt{RcwaMapping}!by permutation and range}
\label{RcwaMapping:by permutation and range}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping({\slshape m, values})\index{RcwaMapping@\texttt{RcwaMapping}!by modulus and list of values}
\label{RcwaMapping:by modulus and list of values}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping({\slshape pi, coeffs})\index{RcwaMapping@\texttt{RcwaMapping}!by set of noninvertible primes and list of coefficients}
\label{RcwaMapping:by set of noninvertible primes and list of coefficients}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping({\slshape q, m, coeffs})\index{RcwaMapping@\texttt{RcwaMapping}!by finite field size, modulus and list of coefficients}
\label{RcwaMapping:by finite field size, modulus and list of coefficients}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping({\slshape P1, P2})\index{RcwaMapping@\texttt{RcwaMapping}!by two partitions of a ring into residue classes}
\label{RcwaMapping:by two partitions of a ring into residue classes}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping({\slshape cycles})\index{RcwaMapping@\texttt{RcwaMapping}!by residue class cycles}
\label{RcwaMapping:by residue class cycles}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 An rcwa mapping. 



 In all cases the argument{\nobreakspace}\mbox{\texttt{\slshape R}} is the underlying ring, \mbox{\texttt{\slshape m}} is the modulus and \mbox{\texttt{\slshape coeffs}} is the coefficient list. A coefficient list for an rcwa mapping with modulus $m$ consists of $|R/mR|$ coefficient triples \texttt{[}$a_{r(m)}$, $b_{r(m)}$, $c_{r(m)}$\texttt{]}. Their ordering is determined by the ordering of the representatives of the
residue classes (mod{\nobreakspace}$m$) in the sorted list returned by \texttt{AllResidues(\mbox{\texttt{\slshape R}}, \mbox{\texttt{\slshape m}})}. In case $R = \Z$ this means that the coefficient triple for the residue class $0(m)$ comes first and is followed by the one for $1(m)$, the one for $2(m)$ and so on. 

 In case one or several of the arguments \mbox{\texttt{\slshape R}}, \mbox{\texttt{\slshape m}} and \mbox{\texttt{\slshape coeffs}} are omitted or replaced by other arguments, the former are either derived from
the latter or default values are taken. The meaning of the other arguments is
defined in the detailed description of the particular methods given in the
sequel: The above methods return the rcwa mapping 
\begin{description}
\item[{(a)}]  of \mbox{\texttt{\slshape R}} with modulus \mbox{\texttt{\slshape m}} and coefficients \mbox{\texttt{\slshape coeffs}}, 
\item[{(b)}]  of \mbox{\texttt{\slshape R}} = $\Z$ or \mbox{\texttt{\slshape R}} = $\Z_{(\pi)}$ with modulus \texttt{Length(\mbox{\texttt{\slshape coeffs}})} and coefficients \mbox{\texttt{\slshape coeffs}}, 
\item[{(c)}]  of \mbox{\texttt{\slshape R}} = $\Z$ with modulus \texttt{Length(\mbox{\texttt{\slshape coeffs}})} and coefficients \mbox{\texttt{\slshape coeffs}}, 
\item[{(d)}]  of \mbox{\texttt{\slshape R}} = $\Z$, permuting any set \texttt{\mbox{\texttt{\slshape range}}+k*Length(\mbox{\texttt{\slshape range}})} like \mbox{\texttt{\slshape perm}} permutes \mbox{\texttt{\slshape range}}, 
\item[{(e)}]  of \mbox{\texttt{\slshape R}} = $\Z$ with modulus \mbox{\texttt{\slshape m}} and values given by a list \mbox{\texttt{\slshape val}} of 2 pairs \texttt{[}preimage\texttt{, }image\texttt{]} per residue class (mod \mbox{\texttt{\slshape m}}), 
\item[{(f)}]  of \mbox{\texttt{\slshape R}} = $\Z_{(\pi)}$ with modulus \texttt{Length(\mbox{\texttt{\slshape coeffs}})} and coefficients \mbox{\texttt{\slshape coeffs}} (the set of primes $\pi$ which denotes the underlying ring is passed as argument \mbox{\texttt{\slshape pi}}), 
\item[{(g)}]  of \mbox{\texttt{\slshape R}} = GF(\mbox{\texttt{\slshape q}})[\mbox{\texttt{\slshape x}}] with modulus \mbox{\texttt{\slshape m}} and coefficients \mbox{\texttt{\slshape coeffs}}, 
\item[{(h)}]  a bijective rcwa mapping which induces a bijection between the partitions \mbox{\texttt{\slshape P1}} and \mbox{\texttt{\slshape P2}} of{\nobreakspace}\mbox{\texttt{\slshape R}} into residue classes and which is affine on the elements of \mbox{\texttt{\slshape P1}}, or 
\item[{(i)}]  a bijective rcwa mapping with ``residue class cycles'' given by a list \mbox{\texttt{\slshape cycles}} of lists of pairwise disjoint residue classes which are to be permuted
cyclically, each, respectively. 
\end{description}
 The methods for the operation \texttt{RcwaMapping} perform a number of argument checks, which can be skipped by using \texttt{RcwaMappingNC} instead. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> R := PolynomialRing(GF(2),1);; x := Indeterminate(GF(2),1);; SetName(x,"x");
  gap> RcwaMapping(R,x+1,[[1,0,x+One(R)],[x+One(R),0,1]]*One(R));      # (a)
  <rcwa mapping of GF(2)[x] with modulus x+Z(2)^0>
  gap> RcwaMapping(Z_pi(2),[[1/3,0,1]]);                               # (b)
  Rcwa mapping of Z_( 2 ): n -> 1/3 n
  gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);                   # (c)
  <rcwa mapping of Z with modulus 3>
  gap> RcwaMapping((1,2,3),[1..4]);                                    # (d)
  <bijective rcwa mapping of Z with modulus 4, of order 3>
  gap> T = RcwaMapping(2,[[1,2],[2,1],[3,5],[4,2]]);                   # (e)
  true
  gap> RcwaMapping([2],[[1/3,0,1]]);                                   # (f)
  Rcwa mapping of Z_( 2 ): n -> 1/3 n
  gap> RcwaMapping(2,x+1,[[1,0,x+One(R)],[x+One(R),0,1]]*One(R));      # (g)
  <rcwa mapping of GF(2)[x] with modulus x+Z(2)^0>
  gap> a = RcwaMapping(List([[0,3],[1,3],[2,3]],ResidueClass),
  >                    List([[0,2],[1,4],[3,4]],ResidueClass));        # (h)
  true
  gap> RcwaMapping([List([[0,2],[1,4],[3,8],[7,16]],ResidueClass)]);   # (i)
  <bijective rcwa mapping of Z with modulus 16, of order 4>
  gap> Cycle(last,ResidueClass(0,2));
  [ 0(2), 1(4), 3(8), 7(16) ]
  
\end{Verbatim}
 }

 Rcwa mappings of $\Z$ can be ``translated'' to rcwa mappings of some semilocalization $\Z_{(\pi)}$ of{\nobreakspace}$\Z$: 

\subsection{\textcolor{Chapter }{LocalizedRcwaMapping (for an rcwa mapping of Z and a prime)}}
\logpage{[ 2, 2, 6 ]}\nobreak
\hyperdef{L}{X7F1A559387D0226E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LocalizedRcwaMapping({\slshape f, p})\index{LocalizedRcwaMapping@\texttt{LocalizedRcwaMapping}!for an rcwa mapping of Z and a prime}
\label{LocalizedRcwaMapping:for an rcwa mapping of Z and a prime}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SemilocalizedRcwaMapping({\slshape f, pi})\index{SemilocalizedRcwaMapping@\texttt{SemilocalizedRcwaMapping}!for an rcwa mapping of Z and a set of primes}
\label{SemilocalizedRcwaMapping:for an rcwa mapping of Z and a set of primes}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The rcwa mapping of $\Z_{(p)}$ respectively $\Z_{(\pi)}$ with the same coefficients as the rcwa mapping \mbox{\texttt{\slshape f}} of{\nobreakspace}$\Z$. 



 The argument \mbox{\texttt{\slshape p}} or \mbox{\texttt{\slshape pi}} must be a prime or a set of primes, respectively. The argument{\nobreakspace}\mbox{\texttt{\slshape f}} must be an rcwa mapping of{\nobreakspace}$\Z$ whose modulus is a power of{\nobreakspace}\mbox{\texttt{\slshape p}}, or whose modulus has only prime divisors which lie in{\nobreakspace}\mbox{\texttt{\slshape pi}}, respectively. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> T := RcwaMapping([[1,0,2],[3,1,2]]);; # The Collatz mapping.
  gap> Cycle(LocalizedRcwaMapping(T,2),131/13);
  [ 131/13, 203/13, 311/13, 473/13, 716/13, 358/13, 179/13, 275/13, 419/13, 
    635/13, 959/13, 1445/13, 2174/13, 1087/13, 1637/13, 2462/13, 1231/13, 
    1853/13, 2786/13, 1393/13, 2096/13, 1048/13, 524/13, 262/13 ]
  
\end{Verbatim}
 }

 \index{View@\texttt{View}!for an rcwa mapping} \index{Display@\texttt{Display}!for an rcwa mapping} \index{Print@\texttt{Print}!for an rcwa mapping} \index{String@\texttt{String}!for an rcwa mapping} \noindent Rcwa mappings can be \texttt{View}ed, \texttt{Display}ed, \texttt{Print}ed and written to a \texttt{String}. The output of the \texttt{View} method is kept reasonably short. In most cases it does not describe an rcwa
mapping completely. In these cases the output is enclosed in brackets. The
output of the methods for \texttt{Display} and \texttt{Print} describe an rcwa mapping in full. The \texttt{Print}ed representation of an rcwa mapping is \textsf{GAP} - readable if and only if the \texttt{Print}ed representation of the elements of the underlying ring is so. 

 \index{LaTeX@\texttt{LaTeX}!for an rcwa mapping} \index{LaTeXObj@\texttt{LaTeXObj}!for an rcwa mapping} There is also a method for \texttt{LaTeX}, respectively \texttt{LaTeXObj}. The output of this method makes use of the {\LaTeX} macro package \textsf{amsmath}. If the option \mbox{\texttt{\slshape Factorization}} is set and the argument is bijective, a factorization into class shifts, class
reflections, class transpositions and prime switches is printed (cp. \texttt{FactorizationIntoCSCRCT} (\ref{FactorizationIntoCSCRCT:for an rcwa permutation of Z})). For rcwa mappings with modulus greater than{\nobreakspace}1, an indentation
by \mbox{\texttt{\slshape Indentation}} characters can be obtained by setting this option value
accor\texttt{\symbol{92}}-dingly. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Print(LaTeXObj(T));
  n \ \longmapsto \
  \begin{cases}
    n/2        & \text{if} \ n \in 0(2), \\
    (3n + 1)/2 & \text{if} \ n \in 1(2).
  \end{cases}
  
\end{Verbatim}
 \index{LaTeXAndXDVI@\texttt{LaTeXAndXDVI}!for an rcwa mapping} There is an operation \texttt{LaTeXAndXDVI} which displays an rcwa mapping in an \textsf{xdvi} window. This works as follows: The string returned by the \texttt{LaTeXObj} - method described above is inserted into a {\LaTeX} template file. This file is {\LaTeX}'ed, and the result is shown with \textsf{xdvi}. Calling \texttt{Display} with option \mbox{\texttt{\slshape xdvi}} has the same effect. The operation \texttt{LaTeXAndXDVI} is only available on UNIX systems, and requires suitable installations of {\LaTeX} and \textsf{xdvi}. }

  
\section{\textcolor{Chapter }{Basic arithmetic for residue-class-wise affine mappings}}\label{sec:BasicArithmeticForRcwaMappings}
\logpage{[ 2, 3, 0 ]}
\hyperdef{L}{X78E796B8824C4FC8}{}
{
  \index{rcwa mapping@rcwa mapping!arithmetic operations} \index{Order@\texttt{Order}!of an rcwa permutation} \index{IsTame@\texttt{IsTame}!for an rcwa mapping} 

 Testing rcwa mappings for equality requires only comparing their coefficient
lists, hence is cheap. Rcwa mappings can be multiplied, thus there is a method
for \texttt{*}. Bijective rcwa mappings can also be inverted, thus there is a method for \texttt{Inverse}. The latter method is usually accessed by raising a mapping to a power with
negative exponent. Multiplying, inverting and computing powers of tame rcwa
mappings is cheap. Computing powers of wild mappings is usually expensive --
runtime and memory requirements normally grow approximately exponentially with
the exponent. How expensive multiplying a couple of wild mappings is, varies
very much. In any case, the amount of memory required for storing an rcwa
mapping is proportional to its modulus. Whether a given mapping is tame or
wild can be determined by the operation \texttt{IsTame}. There is a method for \texttt{Order}, which can not only compute a finite order, but which can also detect
infinite order. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> T := RcwaMapping([[1,0,2],[3,1,2]]);;          # The Collatz mapping.
  gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; # Collatz' permutation.
  gap> List([-4..4],k->Modulus(a^k));
  [ 256, 64, 16, 4, 1, 3, 9, 27, 81 ]
  gap> IsTame(T) or IsTame(a);
  false
  gap> IsTame(ClassShift(0,1)) and IsTame(ClassTransposition(0,2,1,2));
  true
  gap> T^2*a*T*a^-3;
  <rcwa mapping of Z with modulus 768>
  gap> (ClassShift(1,3)*ClassReflection(2,7))^1000000;
  <bijective rcwa mapping of Z with modulus 21>
  
\end{Verbatim}
 \index{IsInjective@\texttt{IsInjective}!for an rcwa mapping} \index{IsSurjective@\texttt{IsSurjective}!for an rcwa mapping} \index{IsBijective@\texttt{IsBijective}!for an rcwa mapping} \index{Image@\texttt{Image}!of an rcwa mapping} There are methods installed for \texttt{IsInjective}, \texttt{IsSurjective}, \texttt{IsBijective} and \texttt{Image}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> [ IsInjective(T), IsSurjective(T), IsBijective(a) ];
  [ false, true, true ]
  gap> Image(RcwaMapping([[2,0,1]]));
  0(2)
  
\end{Verbatim}
 \index{rcwa mapping@rcwa mapping!images under} Images of elements, of finite sets of elements and of unions of finitely many
residue classes of the source of an rcwa mapping can be computed with \texttt{\texttt{\symbol{94}}}, the same symbol as used for exponentiation and conjugation. The same works
for partitions of the source into a finite number of residue classes. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> 15^T;
  23
  gap> ResidueClass(1,2)^T;
  2(3)
  gap> List([[0,3],[1,3],[2,3]],ResidueClass)^a;
  [ 0(2), 1(4), 3(4) ]
  
\end{Verbatim}
 \index{PreImageElm@\texttt{PreImageElm}!of a ring element under an rcwa mapping} \index{PreImagesElm@\texttt{PreImagesElm}!of a ring element under an rcwa mapping} \index{PreImage@\texttt{PreImage}!of a set of ring elements under an rcwa mapping} \index{PreImage@\texttt{PreImage}!of a residue class union under an rcwa mapping} For computing preimages of elements under rcwa mappings, there are methods for \texttt{PreImageElm} and \texttt{PreImagesElm}. The preimage of a finite set of ring elements or of a union of finitely many
residue classes under an rcwa mapping can be computed by \texttt{PreImage}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> PreImagesElm(T,8);
  [ 5, 16 ]
  gap> PreImage(T,ResidueClass(Integers,3,2));
  Z \ 0(6) U 2(6)
  gap> M := [1];; l := [1];;
  gap> while Length(M) < 10000 do M := PreImage(T,M); Add(l,Length(M)); od; l;
  [ 1, 1, 2, 2, 4, 5, 8, 10, 14, 18, 26, 36, 50, 67, 89, 117, 157, 208, 277, 
    367, 488, 649, 869, 1154, 1534, 2039, 2721, 3629, 4843, 6458, 8608, 11472 ]
  
\end{Verbatim}
 \index{Support@\texttt{Support}!of an rcwa mapping} \index{MovedPoints@\texttt{MovedPoints}!of an rcwa mapping} \index{RestrictedPerm@\texttt{RestrictedPerm}!for an rcwa permutation and a residue class union} There is a method for the operation \texttt{Support} for computing the support of an rcwa mapping. A synonym for \texttt{Support} is \texttt{MovedPoints}. There is also a method for \texttt{RestrictedPerm} for computing the restriction of a bijective rcwa mapping to a union of
residue classes which it fixes setwise. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List([a,a^2],Support);
  [ Z \ [ -1, 0, 1 ], Z \ [ -3, -2, -1, 0, 1, 2, 3 ] ]
  gap> RestrictedPerm(ClassShift(0,2)*ClassReflection(1,2),ResidueClass(0,2));
  <rcwa mapping of Z with modulus 2>
  gap> last = ClassShift(0,2);
  true
  
\end{Verbatim}
 Rcwa mappings can be added and subtracted pointwise. However, please note that
the set of rcwa mappings of a ring does not form a ring under \texttt{+} and \texttt{*}. 

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> b := ClassShift(0,3) * a;;
  gap> [ Image((a + b)), Image((a - b)) ];
  [ 2(4), [ -2, 0 ] ]
  
\end{Verbatim}
 \index{Modulus@\texttt{Modulus}!of an rcwa mapping} \index{Mod@\texttt{Mod}!for an rcwa mapping} \index{Coefficients@\texttt{Coefficients}!of an rcwa mapping} \index{rcwa mapping@rcwa mapping!coercion} \index{rcwa group@rcwa group!coercion} There are operations \texttt{Modulus} (abbreviated \texttt{Mod}) and \texttt{Coefficients} for retrieving the modulus and the coefficient list of an rcwa mapping. The
meaning of the return values is as described in Section{\nobreakspace}\ref{sec:EnteringRcwaMappings}. 

 General documentation for most operations mentioned in this section can be
found in the \textsf{GAP} reference manual. For rcwa mappings of rings other than $\Z$, not for all operations applicable methods are available. 

 As in general a subring relation $R_1<R_2$ does \emph{not} give rise to a natural embedding of RCWA($R_1$) into RCWA($R_2$), there is no coercion between rcwa mappings or rcwa groups over different
rings. }

  
\section{\textcolor{Chapter }{ Attributes and properties of residue-class-wise affine mappings }}\label{sec:AttributesAndPropertiesOfRcwaMappings}
\logpage{[ 2, 4, 0 ]}
\hyperdef{L}{X861C5DE6812425F1}{}
{
  \index{Multiplier@\texttt{Multiplier}!of an rcwa mapping} \index{Mult@\texttt{Mult}!for an rcwa mapping} \index{Divisor@\texttt{Divisor}!of an rcwa mapping} \index{Div@\texttt{Div}!for an rcwa mapping} \index{PrimeSet@\texttt{PrimeSet}!of an rcwa mapping} \index{rcwa mapping@rcwa mapping!prime set} \index{integral@integral!definition} \index{rcwa mapping@rcwa mapping!integral} \index{IsIntegral@\texttt{IsIntegral}!for an rcwa mapping} \index{balanced@\texttt{balanced}!definition} \index{rcwa mapping@rcwa mapping!balanced} \index{IsBalanced@\texttt{IsBalanced}!for an rcwa mapping} \index{rcwa mapping@rcwa mapping!class-wise order-preserving} \index{IsClassWiseOrderPreserving@\texttt{IsClassWiseOrderPreserving}!for an rcwa mapping} \index{IsSignPreserving@\texttt{IsSignPreserving}!for an rcwa mapping} A number of basic attributes and properties of an rcwa mapping are derived
immediately from the coefficients of its affine partial mappings. This holds
for example for the multiplier and the divisor. These two values are stored as
attributes \texttt{Multiplier} and \texttt{Divisor}, or for short \texttt{Mult} and \texttt{Div}. The \emph{prime set} of an rcwa mapping is the set of prime divisors of the product of its modulus
and its multiplier. It is stored as an attribute \texttt{PrimeSet}. An rcwa mapping is called \emph{integral} if its divisor equals{\nobreakspace}1. An rcwa mapping is called \emph{balanced} if its multiplier and its divisor have the same prime divisors. An integral
mapping has the property \texttt{IsIntegral} and a balanced mapping has the property \texttt{IsBalanced}. An rcwa mapping of the ring of integers or of one of its semilocalizations
is called \emph{class-wise order-preserving} if and only if all coefficients $a_{r(m)}$ (cp.{\nobreakspace}Section{\nobreakspace}\ref{sec:basicdefinitions}) in the numerators of the affine partial mappings are positive. The
corresponding property is \texttt{IsClassWiseOrderPreserving}. An rcwa mapping of $\Z$ is called \emph{sign-preserving} if it does not map nonnegative integers to negative integers or vice versa.
The corresponding property is \texttt{IsSignPreserving}. All elements of the simple group CT($\Z$) generated by the set of all class transpositions are sign-preserving. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> u := RcwaMapping([[3,0,5],[9,1,5],[3,-1,5],[9,-2,5],[9,4,5]]);;
  gap> IsBijective(u);; Display(u);
  
  Bijective rcwa mapping of Z with modulus 5
  
                  n mod 5                |                 n^f
  ---------------------------------------+--------------------------------------
    0                                    | 3n/5
    1                                    | (9n + 1)/5
    2                                    | (3n - 1)/5
    3                                    | (9n - 2)/5
    4                                    | (9n + 4)/5
  
  gap> Multiplier(u);
  9
  gap> Divisor(u);
  5
  gap> PrimeSet(u);
  [ 3, 5 ]
  gap> IsIntegral(u) or IsBalanced(u);
  false
  gap> IsClassWiseOrderPreserving(u) and IsSignPreserving(u);
  true
  
\end{Verbatim}
 There are a couple of further attributes and operations related to the affine
partial mappings of an rcwa mapping: 

\subsection{\textcolor{Chapter }{LargestSourcesOfAffineMappings (for an rcwa mapping)}}
\logpage{[ 2, 4, 1 ]}\nobreak
\hyperdef{L}{X7C21406085B69C30}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LargestSourcesOfAffineMappings({\slshape f})\index{LargestSourcesOfAffineMappings@\texttt{LargestSourcesOfAffineMappings}!for an rcwa mapping}
\label{LargestSourcesOfAffineMappings:for an rcwa mapping}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 The coarsest partition of \texttt{Source(\mbox{\texttt{\slshape f}})} on whose elements the rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}} is affine. 



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> LargestSourcesOfAffineMappings(ClassShift(3,7));
  [ Z \ 3(7), 3(7) ]
  gap> LargestSourcesOfAffineMappings(ClassReflection(0,1));
  [ Integers ]
  gap> u := RcwaMapping([[3,0,5],[9,1,5],[3,-1,5],[9,-2,5],[9,4,5]]);;
  gap> List( [ u, u^-1 ], LargestSourcesOfAffineMappings );
  [ [ 0(5), 1(5), 2(5), 3(5), 4(5) ], [ 0(3), 1(3), 2(9), 5(9), 8(9) ] ]
  gap> kappa := ClassTransposition(2,4,3,4) * ClassTransposition(4,6,8,12)
  >           * ClassTransposition(3,4,4,6);
  <bijective rcwa mapping of Z with modulus 12>
  gap> LargestSourcesOfAffineMappings(kappa);
  [ 2(4), 1(4) U 0(12), 3(12) U 7(12), 4(12), 8(12), 11(12) ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{FixedPointsOfAffinePartialMappings (for an rcwa mapping)}}
\logpage{[ 2, 4, 2 ]}\nobreak
\hyperdef{L}{X7D6D0F2783AD02F4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FixedPointsOfAffinePartialMappings({\slshape f})\index{FixedPointsOfAffinePartialMappings@\texttt{FixedPointsOfAffinePartialMappings}!for an rcwa mapping}
\label{FixedPointsOfAffinePartialMappings:for an rcwa mapping}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 A list of the sets of fixed points of the affine partial mappings of the rcwa
mapping{\nobreakspace}\mbox{\texttt{\slshape f}} in the quotient field of its source. 



 The returned list contains entries for the restrictions of{\nobreakspace}\mbox{\texttt{\slshape f}} to all residue classes modulo \texttt{Mod(\mbox{\texttt{\slshape f}})}. A list entry can either be an empty set, the source of{\nobreakspace}\mbox{\texttt{\slshape f}} or a set of cardinality{\nobreakspace}1. The ordering of the entries
corresponds to the ordering of the residues in \texttt{AllResidues(Source(\mbox{\texttt{\slshape f}}),\mbox{\texttt{\slshape m}})}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> FixedPointsOfAffinePartialMappings(ClassShift(0,2));
  [ [  ], Rationals ]
  gap> List([1..3],k->FixedPointsOfAffinePartialMappings(T^k));
  [ [ [ 0 ], [ -1 ] ], [ [ 0 ], [ 1 ], [ 2 ], [ -1 ] ], 
    [ [ 0 ], [ -7 ], [ 2/5 ], [ -5 ], [ 4/5 ], [ 1/5 ], [ -10 ], [ -1 ] ] ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Multpk (for an rcwa mapping, a prime and an exponent)}}
\logpage{[ 2, 4, 3 ]}\nobreak
\hyperdef{L}{X7A2E308C860B46E3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Multpk({\slshape f, p, k})\index{Multpk@\texttt{Multpk}!for an rcwa mapping, a prime and an exponent}
\label{Multpk:for an rcwa mapping, a prime and an exponent}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The union of the residue classes $r(m)$ such that $p^k||a_{r(m)}$ if $k \geq 0$, and the union of the residue classes $r(m)$ such that $p^k||c_{r(m)}$ if $k \leq 0$. In this context, $m$ denotes the modulus of{\nobreakspace}\mbox{\texttt{\slshape f}}, and $a_{r(m)}$ and $c_{r(m)}$ denote the coefficients of{\nobreakspace}\mbox{\texttt{\slshape f}} as introduced in Section{\nobreakspace}\ref{sec:basicdefinitions}. 



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> T := RcwaMapping([[1,0,2],[3,1,2]]);; # The Collatz mapping.
  gap> [ Multpk(T,2,-1), Multpk(T,3,1) ];
  [ Integers, 1(2) ]
  gap> u := RcwaMapping([[3,0,5],[9,1,5],[3,-1,5],[9,-2,5],[9,4,5]]);;
  gap> [ Multpk(u,3,0), Multpk(u,3,1), Multpk(u,3,2), Multpk(u,5,-1) ];
  [ [  ], 0(5) U 2(5), Z \ 0(5) U 2(5), Integers ]
  
\end{Verbatim}
 }

 \index{ClassWiseOrderPreservingOn@\texttt{ClassWiseOrderPreservingOn}} \index{ClassWiseConstantOn@\texttt{ClassWiseConstantOn}} \index{ClassWiseOrderReversingOn@\texttt{ClassWiseOrderReversingOn}} There are attributes \texttt{ClassWiseOrderPreservingOn}, \texttt{ClassWiseConstantOn} and \texttt{ClassWiseOrderReversingOn} which store the union of the residue classes (mod{\nobreakspace}\texttt{Mod(\mbox{\texttt{\slshape f}})}) on which an rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}} of{\nobreakspace}$\Z$ or of a semilocalization thereof is class-wise order-preserving, class-wise
constant or class-wise order-reversing, respectively. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List([ClassTransposition(1,2,0,4),ClassShift(2,3),ClassReflection(2,5)],
  >          ClassWiseOrderPreservingOn );
  [ Integers, Integers, Z \ 2(5) ]
  
\end{Verbatim}
 Finally, there are epimorphisms from the subgroup of RCWA($\Z$) formed by all class-wise order-preserving elements to ($\Z$,+) and from RCWA($\Z$) itself to the cyclic group of order{\nobreakspace}2, respectively: 

\subsection{\textcolor{Chapter }{Determinant (of an rcwa mapping of Z)}}
\logpage{[ 2, 4, 4 ]}\nobreak
\hyperdef{L}{X7B1E53127D9AE52F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Determinant({\slshape f})\index{Determinant@\texttt{Determinant}!of an rcwa mapping of Z}
\label{Determinant:of an rcwa mapping of Z}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 The determinant of the rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}} of{\nobreakspace}$\Z$. 



 The \emph{determinant} of an affine mapping $n \mapsto (an+b)/c$ whose source is a residue class $r(m)$ is defined by $b/|a|m$. This definition is extended additively to determinants of rcwa mappings. 

 Let $f$ be an rcwa mapping of the integers, and let $m$ denote its modulus. Using the notation $f|_{r(m)}: n \mapsto (a_{r(m)} \cdot n + b_{r(m)})/c_{r(m)}$ for the affine partial mappings, the \emph{determinant} det($f$) of{\nobreakspace}$f$ is given by  
\[ \sum_{r(m) \in \Z/m\Z} b_{r(m)}/(|a_{r(m)}| \cdot m). \]
    The determinant mapping is an epimorphism from the group of all class-wise
order-preserving bijective rcwa mappings of $\Z$ to $(\Z,+)$, see{\nobreakspace}\cite{Kohl05}, Theorem{\nobreakspace}2.11.9. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List([ClassTransposition(0,4,5,12),ClassShift(3,7)],Determinant);
  [ 0, 1 ]
  gap> Determinant(ClassTransposition(0,4,5,12)*ClassShift(3,7)^100);   
  100
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Sign (of an rcwa permutation of Z)}}
\logpage{[ 2, 4, 5 ]}\nobreak
\hyperdef{L}{X8365EEEB82C946FD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Sign({\slshape g})\index{Sign@\texttt{Sign}!of an rcwa permutation of Z}
\label{Sign:of an rcwa permutation of Z}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 The sign of the bijective rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape g}} of{\nobreakspace}$\Z$. 



 Let $\sigma$ be an rcwa permutation of the integers, and let $m$ denote its modulus. Using the notation $\sigma|_{r(m)}: n \mapsto (a_{r(m)} \cdot n + b_{r(m)})/c_{r(m)}$ for the affine partial mappings, the \emph{sign} of{\nobreakspace}$\sigma$ is defined by  
\[ (-1)^{\displaystyle{{\rm det}(\sigma) + \sum_{r(m): \ a_{r(m)} < 0} \frac{m -
2r}{m}}}. \]
    The sign mapping is an epimorphism from RCWA($\Z$) to the group $\Z^\times$ of units of{\nobreakspace}$\Z$, see{\nobreakspace}\cite{Kohl05}, Theorem{\nobreakspace}2.12.8. Therefore the kernel of the sign mapping is a
normal subgroup of RCWA($\Z$) of index{\nobreakspace}2. The simple group CT($\Z$) is a subgroup of this kernel. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List([ClassTransposition(3,4,2,6),ClassShift(0,3),ClassReflection(2,5)],Sign);
  [ 1, -1, -1 ]
  gap> Sign (ClassTransposition(3,4,2,6)*ClassShift(0,3)*ClassReflection(2,5));
  1
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{Factoring residue-class-wise affine permutations}}\label{sec:FactoringRcwaMappings}
\logpage{[ 2, 5, 0 ]}
\hyperdef{L}{X8475F844869DD060}{}
{
  Factoring group elements into the members of some ``nice'' set of generators is often helpful. In this section we describe an operation
which attempts to solve this problem for the group RCWA($\Z$). Elements of finitely generated rcwa groups can be factored into generators ``as usual'', see{\nobreakspace}\texttt{PreImagesRepresentative} (\ref{PreImagesRepresentative:for an epi. from a free group to an rcwa group}). 

\subsection{\textcolor{Chapter }{FactorizationIntoCSCRCT (for an rcwa permutation of Z)}}
\logpage{[ 2, 5, 1 ]}\nobreak
\hyperdef{L}{X853885A182EC5104}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FactorizationIntoCSCRCT({\slshape g})\index{FactorizationIntoCSCRCT@\texttt{FactorizationIntoCSCRCT}!for an rcwa permutation of Z}
\label{FactorizationIntoCSCRCT:for an rcwa permutation of Z}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Factorization({\slshape g})\index{Factorization@\texttt{Factorization}!for an rcwa permutation of Z}
\label{Factorization:for an rcwa permutation of Z}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 A factorization of the bijective rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape g}} of{\nobreakspace}$\Z$ into class shifts, class reflections and class transpositions, provided that
such a factorization exists and the method finds it. 



 The method may return \texttt{fail}, stop with an error message or run into an infinite loop. If it returns a
result, this result is always correct. 

 The problem of obtaining a factorization as described is algorithmically
difficult, and this factorization routine is currently perhaps the most
sophisticated part of the \textsf{RCWA} package. Information about the progress of the factorization process can be
obtained by setting the info level of the Info class \texttt{InfoRCWA} (\ref{InfoRCWA}) to{\nobreakspace}2. 

 By default, prime switches ($\rightarrow$ \texttt{PrimeSwitch} (\ref{PrimeSwitch:p})) are taken as one factor. If the option \mbox{\texttt{\slshape ExpandPrimeSwitches}} is set, they are each decomposed into the 6 class transpositions given in the
definition. 

 By default, the factoring process begins with splitting off factors from the
right. This can be changed by setting the option \mbox{\texttt{\slshape Direction}} to \texttt{"from the left"}. 

 By default, a reasonably coarse respected partition of the integral mapping
occuring in the final stage of the algorithm is computed. This can be
suppressed by setting the option \mbox{\texttt{\slshape ShortenPartition}} equal to \texttt{false}. 

 By default, at the end it is checked whether the product of the determined
factors indeed equals \mbox{\texttt{\slshape g}}. This check can be suppressed by setting the option \mbox{\texttt{\slshape NC}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Factorization(Comm(ClassShift(0,3)*ClassReflection(1,2),ClassShift(0,2)));
  [ ClassReflection(2,3), ClassShift(2,6)^-1, ClassTransposition(0,6,2,6), 
    ClassTransposition(0,6,5,6) ]
  
\end{Verbatim}
 }

 For purposes of demonstrating the capabilities of the factorization routine,
in Section{\nobreakspace}\ref{sec:FactoringTheCollatzPermutation} Collatz' permutation is factored. Lothar Collatz has investigated this
permutation in{\nobreakspace}1932. Its cycle structure is unknown so far. 

 The permutations of the following kind play an important role in factoring
rcwa permutations of{\nobreakspace}$\Z$ into class shifts, class reflections and class transpositions: 

\subsection{\textcolor{Chapter }{PrimeSwitch (p)}}
\logpage{[ 2, 5, 2 ]}\nobreak
\hyperdef{L}{X861C74E97AE5DA3B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PrimeSwitch({\slshape p})\index{PrimeSwitch@\texttt{PrimeSwitch}!p}
\label{PrimeSwitch:p}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PrimeSwitch({\slshape p, k})\index{PrimeSwitch@\texttt{PrimeSwitch}!p, k}
\label{PrimeSwitch:p, k}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 In the one-argument form the \emph{prime switch} $\sigma_p := \tau_{0(8),1(2p)} \cdot \tau_{4(8),-1(2p)} \cdot \tau_{0(4),1(2p)}
\cdot \tau_{2(4),-1(2p)} \cdot \tau_{2(2p),1(4p)} \cdot \tau_{4(2p),2p+1(4p)}$, and in the two-argument form the restriction of $\sigma_p$ by $n \mapsto kn$. 



 For an odd prime $p$, the prime switch $\sigma_p$ is a bijective rcwa mapping of $\Z$ with modulus{\nobreakspace}$4p$, multiplier{\nobreakspace}$p$ and divisor{\nobreakspace}2. The key mathematical property of a prime switch
is that it is a product of class transpositions, but that its multiplier and
its divisor are coprime anyway. Prime switches can be distinguished from other
rcwa mappings by their \textsf{GAP} property \texttt{IsPrimeSwitch}. \index{IsPrimeSwitch@\texttt{IsPrimeSwitch}!for an rcwa mapping} 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Display(PrimeSwitch(3));
  
  Wild bijective rcwa mapping of Z with modulus 12
  
                 n mod 12                |           n^PrimeSwitch(3)
  ---------------------------------------+--------------------------------------
     0                                   | n/2
     1  7                                | n + 1
     2  6 10                             | (3n + 4)/2
     3  9                                | n
     4                                   | n - 3
     5  8 11                             | n - 1
  
  gap> Factorization(PrimeSwitch(3));
  [ ClassTransposition(1,6,0,8), ClassTransposition(5,6,4,8), 
    ClassTransposition(0,4,1,6), ClassTransposition(2,4,5,6), 
    ClassTransposition(2,6,1,12), ClassTransposition(4,6,7,12) ]
  
\end{Verbatim}
 }

 Obtaining a factorization of a bijective rcwa mapping into class shifts, class
reflections and class transpositions is particularly difficult if multiplier
and divisor are coprime. A prototype of permutations which have this property
has been introduced in a different context in{\nobreakspace}\cite{Keller99}: 

\subsection{\textcolor{Chapter }{mKnot (for an odd integer)}}
\logpage{[ 2, 5, 3 ]}\nobreak
\hyperdef{L}{X789CB69C7D97B0C4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{mKnot({\slshape m})\index{mKnot@\texttt{mKnot}!for an odd integer}
\label{mKnot:for an odd integer}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The permutation $g_m$ as introduced in{\nobreakspace}\cite{Keller99}. 



 The argument \mbox{\texttt{\slshape m}} must be an odd integer greater than{\nobreakspace}1. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Display(mKnot(5));
  
  Wild bijective rcwa mapping of Z with modulus 5
  
                  n mod 5                |              n^mKnot(5)
  ---------------------------------------+--------------------------------------
    0                                    | 6n/5
    1                                    | (4n + 1)/5
    2                                    | (6n - 2)/5
    3                                    | (4n + 3)/5
    4                                    | (6n - 4)/5
  
  
\end{Verbatim}
 }

 \noindent In his article, Timothy P. Keller shows that a permutation of this type cannot
have infinitely many cycles of any given finite length. }

  
\section{\textcolor{Chapter }{ Extracting roots of residue-class-wise affine mappings }}\label{sec:ExtractingRoots}
\logpage{[ 2, 6, 0 ]}
\hyperdef{L}{X8141065381B0942B}{}
{
  

\subsection{\textcolor{Chapter }{Root (k-th root of an rcwa mapping)}}
\logpage{[ 2, 6, 1 ]}\nobreak
\hyperdef{L}{X873692CE78433859}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Root({\slshape f, k})\index{Root@\texttt{Root}!k-th root of an rcwa mapping}
\label{Root:k-th root of an rcwa mapping}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 An rcwa mapping \texttt{g} such that \texttt{g\texttt{\symbol{94}}\mbox{\texttt{\slshape k}}=\mbox{\texttt{\slshape f}}}, provided that such a mapping exists and that there is a method available
which can determine it. 



 Currently, extracting roots is implemented for rcwa permutations of finite
order. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Root(ClassTransposition(0,2,1,2),100);
  <bijective rcwa mapping of Z with modulus 8>
  gap> Display(last);
  
  Bijective rcwa mapping of Z with modulus 8
  
                  n mod 8                |                 n^f
  ---------------------------------------+--------------------------------------
    0 1 2 3 4 5                          | n + 2
    6                                    | n - 5
    7                                    | n - 7
  
  gap> last^100 = ClassTransposition(0,2,1,2);
  true
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{ Special functions for non-bijective mappings }}\label{sec:NonBijectiveMappings}
\logpage{[ 2, 7, 0 ]}
\hyperdef{L}{X8322C6848305EC4C}{}
{
  

\subsection{\textcolor{Chapter }{RightInverse (of an injective rcwa mapping)}}
\logpage{[ 2, 7, 1 ]}\nobreak
\hyperdef{L}{X7AEFF16E86533633}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RightInverse({\slshape f})\index{RightInverse@\texttt{RightInverse}!of an injective rcwa mapping}
\label{RightInverse:of an injective rcwa mapping}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 A right inverse of the injective rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}}, i.e. a mapping $g$ such that \mbox{\texttt{\slshape f}}$g${\nobreakspace}={\nobreakspace}1. 



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> twice := 2*IdentityRcwaMappingOfZ;
  Rcwa mapping of Z: n -> 2n
  gap> twice * RightInverse(twice);
  IdentityMapping( Integers )
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{CommonRightInverse (of two injective rcwa mappings)}}
\logpage{[ 2, 7, 2 ]}\nobreak
\hyperdef{L}{X87C5B9CA7E319233}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CommonRightInverse({\slshape l, r})\index{CommonRightInverse@\texttt{CommonRightInverse}!of two injective rcwa mappings}
\label{CommonRightInverse:of two injective rcwa mappings}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 A mapping $d$ such that \mbox{\texttt{\slshape l}}$d$ = \mbox{\texttt{\slshape r}}$d$ = 1. 



 The mappings \mbox{\texttt{\slshape l}} and \mbox{\texttt{\slshape r}} must be injective, and their images must form a partition of their source. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> twice := 2*IdentityRcwaMappingOfZ; twiceplus1 := twice+1;
  Rcwa mapping of Z: n -> 2n
  Rcwa mapping of Z: n -> 2n + 1
  gap> Display(CommonRightInverse(twice,twiceplus1));
  
  Rcwa mapping of Z with modulus 2
  
                  n mod 2                |                 n^f
  ---------------------------------------+--------------------------------------
    0                                    | n/2
    1                                    | (n - 1)/2
  
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ImageDensity (of an rcwa mapping)}}
\logpage{[ 2, 7, 3 ]}\nobreak
\hyperdef{L}{X808D9EDF7BA27467}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ImageDensity({\slshape f})\index{ImageDensity@\texttt{ImageDensity}!of an rcwa mapping}
\label{ImageDensity:of an rcwa mapping}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 The \emph{image density} of the rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}}. 



 In the notation introduced in the definition of an rcwa mapping, the \emph{image density} of an rcwa mapping{\nobreakspace}$f$ is defined by $\frac{1}{m}$ $\sum_{r(m) \in R/mR} |R/c_{r(m)}R|/|R/a_{r(m)}R|$. The image density of an injective rcwa mapping is $\leq 1$, and the image density of a surjective rcwa mapping is $\geq 1$ (this can be seen easily). Thus in particular the image density of a bijective
rcwa mapping is{\nobreakspace}1. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> T := RcwaMapping([[1,0,2],[3,1,2]]);; # The Collatz mapping.
  gap> List( [ T, ClassShift(0,1), RcwaMapping([[2,0,1]]) ], ImageDensity );
  [ 4/3, 1, 1/2 ]
  
\end{Verbatim}
 }

 \index{InjectiveAsMappingFrom@\texttt{InjectiveAsMappingFrom}!for an rcwa mapping} Given an rcwa mapping \texttt{f}, the function \texttt{InjectiveAsMappingFrom} returns a set \texttt{S} such that the restriction of \texttt{f} to{\nobreakspace}\texttt{S} is injective, and such that the image of \texttt{S} under{\nobreakspace}\texttt{f} is the entire image of{\nobreakspace}\texttt{f}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> InjectiveAsMappingFrom(T);
  0(2)
  
\end{Verbatim}
 }

  
\section{\textcolor{Chapter }{ On trajectories and cycles of residue-class-wise affine mappings }}\label{sec:Trajectories}
\logpage{[ 2, 8, 0 ]}
\hyperdef{L}{X7A34724386A2E9F3}{}
{
  \textsf{RCWA} provides various methods to compute trajectories of rcwa mappings: 
\subsection{\textcolor{Chapter }{ Trajectory (methods for rcwa mappings) }}\logpage{[ 2, 8, 1 ]}
\hyperdef{L}{X7C72174D7CCB6348}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Trajectory({\slshape f, n, length})\index{Trajectory@\texttt{Trajectory}!for rcwa mapping, starting point, length}
\label{Trajectory:for rcwa mapping, starting point, length}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Trajectory({\slshape f, n, length, m})\index{Trajectory@\texttt{Trajectory}!for rcwa mapping, starting point, length, modulus}
\label{Trajectory:for rcwa mapping, starting point, length, modulus}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Trajectory({\slshape f, n, terminal})\index{Trajectory@\texttt{Trajectory}!for rcwa mapping, starting point, set of end points}
\label{Trajectory:for rcwa mapping, starting point, set of end points}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Trajectory({\slshape f, n, terminal, m})\index{Trajectory@\texttt{Trajectory}!for rcwa mapping, starting point, set of end points, modulus}
\label{Trajectory:for rcwa mapping, starting point, set of end points, modulus}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 The first \mbox{\texttt{\slshape length}} iterates in the trajectory of the rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}} starting at{\nobreakspace}\mbox{\texttt{\slshape n}}, respectively the initial part of the trajectory of the rcwa
mapping{\nobreakspace}\mbox{\texttt{\slshape f}} starting at{\nobreakspace}\mbox{\texttt{\slshape n}} which ends at the first occurence of an iterate in the set \mbox{\texttt{\slshape terminal}}. If the argument \mbox{\texttt{\slshape m}} is given, the iterates are reduced (mod{\nobreakspace}\mbox{\texttt{\slshape m}}). 



 To save memory when computing long trajectories containing huge iterates, the
reduction (mod{\nobreakspace}\mbox{\texttt{\slshape m}}) is done each time before storing an iterate. In place of the ring
element{\nobreakspace}\mbox{\texttt{\slshape n}}, the methods also accept a finite set of ring elements or a union of residue
classes. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> T := RcwaMapping([[1,0,2],[3,1,2]]);; # The Collatz mapping.
  gap> Trajectory(T,27,16); Trajectory(T,27,25,5);
  [ 27, 41, 62, 31, 47, 71, 107, 161, 242, 121, 182, 91, 137, 206, 103, 155 ]
  [ 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 3, 0, 3, 0, 0, 3, 0, 3, 0, 0, 3 ]
  gap> Trajectory(T,15,[1]); Trajectory(T,15,[1],2);
  [ 15, 23, 35, 53, 80, 40, 20, 10, 5, 8, 4, 2, 1 ]
  [ 1, 1, 1, 1, 0, 0, 0, 0, 1, 0, 0, 0, 1 ]
  gap> Trajectory(T,ResidueClass(Integers,3,0),Integers);
  [ 0(3), 0(3) U 5(9), 0(3) U 5(9) U 7(9) U 8(27), 
    <union of 20 residue classes (mod 27)>, <union of 73 residue classes (mod 
      81)>, Z \ 10(81) U 37(81), Integers ]
  
\end{Verbatim}
 }

 
\subsection{\textcolor{Chapter }{ Trajectory (methods for rcwa mappings -- ``accumulated coefficients'') }}\logpage{[ 2, 8, 2 ]}
\hyperdef{L}{X7FFD09837E934853}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Trajectory({\slshape f, n, length, whichcoeffs})\index{Trajectory@\texttt{Trajectory}!for rcwa mapping, starting point, length, coeff.-spec.}
\label{Trajectory:for rcwa mapping, starting point, length, coeff.-spec.}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Trajectory({\slshape f, n, terminal, whichcoeffs})\index{Trajectory@\texttt{Trajectory}!for rcwa mapping, starting point, set of end points, coeff.-spec.}
\label{Trajectory:for rcwa mapping, starting point, set of end points, coeff.-spec.}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 Either the list \texttt{c} of triples of coprime coefficients such that for any{\nobreakspace}\texttt{k} it holds that \texttt{\mbox{\texttt{\slshape n}}\texttt{\symbol{94}}(\mbox{\texttt{\slshape f}}\texttt{\symbol{94}}(k-1)) = (c[k][1]*\mbox{\texttt{\slshape n}} + c[k][2])/c[k][3]} or the last entry of that list, depending on whether \mbox{\texttt{\slshape whichcoeffs}} is \texttt{"AllCoeffs"} or \texttt{"LastCoeffs"}. 



 The meanings of the arguments \mbox{\texttt{\slshape length}} and \mbox{\texttt{\slshape terminal}} are the same as in the methods for the operation \texttt{Trajectory} described above. In general, computing only the last coefficient triple (\mbox{\texttt{\slshape whichcoeffs}} = \texttt{"LastCoeffs"}) needs considerably less memory than computing the entire list. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Trajectory(T,27,[1],"LastCoeffs");
  [ 36472996377170786403, 195820718533800070543, 1180591620717411303424 ]
  gap> (last[1]*27+last[2])/last[3];
  1
  
\end{Verbatim}
 }

 When dealing with problems like the $3n+1$-Conjecture or when determining the degree of transitivity of the natural
action of an rcwa group on its underlying ring, an important task is to
determine the residue classes whose elements get larger or smaller when
applying a given rcwa mapping: 
\subsection{\textcolor{Chapter }{ IncreasingOn \& DecreasingOn (for an rcwa mapping) }}\logpage{[ 2, 8, 3 ]}
\hyperdef{L}{X871989927C55AAE4}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IncreasingOn({\slshape f})\index{IncreasingOn@\texttt{IncreasingOn}!for an rcwa mapping}
\label{IncreasingOn:for an rcwa mapping}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DecreasingOn({\slshape f})\index{DecreasingOn@\texttt{DecreasingOn}!for an rcwa mapping}
\label{DecreasingOn:for an rcwa mapping}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 The union of all residue classes $r(m)$ such that $|R/a_{r(m)}R| > |R/c_{r(m)}R|$ or $|R/a_{r(m)}R| < |R/c_{r(m)}R|$, respectively, where $R$ denotes the source, $m$ denotes the modulus and $a_{r(m)}$, $b_{r(m)}$ and $c_{r(m)}$ denote the coefficients of{\nobreakspace}\mbox{\texttt{\slshape f}} as introduced in Section{\nobreakspace}\ref{sec:basicdefinitions}. 



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List([1..3],k->IncreasingOn(T^k));
  [ 1(2), 3(4), 3(4) U 1(8) U 6(8) ]
  gap> List([1..3],k->DecreasingOn(T^k));
  [ 0(2), Z \ 3(4), 0(4) U 2(8) U 5(8) ]
  gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; # Collatz' permutation.
  gap> List([-2..2],k->IncreasingOn(a^k));
  [ Z \ 1(8) U 7(8), 0(2), [  ], Z \ 0(3), 1(9) U 4(9) U 5(9) U 8(9) ]
  
\end{Verbatim}
 }

 We assign certain directed graphs to rcwa mappings, which encode the order in
which trajectories may traverse the residue classes modulo some modulus: 

\subsection{\textcolor{Chapter }{TransitionGraph (for an rcwa mapping and a modulus)}}
\logpage{[ 2, 8, 4 ]}\nobreak
\hyperdef{L}{X780841E07CAE7543}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TransitionGraph({\slshape f, m})\index{TransitionGraph@\texttt{TransitionGraph}!for an rcwa mapping and a modulus}
\label{TransitionGraph:for an rcwa mapping and a modulus}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The transition graph of the rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}} for modulus{\nobreakspace}\mbox{\texttt{\slshape m}}. 



 \index{rcwa mapping@rcwa mapping!transition graph} \noindent The \emph{transition graph} $\Gamma_{f,m}$ of{\nobreakspace}$f$ for modulus{\nobreakspace}$m$ is defined as follows: 
\begin{enumerate}
\item  The vertices are the residue classes (mod{\nobreakspace}$m$). 
\item  There is an edge from $r_1(m)$ to $r_2(m)$ if and only if there is some $n \in r_1(m)$ such that $n^f \in r_2(m)$. 
\end{enumerate}
 The assignment of the residue classes (mod{\nobreakspace}$m$) to the vertices of the graph corresponds to the ordering of the residues in \texttt{AllResidues(Source(\mbox{\texttt{\slshape f}}),\mbox{\texttt{\slshape m}})}. The result is returned in the format used by the package \textsf{GRAPE}{\nobreakspace}\cite{GRAPE}. }

 There are a couple of operations and attributes which are based on these
graphs: 

\subsection{\textcolor{Chapter }{OrbitsModulo (for an rcwa mapping and a modulus)}}
\logpage{[ 2, 8, 5 ]}\nobreak
\hyperdef{L}{X7F03CC4179424AA9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{OrbitsModulo({\slshape f, m})\index{OrbitsModulo@\texttt{OrbitsModulo}!for an rcwa mapping and a modulus}
\label{OrbitsModulo:for an rcwa mapping and a modulus}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The partition of \texttt{AllResidues(Source(\mbox{\texttt{\slshape f}}),\mbox{\texttt{\slshape m}})} corresponding to the weakly connected components of the transition graph of
the rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}} for modulus{\nobreakspace}\mbox{\texttt{\slshape m}}. 



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> OrbitsModulo(ClassTransposition(0,2,1,4),8);
  [ [ 0, 1, 4 ], [ 2, 5, 6 ], [ 3 ], [ 7 ] ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{FactorizationOnConnectedComponents (for an rcwa mapping and a modulus)}}
\logpage{[ 2, 8, 6 ]}\nobreak
\hyperdef{L}{X7F11051E866C197F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FactorizationOnConnectedComponents({\slshape f, m})\index{FactorizationOnConnectedComponents@\texttt{FactorizationOnConnectedComponents}!for an rcwa mapping and a modulus}
\label{FactorizationOnConnectedComponents:for an rcwa mapping and a modulus}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The set of restrictions of the rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}} to the weakly connected components of its transition graph $\Gamma_{f,m}$. 



 The product of the returned mappings is{\nobreakspace}\mbox{\texttt{\slshape f}}. They have pairwise disjoint supports, hence any two of them commute. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> sigma :=   ClassTransposition(1,4,2,4)  * ClassTransposition(1,4,3,4)
  >             * ClassTransposition(3,9,6,18) * ClassTransposition(1,6,3,9);;
  gap> List(FactorizationOnConnectedComponents(sigma,36),Support);
  [ 33(36) U 34(36) U 35(36), 9(36) U 10(36) U 11(36), 
    <union of 23 residue classes (mod 36)> \ [ -6, 3 ] ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{TransitionMatrix (for an rcwa mapping and a modulus)}}
\logpage{[ 2, 8, 7 ]}\nobreak
\hyperdef{L}{X7B6833D67D916EF9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TransitionMatrix({\slshape f, m})\index{TransitionMatrix@\texttt{TransitionMatrix}!for an rcwa mapping and a modulus}
\label{TransitionMatrix:for an rcwa mapping and a modulus}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The transition matrix of the rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}} for modulus{\nobreakspace}\mbox{\texttt{\slshape m}}. 



 Let $M$ be this matrix. Then for any two residue classes $r_1(m), r_2(m) \in R/mR$, the entry $M_{r_1(m),r_2(m)}$ is defined by  
\[ M_{r_1(m),r_2(m)} \ := \ \displaystyle{\frac{|R/mR|}{|R/\hat{m}R|}} \cdot
\left|\left\{r(\hat{m}) \in R/\hat{m}R | \ r \in r_1(m) \wedge r^f \in
r_2(m)\right\}\right|, \]
    where $\hat{m}$ is the product of \mbox{\texttt{\slshape m}} and the square of the modulus of{\nobreakspace}\mbox{\texttt{\slshape f}}. The assignment of the residue classes (mod{\nobreakspace}\mbox{\texttt{\slshape m}}) to the rows and columns of the matrix corresponds to the ordering of the
residues in \texttt{AllResidues(Source(\mbox{\texttt{\slshape f}}),\mbox{\texttt{\slshape m}})}. 

 The transition matrix is a weighted adjacency matrix of the corresponding
transition graph \texttt{TransitionGraph(\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape m}})}. The sums of the rows of a transition matrix are always equal
to{\nobreakspace}1. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> T := RcwaMapping([[1,0,2],[3,1,2]]);; # The Collatz mapping.
  gap> Display(TransitionMatrix(T^3,3));
  [ [  1/8,  1/4,  5/8 ],
    [    0,  1/4,  3/4 ],
    [    0,  3/8,  5/8 ] ]
  
\end{Verbatim}
 }

 
\subsection{\textcolor{Chapter }{ Sources \& Sinks (of an rcwa mapping) }}\logpage{[ 2, 8, 8 ]}
\hyperdef{L}{X81DBA2D58526BE7E}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Sources({\slshape f})\index{Sources@\texttt{Sources}!of an rcwa mapping}
\label{Sources:of an rcwa mapping}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Sinks({\slshape f})\index{Sinks@\texttt{Sinks}!of an rcwa mapping}
\label{Sinks:of an rcwa mapping}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 A list of unions of residue classes modulo the modulus{\nobreakspace}$m$ of the rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}}, as described below. 



 The returned list contains an entry for any strongly connected component of
the transition graph of{\nobreakspace}\mbox{\texttt{\slshape f}} for modulus{\nobreakspace}\texttt{Mod(\mbox{\texttt{\slshape f}})} which has only outgoing edges (``source'') or which has only ingoing edges (``sink''), respectively. The list entry corresponding to such a component is the union
of the vertices belonging to it. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> g := ClassTransposition(0,2,1,2)*ClassTransposition(0,2,1,4);;
  gap> Sources(g); Sinks(g);
  [ 0(4) ]
  [ 1(4) ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Loops (of an rcwa mapping)}}
\logpage{[ 2, 8, 9 ]}\nobreak
\hyperdef{L}{X80221A4D81AF7453}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Loops({\slshape f})\index{Loops@\texttt{Loops}!of an rcwa mapping}
\label{Loops:of an rcwa mapping}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 If \mbox{\texttt{\slshape f}} is bijective, the list of non-isolated vertices of the transition graph
of{\nobreakspace}\mbox{\texttt{\slshape f}} for modulus \texttt{Mod(\mbox{\texttt{\slshape f}})} which carry a loop. In general, the list of vertices of that transition graph
which carry a loop, but which \mbox{\texttt{\slshape f}} does not fix setwise. 



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Loops(ClassTransposition(0,2,1,2)*ClassTransposition(0,2,1,4));
  [ 0(4), 1(4) ]
  
\end{Verbatim}
 }

 There is a nice invariant of trajectories of the Collatz mapping: 

\subsection{\textcolor{Chapter }{GluckTaylorInvariant (of a trajectory)}}
\logpage{[ 2, 8, 10 ]}\nobreak
\hyperdef{L}{X8773152E81A30123}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GluckTaylorInvariant({\slshape a})\index{GluckTaylorInvariant@\texttt{GluckTaylorInvariant}!of a trajectory}
\label{GluckTaylorInvariant:of a trajectory}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The invariant introduced in{\nobreakspace}\cite{GluckTaylor02}. This is $(\sum_{i=1}^l a_i \cdot a_{i \mod l + 1})/(\sum_{i=1}^l a_i^2)$, where $l$ denotes the length of{\nobreakspace}\mbox{\texttt{\slshape a}}. 



 The argument \mbox{\texttt{\slshape a}} must be a list of integers. In{\nobreakspace}\cite{GluckTaylor02} it is shown that if \mbox{\texttt{\slshape a}} is a trajectory of the `original' Collatz mapping $n$ $\mapsto$ ($n/2$ if $n$ even, $3n+1$ if $n$ odd) starting at an odd integer $\geq 3$ and ending at{\nobreakspace}1, then the invariant lies in the interval $]9/13,5/7[$. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> C := RcwaMapping([[1,0,2],[3,1,1]]);;
  gap> List([3,5..49],n->Float(GluckTaylorInvariant(Trajectory(C,n,[1]))));
  [ 0.701053, 0.696721, 0.708528, 0.707684, 0.706635, 0.695636, 0.711769,
    0.699714, 0.707409, 0.693833, 0.710432, 0.706294, 0.714242, 0.699935,
    0.714242, 0.705383, 0.706591, 0.698198, 0.712222, 0.714242, 0.709048,
    0.69612, 0.714241, 0.701076 ]
  
\end{Verbatim}
 }

 Quite often one can make certain ``educated guesses'' on the overall behaviour of the trajectories of a given rcwa mapping. For
example it is reasonably straightforward to make the conjecture that all
trajectories of the Collatz mapping eventually enter the finite set $\{-136, -91, -82, -68, -61, -55, -41, -37, -34, -25, -17, -10, -7, -5, -1, 0,
1, 2 \}$, or that ``on average'' the next number in a trajectory of the Collatz mapping is smaller than the
preceding one by a factor of $\sqrt{3}/2$. However it is clear that such guesses can be wrong, and that they therefore
cannot be used to prove anything. Nevertheless they can sometimes be useful: 

\subsection{\textcolor{Chapter }{LikelyContractionCentre (of an rcwa mapping)}}
\logpage{[ 2, 8, 11 ]}\nobreak
\hyperdef{L}{X84F6A29280E2F925}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LikelyContractionCentre({\slshape f, maxn, bound})\index{LikelyContractionCentre@\texttt{LikelyContractionCentre}!of an rcwa mapping}
\label{LikelyContractionCentre:of an rcwa mapping}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 A list of ring elements (see below). 



 This operation tries to compute the \emph{contraction centre} of the rcwa mapping \mbox{\texttt{\slshape f}}. Assuming its existence this is the unique finite subset $S_0$ of the source of{\nobreakspace}\mbox{\texttt{\slshape f}} on which \mbox{\texttt{\slshape f}} induces a permutation and which intersects nontrivially with any trajectory
of{\nobreakspace}\mbox{\texttt{\slshape f}}. The mapping{\nobreakspace}\mbox{\texttt{\slshape f}} is assumed to be \emph{contracting}, i.e. to have such a contraction centre. As in general contraction centres
are likely not computable, the methods for this operation are probabilistic
and may return wrong results. The argument \mbox{\texttt{\slshape maxn}} is a bound on the starting value and \mbox{\texttt{\slshape bound}} is a bound on the elements of the trajectories to be searched. If the limit \mbox{\texttt{\slshape bound}} is exceeded, an Info message on Info level{\nobreakspace}3 of \texttt{InfoRCWA} is given. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> T := RcwaMapping([[1,0,2],[3,1,2]]);; # The Collatz mapping.
  gap> S0 := LikelyContractionCentre(T,100,1000);
  #I  Warning: `LikelyContractionCentre' is highly probabilistic.
  The returned result can only be regarded as a rough guess.
  See ?LikelyContractionCentre for information on how to improve this guess.
  [ -136, -91, -82, -68, -61, -55, -41, -37, -34, -25, -17, -10, -7, -5, -1, 0, 
    1, 2 ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{GuessedDivergence (of an rcwa mapping)}}
\logpage{[ 2, 8, 12 ]}\nobreak
\hyperdef{L}{X81E0D8E3817B3D16}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GuessedDivergence({\slshape f})\index{GuessedDivergence@\texttt{GuessedDivergence}!of an rcwa mapping}
\label{GuessedDivergence:of an rcwa mapping}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 A floating point value which is intended to be a rough guess on how fast the
trajectories of the rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}} diverge (return value greater than{\nobreakspace}1) or converge (return value
smaller than{\nobreakspace}1). 



 Nothing particular is guaranteed. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> GuessedDivergence(T);                                       
  #I  Warning: GuessedDivergence: no particular return value is guaranteed.
  0.866025
  
\end{Verbatim}
 }

 }

 \pagebreak[4]  
\section{\textcolor{Chapter }{The categories and families of rcwa mappings}}\label{sec:CategoriesOfRcwaMappings}
\logpage{[ 2, 9, 0 ]}
\hyperdef{L}{X83FA71DD842377F0}{}
{
  

\subsection{\textcolor{Chapter }{IsRcwaMapping}}
\logpage{[ 2, 9, 1 ]}\nobreak
\hyperdef{L}{X7927C13782729CE9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaMapping({\slshape f})\index{IsRcwaMapping@\texttt{IsRcwaMapping}}
\label{IsRcwaMapping}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaMappingOfZ({\slshape f})\index{IsRcwaMappingOfZ@\texttt{IsRcwaMappingOfZ}}
\label{IsRcwaMappingOfZ}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaMappingOfZ{\textunderscore}pi({\slshape f})\index{IsRcwaMappingOfZpi@\texttt{IsRcwaMappingOfZ{\textunderscore}pi}}
\label{IsRcwaMappingOfZpi}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaMappingOfGFqx({\slshape f})\index{IsRcwaMappingOfGFqx@\texttt{IsRcwaMappingOfGFqx}}
\label{IsRcwaMappingOfGFqx}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} if \mbox{\texttt{\slshape f}} is an rcwa mapping, an rcwa mapping of the ring of integers, an rcwa mapping
of a semilocalization of the ring of integers or an rcwa mapping of a
polynomial ring in one variable over a finite field, respectively, and \texttt{false} otherwise. 



 Often the same methods can be used for rcwa mappings of the ring of integers
and of its semilocalizations. For this reason there is a category \texttt{IsRcwaMappingOfZOrZ{\textunderscore}pi} which is the union of \texttt{IsRcwaMappingOfZ} and \texttt{IsRcwaMappingOfZ{\textunderscore}pi}. \index{IsRcwaMappingOfZOrZ_pi@\texttt{IsRcwaMappingOfZOrZ{\textunderscore}pi}} The internal representation of rcwa mappings is called \texttt{IsRcwaMappingStandardRep}. \index{IsRcwaMappingStandardRep@\texttt{IsRcwaMappingStandardRep}} There are methods available for \texttt{ExtRepOfObj} and \texttt{ObjByExtRep}. \index{ExtRepOfObj@\texttt{ExtRepOfObj}} \index{ObjByExtRep@\texttt{ObjByExtRep}} }

 

\subsection{\textcolor{Chapter }{RcwaMappingsFamily (of a ring)}}
\logpage{[ 2, 9, 2 ]}\nobreak
\hyperdef{L}{X825DD365822934AF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMappingsFamily({\slshape R})\index{RcwaMappingsFamily@\texttt{RcwaMappingsFamily}!of a ring}
\label{RcwaMappingsFamily:of a ring}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The family of rcwa mappings of the ring{\nobreakspace}\mbox{\texttt{\slshape R}}. 

}

 }

  }

         
\chapter{\textcolor{Chapter }{Residue-Class-Wise Affine Groups}}\label{ch:RcwaGroups}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X874A3BB684F0639A}{}
{
  In this chapter, we describe how to construct residue-class-wise affine groups
and how to compute with them.  
\section{\textcolor{Chapter }{Constructing residue-class-wise affine groups}}\label{sec:ContructingRcwaGroups}
\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X81242A6586A604A3}{}
{
  \index{Group@\texttt{Group}} \index{GroupByGenerators@\texttt{GroupByGenerators}} \index{GroupWithGenerators@\texttt{GroupWithGenerators}} As any other groups in \textsf{GAP}, residue-class-wise affine groups can be constructed by \texttt{Group}, \texttt{GroupByGenerators} or \texttt{GroupWithGenerators}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  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
  
\end{Verbatim}
 \index{View@\texttt{View}!for an rcwa group} \index{Display@\texttt{Display}!for an rcwa group} \index{Print@\texttt{Print}!for an rcwa group} \index{String@\texttt{String}!for an rcwa group} There are methods for the operations \texttt{View}, \texttt{Display}, \texttt{Print} and \texttt{String} 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: 

\subsection{\textcolor{Chapter }{RCWA (the group of all rcwa permutations of a ring)}}
\logpage{[ 3, 1, 1 ]}\nobreak
\hyperdef{L}{X7C0DCF887D324CF9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RCWA({\slshape R})\index{RCWA@\texttt{RCWA}!the group of all rcwa permutations of a ring}
\label{RCWA:the group of all rcwa permutations of a ring}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The group RCWA(\mbox{\texttt{\slshape R}}) of all residue-class-wise affine permutations of the ring{\nobreakspace}\mbox{\texttt{\slshape R}}. 



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> RCWA_Z := RCWA(Integers);
  RCWA(Z)
  gap> IsSubgroup(RCWA_Z,G);
  true
  
\end{Verbatim}
 }

 Examples of rcwa permutations can be obtained via \texttt{Random(RCWA(\mbox{\texttt{\slshape R}}))}, see Section{\nobreakspace}\ref{sec:Random}. 

 \pagebreak[4] We denote the group which is generated by all class transpositions of the
ring{\nobreakspace}$R$ by CT($R$). This group is handled as a special case as well: 

\subsection{\textcolor{Chapter }{CT (the group generated by all class transpositions of a ring)}}
\logpage{[ 3, 1, 2 ]}\nobreak
\hyperdef{L}{X7BD42D8481300E25}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CT({\slshape R})\index{CT@\texttt{CT}!the group generated by all class transpositions of a ring}
\label{CT:the group generated by all class transpositions of a ring}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The group CT(\mbox{\texttt{\slshape R}}) which is generated by all class transpositions of the ring{\nobreakspace}$R$. 



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> CT_Z := CT(Integers);
  CT(Z)
  gap> IsSimple(CT_Z); # One of a longer list of stored attributes/properties.
  true
  gap> IsSubgroup(CT_Z,G);
  false
  
\end{Verbatim}
 }

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

\subsection{\textcolor{Chapter }{IsomorphismRcwaGroup (for a group, over a given ring)}}
\logpage{[ 3, 1, 3 ]}\nobreak
\hyperdef{L}{X7EB8A301790290C7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismRcwaGroup({\slshape G, R})\index{IsomorphismRcwaGroup@\texttt{IsomorphismRcwaGroup}!for a group, over a given ring}
\label{IsomorphismRcwaGroup:for a group, over a given ring}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismRcwaGroup({\slshape G})\index{IsomorphismRcwaGroup@\texttt{IsomorphismRcwaGroup}!for a group}
\label{IsomorphismRcwaGroup:for a group}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 A monomorphism from the group \mbox{\texttt{\slshape G}} to{\nobreakspace}RCWA(\mbox{\texttt{\slshape R}}) or to{\nobreakspace}RCWA($\Z$), respectively. 



 The best-supported case is \mbox{\texttt{\slshape R}} = $\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{\nobreakspace}II.B.
in{\nobreakspace}\cite{LaHarpe00}), and the method for free groups uses an adaptation of the construction given
on page{\nobreakspace}27 in{\nobreakspace}\cite{LaHarpe00} from PSL(2,$\C$) to RCWA($\Z$). 

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  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>
  
\end{Verbatim}
 }

 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: 

\subsection{\textcolor{Chapter }{DirectProduct (for rcwa groups over Z)}}
\logpage{[ 3, 1, 4 ]}\nobreak
\hyperdef{L}{X79CAE48981C11FE8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DirectProduct({\slshape G1, G2, ...})\index{DirectProduct@\texttt{DirectProduct}!for rcwa groups over Z}
\label{DirectProduct:for rcwa groups over Z}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 An rcwa group isomorphic to the direct product of the rcwa groups
over{\nobreakspace}$\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 \mbox{\texttt{\slshape G1}}, \mbox{\texttt{\slshape G2}}, \mbox{\texttt{\slshape G3}}{\nobreakspace}... via restrictions by $n \mapsto mn$, $n \mapsto mn+1$, $n \mapsto mn+2${\nobreakspace}... ($\rightarrow${\nobreakspace}\texttt{Restriction} (\ref{Restriction:of an rcwa group, by an injective rcwa mapping})), where $m$ denotes the number of groups given as arguments. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  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
  
\end{Verbatim}
 }

 
\subsection{\textcolor{Chapter }{ WreathProduct (for an rcwa group over Z, with a permutation group or ($\Z$,+)) }}\logpage{[ 3, 1, 5 ]}
\hyperdef{L}{X7AEFAB7E7F81444B}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WreathProduct({\slshape G, P})\index{WreathProduct@\texttt{WreathProduct}!for an rcwa group over Z and a permutation group}
\label{WreathProduct:for an rcwa group over Z and a permutation group}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WreathProduct({\slshape G, Z})\index{WreathProduct@\texttt{WreathProduct}!for an rcwa group over Z and the infinite cyclic group}
\label{WreathProduct:for an rcwa group over Z and the infinite cyclic group}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 An rcwa group isomorphic to the wreath product of the rcwa
group{\nobreakspace}\mbox{\texttt{\slshape G}} over{\nobreakspace}$\Z$ with the finite permutation group{\nobreakspace}\mbox{\texttt{\slshape P}} or with the infinite cyclic group{\nobreakspace}\mbox{\texttt{\slshape Z}}, respectively. 



 The first-mentioned method embeds the \texttt{DegreeAction(\mbox{\texttt{\slshape P}})}th direct power of{\nobreakspace}\mbox{\texttt{\slshape G}} using the method for \texttt{DirectProduct}, and lets the permutation group{\nobreakspace}\mbox{\texttt{\slshape P}} act naturally on the set of residue classes modulo \texttt{DegreeAction(\mbox{\texttt{\slshape P}})}. The second-mentioned method restricts ($\rightarrow${\nobreakspace}\texttt{Restriction} (\ref{Restriction:of an rcwa group, by an injective rcwa mapping})) the group{\nobreakspace}\mbox{\texttt{\slshape G}} to the residue class{\nobreakspace}3(4), and maps the generator of the
infinite cyclic group{\nobreakspace}\mbox{\texttt{\slshape Z}} to \texttt{ClassTransposition(0,2,1,2) * ClassTransposition(0,2,1,4)}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  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> ]
  
\end{Verbatim}
 }

 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 \emph{restriction monomorphisms}. The following operation computes images of rcwa mappings and -groups under
them: 
\subsection{\textcolor{Chapter }{ Restriction (of an rcwa mapping or -group, by an injective rcwa mapping) }}\logpage{[ 3, 1, 6 ]}
\hyperdef{L}{X7FAC058484C608D3}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Restriction({\slshape g, f})\index{Restriction@\texttt{Restriction}!of an rcwa mapping, by an injective rcwa mapping}
\label{Restriction:of an rcwa mapping, by an injective rcwa mapping}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Restriction({\slshape G, f})\index{Restriction@\texttt{Restriction}!of an rcwa group, by an injective rcwa mapping}
\label{Restriction:of an rcwa group, by an injective rcwa mapping}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The restriction of the rcwa mapping \mbox{\texttt{\slshape g}} (respectively the rcwa group \mbox{\texttt{\slshape G}}) by the injective rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}}. 



 By definition, the \emph{restriction} $g_f$ of an rcwa mapping \mbox{\texttt{\slshape g}} by an injective rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}} is the unique rcwa mapping which satisfies the equation $f \cdot g_f = g \cdot f$ and which fixes the complement of the image of \mbox{\texttt{\slshape f}} pointwise. If \mbox{\texttt{\slshape f}} is bijective, the restriction of \mbox{\texttt{\slshape g}} by \mbox{\texttt{\slshape f}} is just the conjugate of \mbox{\texttt{\slshape g}} under{\nobreakspace}\mbox{\texttt{\slshape f}}. 

 The \emph{restriction} of an rcwa group{\nobreakspace}\mbox{\texttt{\slshape G}} by an injective rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}} is defined as the group whose elements are the restrictions of the elements
of{\nobreakspace}\mbox{\texttt{\slshape G}} by{\nobreakspace}\mbox{\texttt{\slshape f}}. The restriction of{\nobreakspace}\mbox{\texttt{\slshape G}} by{\nobreakspace}\mbox{\texttt{\slshape f}} acts on the image of{\nobreakspace}\mbox{\texttt{\slshape f}} and fixes its complement pointwise. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> F2tilde := Restriction(F2,RcwaMapping([[5,3,1]]));
  <wild rcwa group over Z with 2 generators>
  gap> Support(F2tilde);
  3(5)
  
\end{Verbatim}
 }

 
\subsection{\textcolor{Chapter }{ Induction (of an rcwa mapping or -group, by an injective rcwa mapping) }}\logpage{[ 3, 1, 7 ]}
\hyperdef{L}{X82171D7287CBED95}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Induction({\slshape g, f})\index{Induction@\texttt{Induction}!of an rcwa mapping, by an injective rcwa mapping}
\label{Induction:of an rcwa mapping, by an injective rcwa mapping}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Induction({\slshape G, f})\index{Induction@\texttt{Induction}!of an rcwa group, by an injective rcwa mapping}
\label{Induction:of an rcwa group, by an injective rcwa mapping}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The induction of the rcwa mapping \mbox{\texttt{\slshape g}} (respectively the rcwa group \mbox{\texttt{\slshape G}}) by the injective rcwa mapping{\nobreakspace}\mbox{\texttt{\slshape f}}. 



 \emph{Induction} is the right inverse of restriction, i.e. it is \texttt{Induction(Restriction(\mbox{\texttt{\slshape g}},\mbox{\texttt{\slshape f}}),\mbox{\texttt{\slshape f}}) = \mbox{\texttt{\slshape g}}} and \texttt{Induction(Restriction(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape f}}),\mbox{\texttt{\slshape f}}) = \mbox{\texttt{\slshape G}}}. The mapping{\nobreakspace}\mbox{\texttt{\slshape g}} respectively the group{\nobreakspace}\mbox{\texttt{\slshape G}} must not move points outside the image of{\nobreakspace}\mbox{\texttt{\slshape f}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Induction(F2tilde,RcwaMapping([[5,3,1]])) = F2;
  true
  
\end{Verbatim}
 }

 \index{rcwa group@rcwa group!modulus} \index{rcwa group@rcwa group!multiplier} \index{rcwa group@rcwa group!divisor} \index{rcwa group@rcwa group!prime set} \index{rcwa group@rcwa group!integral} \index{rcwa group@rcwa group!class-wise order-preserving} \index{Modulus@\texttt{Modulus}!of an rcwa group} \index{Mod@\texttt{Mod}!for an rcwa group} \index{ModulusOfRcwaMonoid@\texttt{ModulusOfRcwaMonoid}!for an rcwa group} \index{Multiplier@\texttt{Multiplier}!of an rcwa group} \index{Mult@\texttt{Mult}!for an rcwa group} \index{Divisor@\texttt{Divisor}!of an rcwa group} \index{Div@\texttt{Div}!for an rcwa group} \index{PrimeSet@\texttt{PrimeSet}!of an rcwa group} \index{IsIntegral@\texttt{IsIntegral}!for an rcwa group} \index{IsClassWiseOrderPreserving@\texttt{IsClassWiseOrderPreserving}!for an rcwa group} \index{IsSignPreserving@\texttt{IsSignPreserving}!for an rcwa group} Basic attributes of an rcwa group which are derived from the coefficients of
its elements are \texttt{Modulus}, \texttt{Multiplier}, \texttt{Divisor} and \texttt{PrimeSet}. The \emph{modulus} 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 \emph{multiplier} respectively \emph{divisor} 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 \emph{prime set} of an rcwa group is the union of the prime sets of its elements. There are
shorthands \texttt{Mod}, \texttt{Mult} and \texttt{Div} defined for \texttt{Modulus}, \texttt{Multiplier} and \texttt{Divisor}, respectively. An rcwa group is called \emph{integral} respectively \emph{class-wise order-preserving} if all of its elements are so. There are corresponding methods available for \texttt{IsIntegral} and \texttt{IsClassWiseOrderPreserving}. There is a property \texttt{IsSignPreserving}, which indicates whether a given rcwa group over{\nobreakspace}$\Z$ acts on the set of nonnegative integers. The latter holds for any subgroup of
CT($\Z$). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(ClassTransposition(0,2,1,2),ClassTransposition(1,3,2,6),  
  >               ClassReflection(2,4));
  <rcwa group over Z with 3 generators>
  gap> List([Modulus,Multiplier,Divisor,PrimeSet,IsIntegral,
  >          IsClassWiseOrderPreserving,IsSignPreserving],f->f(G));
  [ 24, 2, 2, [ 2, 3 ], false, false, false ]
  
\end{Verbatim}
 }

  
\section{\textcolor{Chapter }{ Basic routines for investigating residue-class-wise affine groups }}\label{sec:InvestigatingRcwaGroups}
\logpage{[ 3, 2, 0 ]}
\hyperdef{L}{X80C042BE82EE0F9A}{}
{
  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 \texttt{StructureDescription}: 

\subsection{\textcolor{Chapter }{StructureDescription (for an rcwa group)}}
\logpage{[ 3, 2, 1 ]}\nobreak
\hyperdef{L}{X864A7E3E87F366A8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StructureDescription({\slshape G})\index{StructureDescription@\texttt{StructureDescription}!for an rcwa group}
\label{StructureDescription:for an rcwa group}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 A string which describes the structure of the rcwa group{\nobreakspace}\mbox{\texttt{\slshape G}} to some extent. 



 The attribute \texttt{StructureDescription} for finite groups is documented in the \textsf{GAP} 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{\nobreakspace}\texttt{wr}, and free products are denoted by{\nobreakspace}\texttt{*}. The infinite cyclic group $(\Z,+)$ is denoted by{\nobreakspace}\texttt{Z}, the infinite dihedral group is denoted by{\nobreakspace}\texttt{D0} and free groups of rank $2,3,4,\dots$ are denoted by{\nobreakspace}\texttt{F2}, \texttt{F3}, \texttt{F4},{\nobreakspace}$\dots$. While for finite groups the symbol{\nobreakspace}\texttt{.} 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 \texttt{{\textless}unknown{\textgreater}}. In general, the structure of a section denoted by \texttt{{\textless}unknown{\textgreater}} 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. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  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"
  
\end{Verbatim}
 }

 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. 

 \index{Size@\texttt{Size}!for an rcwa group} The order of an rcwa group can be computed by the operation \texttt{Size}. An rcwa group is finite if and only if it is tame and its action on a
suitably chosen respected partition (see{\nobreakspace}\texttt{RespectedPartition} (\ref{RespectedPartition:of a tame rcwa group})) is faithful. Hence the problem of computing the order of an rcwa group
reduces to the problem of deciding whether it is tame, the problem of deciding
whether it acts faithfully on a respected partition and the problem of
computing the order of the finite permutation group induced on the respected
partition. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(ClassTransposition(0,2,1,2),ClassTransposition(1,3,2,3),
  >               ClassReflection(0,5));
  <rcwa group over Z with 3 generators>
  gap> Size(G);
  46080
  
\end{Verbatim}
 \index{IsomorphismPermGroup@\texttt{IsomorphismPermGroup}!for a finite rcwa group} For a finite rcwa group, an isomorphism to a permutation group can be computed
by \texttt{IsomorphismPermGroup}: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(ClassTransposition(0,2,1,2),ClassTransposition(0,3,1,3));;
  gap> IsomorphismPermGroup(G);
  [ ClassTransposition(0,2,1,2), ClassTransposition(0,3,1,3) ] -> 
  [ (1,2)(3,4)(5,6), (1,2)(4,5) ]
  
\end{Verbatim}
 \index{rcwa group@rcwa group!membership test} 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{\nobreakspace}2 of \texttt{InfoRCWA} the membership test provides information on reasons why the given rcwa
permutation is an element of the given rcwa group or{\nobreakspace}not. 

 The direct product of two free groups of rank{\nobreakspace}2 can faithfully
be represented as an rcwa group. According to{\nobreakspace}\cite{Mihailova58} this implies that in general the membership problem for rcwa groups is
algorithmically undecidable. \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  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
  
\end{Verbatim}
 \index{rcwa group@rcwa group!conjugacy problem} \index{IsConjugate@\texttt{IsConjugate}!for elements of RCWA(R)} \index{IsConjugate@\texttt{IsConjugate}!for elements of CT(R)} The conjugacy problem for rcwa groups is difficult, and \textsf{RCWA} provides only methods to solve it in some reasonably easy cases. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> IsConjugate(RCWA(Integers),ClassTransposition(0,2,1,4),ClassShift(0,1));
  false
  gap> IsConjugate(CT(Integers),ClassTransposition(0,2,1,6),
  >                             ClassTransposition(1,4,0,8));
  true
  gap> g := RepresentativeAction(CT(Integers),ClassTransposition(0,2,1,6),
  >                                           ClassTransposition(1,4,0,8));
  <bijective rcwa mapping of Z with modulus 48>
  gap> ClassTransposition(0,2,1,6)^g = ClassTransposition(1,4,0,8);
  true
  
\end{Verbatim}
 \index{NrConjugacyClassesOfRCWAZOfOrder@\texttt{NrConjugacyClassesOfRCWAZOfOrder}} The number of conjugacy classes of RCWA($\Z$) of elements of given order is known, cp.
Corollary{\nobreakspace}2.7.1{\nobreakspace}(b) in{\nobreakspace}\cite{Kohl05}. It can be determined by the function \texttt{NrConjugacyClassesOfRCWAZOfOrder}: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List([2,105],NrConjugacyClassesOfRCWAZOfOrder);
  [ infinity, 218 ]
  
\end{Verbatim}
 \index{IsTame@\texttt{IsTame}!for an rcwa group} There is a property \texttt{IsTame} which indicates whether an rcwa group is tame or not: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(ClassTransposition(0,2,1,4),ClassShift(1,3));;
  gap> H := Group(ClassTransposition(0,2,1,6),ClassShift(1,3));;
  gap> IsTame(G);
  true
  gap> IsTame(H);
  false
  
\end{Verbatim}
 \index{IsSolvable@\texttt{IsSolvable}!for an rcwa group} \index{IsPerfect@\texttt{IsPerfect}!for an rcwa group} \index{DerivedSubgroup@\texttt{DerivedSubgroup}!of an rcwa group} \index{Index@\texttt{Index}!for rcwa groups} \index{IsomorphismMatrixGroup@\texttt{IsomorphismMatrixGroup}!for an rcwa group} \index{Exponent@\texttt{Exponent}!of an rcwa group} For tame rcwa groups, there are methods for \texttt{IsSolvable} and \texttt{IsPerfect} 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 \texttt{IsomorphismMatrixGroup}. 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 \texttt{Exponent} available, which works basically for any rcwa group. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(ClassTransposition(0,2,1,4),ClassShift(1,2));;
  gap> IsPerfect(G);
  false
  gap> IsSolvable(G);
  true
  gap> D1 := DerivedSubgroup(G);; D2 := DerivedSubgroup(D1);;
  gap> IsAbelian(D2);
  true
  gap> Index(G,D1); Index(D1,D2);
  infinity
  9
  gap> StructureDescription(G); StructureDescription(D1);
  "(Z x Z x Z) . S3"
  "(Z x Z) . C3"
  gap> Q := D1/D2;
  Group([ (), (1,2,4)(3,5,7)(6,8,9), (1,3,6)(2,5,8)(4,7,9) ])
  gap> StructureDescription(Q); 
  "C3 x C3"
  gap> Exponent(G);
  infinity
  gap> phi := IsomorphismMatrixGroup(G);;
  gap> Display(Image(phi,ClassTransposition(0,2,1,4)));
  [ [     0,     0,   1/2,  -1/2,     0,     0 ], 
    [     0,     0,     0,     1,     0,     0 ], 
    [     2,     1,     0,     0,     0,     0 ], 
    [     0,     1,     0,     0,     0,     0 ], 
    [     0,     0,     0,     0,     1,     0 ], 
    [     0,     0,     0,     0,     0,     1 ] ]
  
\end{Verbatim}
 When investigating a group, a basic task is to find relations among the
generators: 

\subsection{\textcolor{Chapter }{EpimorphismFromFpGroup (for an rcwa group and a search radius)}}
\logpage{[ 3, 2, 2 ]}\nobreak
\hyperdef{L}{X83527DA37C5CB2C7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{EpimorphismFromFpGroup({\slshape G, r})\index{EpimorphismFromFpGroup@\texttt{EpimorphismFromFpGroup}!for an rcwa group and a search radius}
\label{EpimorphismFromFpGroup:for an rcwa group and a search radius}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 An epimorphism from a finitely presented group to the rcwa
group{\nobreakspace}\mbox{\texttt{\slshape G}}. 



 The argument \mbox{\texttt{\slshape r}} is the ``search radius'', i.e. the radius of the ball around{\nobreakspace}1 which is scanned for
relations. In general, the larger \mbox{\texttt{\slshape r}} is chosen the smaller the kernel of the returned epimorphism is. If the
group{\nobreakspace}\mbox{\texttt{\slshape G}} has finite presentations, the kernel will in principle get trivial provided
that \mbox{\texttt{\slshape r}} is chosen large enough. 

 Both the performance and the returned epimorphism depend on whether the
package \textsf{FR}{\nobreakspace}\cite{FR} is present or{\nobreakspace}not. \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> a := ClassTransposition(2,4,3,4 :Name:="a");;
  gap> b := ClassTransposition(4,6,8,12:Name:="b");;
  gap> c := ClassTransposition(3,4,4,6 :Name:="c");;
  gap> G := Group(a,b,c);
  <rcwa group over Z with 3 generators>
  gap> phi := EpimorphismFromFpGroup(G,6);
  [ a, b, c ] -> [ a, b, c ]
  gap> RelatorsOfFpGroup(Source(phi));
  [ a^2, b^2, c^2, c*b*c*b*c*b, c*b*c*a*c*b*c*a*c*b*c*a, 
    b*a*b*a*b*a*b*a*b*a*b*a ]
  
\end{Verbatim}
 }

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

\subsection{\textcolor{Chapter }{PreImagesRepresentative (for an epi. from a free group to an rcwa group)}}
\logpage{[ 3, 2, 3 ]}\nobreak
\hyperdef{L}{X8463E34286344F06}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PreImagesRepresentative({\slshape phi, g})\index{PreImagesRepresentative@\texttt{PreImagesRepresentative}!for an epi. from a free group to an rcwa group}
\label{PreImagesRepresentative:for an epi. from a free group to an rcwa group}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 A representative of the set of preimages of{\nobreakspace}\mbox{\texttt{\slshape g}} under the epimorphism{\nobreakspace}\mbox{\texttt{\slshape phi}} from a free group to an rcwa group. 



 The epimorphism \mbox{\texttt{\slshape phi}} 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 \texttt{RepresentativeActionPreImage}, see \texttt{RepresentativeAction} (\ref{RepresentativeAction:G, source, destination, action}). 

 \index{PreImagesRepresentatives@\texttt{PreImagesRepresentatives}!for an epi. from a free group to an rcwa group} Quite frequently, computing several preimages is not harder than computing
just one, i.e. often several preimages are found simultaneously. The operation \texttt{PreImagesRepresentatives} takes care of this. It takes the same arguments as \texttt{PreImagesRepresentative} 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{\nobreakspace}\mbox{\texttt{\slshape phi}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; SetName(a,"a");
  gap> b := ClassShift(0,1:Name:="b");;
  gap> G := Group(a,b);; # G = <<Collatz permutation>, n -> n + 1>
  gap> phi := EpimorphismFromFreeGroup(G);;
  gap> g := Comm(a^2*b^4,a*b^3); # a sample element to be factored
  <bijective rcwa mapping of Z with modulus 8>
  gap> PreImagesRepresentative(phi,g); # -> a factorization of g
  b^-4*a^-1*b^-1*a^-1*b^3*a*b^-1*a*b^3
  gap> g = b^-4*a^-1*b^-1*a^-1*b^3*a*b^-1*a*b^3; # check
  true
  gap> g := Comm(a*b,Comm(a,b^3));
  <bijective rcwa mapping of Z with modulus 8>
  gap> pre := PreImagesRepresentatives(phi,g);
  [ 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 ]
  gap> rel := CyclicallyReducedWord(pre[1]/pre[2]); # -> a nontrivial relation
  b^-1*a^-1*b^3*a*b^2*a^-1*b^-3*a*b^-1
  gap> rel^phi;
  IdentityMapping( Integers )
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{ The natural action of an rcwa group on the underlying ring }}\label{sec:ActionOnR}
\logpage{[ 3, 3, 0 ]}
\hyperdef{L}{X8151BE577FFDCE87}{}
{
  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 \textsf{RCWA}'s functionality related to this action. 

 \index{Support@\texttt{Support}!of an rcwa group} \index{MovedPoints@\texttt{MovedPoints}!of an rcwa group} The support, i.e. the set of moved points, of an rcwa group can be determined
by \texttt{Support} or \texttt{MovedPoints} (these are synonyms). There are methods to compute orbits under the action of
an rcwa group: 
\subsection{\textcolor{Chapter }{ Orbit (for an rcwa group and either a point or a set) }}\logpage{[ 3, 3, 1 ]}
\hyperdef{L}{X7C046BE97EE53692}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Orbit({\slshape G, point})\index{Orbit@\texttt{Orbit}!for an rcwa group and a point}
\label{Orbit:for an rcwa group and a point}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Orbit({\slshape G, set})\index{Orbit@\texttt{Orbit}!for an rcwa group and a set}
\label{Orbit:for an rcwa group and a set}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 The orbit of the point{\nobreakspace}\mbox{\texttt{\slshape point}} respectively the set{\nobreakspace}\mbox{\texttt{\slshape set}} under the natural action of the rcwa group{\nobreakspace}\mbox{\texttt{\slshape G}} on its underlying ring. 



 The second argument can either be an element or a subset of the underlying
ring of the rcwa group{\nobreakspace}\mbox{\texttt{\slshape G}}. 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. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(ClassShift(0,2),ClassTransposition(0,3,1,3));
  <rcwa group over Z with 2 generators>
  gap> Orbit(G,0);
  Z \ 5(6)
  gap> Orbit(G,5);
  [ 5 ]
  gap> Orbit(G,ResidueClass(0,2));
  [ 0(2), 1(6) U 2(6) U 3(6), 1(3) U 3(6), 0(3) U 1(6), 0(3) U 4(6), 
    1(3) U 0(6), 0(3) U 2(6), 0(6) U 1(6) U 2(6), 2(6) U 3(6) U 4(6), 
    1(3) U 2(6) ]
  gap> G := Group(ClassTransposition(0,2,1,2),ClassTransposition(0,2,1,4),
  >               ClassReflection(0,3));
  <rcwa group over Z with 3 generators>
  gap> orb1 := Orbit(G,2); orb2 := Orbit(G,999);
  <orbit of 2 under <wild rcwa group over Z with 3 generators>>
  <orbit of 999 under <wild rcwa group over Z with 3 generators>>
  gap> 1 in orb1;
  false
  gap> 1015808 in orb1;
  true
  gap> orb1 = orb2;
  true
  gap> First(orb1,n->ForAll([n,n+2,n+6,n+8,n+30,n+32,n+36,n+38],IsPrime));
  -19
  
\end{Verbatim}
 }

 \textsf{RCWA} permits drawing pictures of orbits of rcwa groups on{\nobreakspace}$\Z^2$, see Section{\nobreakspace}\ref{sec:DrawingPictures}. \index{IsTransitive@\texttt{IsTransitive}!for an rcwa group, on its underlying ring} Testing for transitivity on the underlying ring is often feasible: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(ClassTransposition(1,2,0,4),ClassShift(0,2));;
  gap> IsTransitive(G,Integers);
  true
  
\end{Verbatim}
 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: 
\subsection{\textcolor{Chapter }{ ShortOrbits (for rcwa groups) \& ShortCycles (for rcwa permutations) }}\logpage{[ 3, 3, 2 ]}
\hyperdef{L}{X7CE0BA7F79CB3F5C}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ShortOrbits({\slshape G, S, maxlng})\index{ShortOrbits@\texttt{ShortOrbits}!for rcwa group, set of points and bound on length}
\label{ShortOrbits:for rcwa group, set of points and bound on length}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ShortCycles({\slshape g, S, maxlng})\index{ShortCycles@\texttt{ShortCycles}!for rcwa permutation, set of points and bound on length}
\label{ShortCycles:for rcwa permutation, set of points and bound on length}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ShortCycles({\slshape g, maxlng})\index{ShortCycles@\texttt{ShortCycles}!for rcwa permutation and bound on length}
\label{ShortCycles:for rcwa permutation and bound on length}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 In the first form a list of all finite orbits of the rcwa group{\nobreakspace}\mbox{\texttt{\slshape G}} of length at most \mbox{\texttt{\slshape maxlng}} which intersect nontrivially with the set{\nobreakspace}\mbox{\texttt{\slshape S}}. 

 In the second form a list of all cycles of the rcwa permutation \mbox{\texttt{\slshape g}} of length at most{\nobreakspace}\mbox{\texttt{\slshape maxlng}} which intersect nontrivially with the set{\nobreakspace}\mbox{\texttt{\slshape S}}. 

 In the third form a list of all cycles of the rcwa permutation \mbox{\texttt{\slshape g}} of length at most \mbox{\texttt{\slshape maxlng}} which do not correspond to cycles consisting of residue classes. 



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(ClassTransposition(1,4,2,4)*ClassTransposition(1,4,3,4),
  >               ClassTransposition(3,9,6,18)*ClassTransposition(1,6,3,9));;
  gap> List(ShortOrbits(G,[-15..15],100),orb->StructureDescription(Action(G,orb)));
  [ "A15", "A4", "1", "1", "C3", "1", "((C2 x C2 x C2) : C7) : C3", "1", "1", 
    "C3", "A19" ]
  gap> ShortCycles(mKnot(7),[1..100],20);
  [ [ 1 ], [ 2 ], [ 3 ], [ 4 ], [ 5 ], [ 6 ], [ 7, 8 ], [ 9, 10 ], [ 11, 12 ], 
    [ 13, 14, 16, 18, 20, 22, 19, 17, 15 ], [ 21, 24 ], [ 23, 26 ], 
    [ 25, 28, 32, 36, 31, 27, 30, 34, 38, 33, 29 ], [ 35, 40 ], 
    [ 37, 42, 48, 54, 47, 41, 46, 52, 45, 39, 44, 50, 43 ], 
    [ 77, 88, 100, 114, 130, 148, 127, 109, 124, 107, 122, 105, 120, 103, 89 ] ]
  
\end{Verbatim}
 }

 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: 
\subsection{\textcolor{Chapter }{ Ball (for group, element and radius or group, point, radius and action) }}\logpage{[ 3, 3, 3 ]}
\hyperdef{L}{X8735855587CC029F}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Ball({\slshape G, g, r})\index{Ball@\texttt{Ball}!for group, element and radius}
\label{Ball:for group, element and radius}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Ball({\slshape G, p, r, action})\index{Ball@\texttt{Ball}!for group, point, radius and action}
\label{Ball:for group, point, radius and action}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 The ball of radius{\nobreakspace}\mbox{\texttt{\slshape r}} around the element{\nobreakspace}\mbox{\texttt{\slshape g}} in the group{\nobreakspace}\mbox{\texttt{\slshape G}}, respectively the ball of radius{\nobreakspace}\mbox{\texttt{\slshape r}} around the point{\nobreakspace}\mbox{\texttt{\slshape p}} under the action{\nobreakspace}\mbox{\texttt{\slshape action}} of the group{\nobreakspace}\mbox{\texttt{\slshape G}}. 



 All balls are understood with respect to \texttt{GeneratorsOfGroup(\mbox{\texttt{\slshape G}})}. As membership tests can be expensive, the former method does not check
whether \mbox{\texttt{\slshape g}} is indeed an element of{\nobreakspace}\mbox{\texttt{\slshape G}}. The methods require that element- / point comparisons are cheap. They are
not only applicable to rcwa groups. If the option \mbox{\texttt{\slshape Spheres}} is set, the ball is splitted up and returned as a list of spheres. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> PSL2Z := Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(2),
  >                                                    CyclicGroup(3))));;
  gap> List([1..10],k->Length(Ball(PSL2Z,[0,1],k,OnTuples)));
  [ 4, 8, 14, 22, 34, 50, 74, 106, 154, 218 ]
  gap> Ball(Group((1,2),(2,3),(3,4)),(),2:Spheres);
  [ [ () ], [ (3,4), (2,3), (1,2) ],
    [ (2,3,4), (2,4,3), (1,2)(3,4), (1,2,3), (1,3,2) ] ]
  
\end{Verbatim}
 }

 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: 

\subsection{\textcolor{Chapter }{RepresentativeAction (G, source, destination, action)}}
\logpage{[ 3, 3, 4 ]}\nobreak
\hyperdef{L}{X87A3462C82FD376E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RepresentativeAction({\slshape G, source, destination, action})\index{RepresentativeAction@\texttt{RepresentativeAction}!G, source, destination, action}
\label{RepresentativeAction:G, source, destination, action}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 An element of \mbox{\texttt{\slshape G}} which maps \mbox{\texttt{\slshape source}} to{\nobreakspace}\mbox{\texttt{\slshape destination}} under the action given by{\nobreakspace}\mbox{\texttt{\slshape action}}. 



 If an element satisfying this condition does not exist, this method either
returns \texttt{fail} or runs into an infinite loop. The problem whether \mbox{\texttt{\slshape source}} and \mbox{\texttt{\slshape destination}} lie in the same orbit under the action \mbox{\texttt{\slshape action}} of{\nobreakspace}\mbox{\texttt{\slshape G}} is hard, and in its general form most likely computationally undecidable. 

 \index{RepresentativeActionPreImage@\texttt{RepresentativeActionPreImage}!G, source, destination, action, F} In cases where rather a word in the generators of{\nobreakspace}\mbox{\texttt{\slshape G}} than the actual group element is needed, one should use the operation \texttt{RepresentativeActionPreImage} instead. This operation takes five arguments. The first four are the same as
those of \texttt{RepresentativeAction}, and the fifth is a free group whose generators are to be used as letters of
the returned word. Note that \texttt{RepresentativeAction} calls \texttt{RepresentativeActionPreImage} and evaluates the returned word. The evaluation of the word can very well take
most of the time if \mbox{\texttt{\slshape G}} is wild and coefficient explosion occurs. 

 The algorithm is based on computing balls of increasing radius around \mbox{\texttt{\slshape source}} and \mbox{\texttt{\slshape destination}} until they intersect nontrivially. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; SetName(a,"a");
  gap> b := ClassShift(1,4:Name:="b");; G := Group(a,b);;
  gap> elm := RepresentativeAction(G,[7,4,9],[4,5,13],OnTuples);;
  gap> Display(elm);
  
  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,[6,-3,8],[-9,4,11],OnPoints);;
  gap> Display(elm);
  
  Bijective rcwa mapping of Z with modulus 12
  
                 n mod 12                |                 n^f
  ---------------------------------------+--------------------------------------
     0  3  6                             | 2n/3
     1                                   | (2n - 8)/3
     2  8 11                             | (4n + 1)/3
     4  7 10                             | (4n - 1)/3
     5                                   | (4n - 17)/3
     9                                   | (4n - 15)/3
  
  gap> [6,-3,8]^elm; List([6,-3,8],n->n^elm); # `OnPoints' permits reordering.
  [ -9, 4, 11 ]
  [ 4, -9, 11 ]
  gap> F := FreeGroup("a","b");; phi := EpimorphismByGenerators(F,G);;
  gap> w := RepresentativeActionPreImage(G,[10,-4,9,5],[4,5,13,-8],OnTuples,F);
  a*b^-1*a^-1*b^-1*a*b^-1*a*b*a*b^-2*a*b*a^-1*b
  gap> elm := w^phi;
  <bijective rcwa mapping of Z with modulus 324>
  gap> List([10,-4,9,5],n->n^elm);
  [ 4, 5, 13, -8 ]
  
\end{Verbatim}
 }

 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: 

\subsection{\textcolor{Chapter }{Projections (for an rcwa group and a modulus)}}
\logpage{[ 3, 3, 5 ]}\nobreak
\hyperdef{L}{X7F3CBDD2806ACECF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Projections({\slshape G, m})\index{Projections@\texttt{Projections}!for an rcwa group and a modulus}
\label{Projections:for an rcwa group and a modulus}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The projections of the rcwa group{\nobreakspace}\mbox{\texttt{\slshape G}} to the unions of residue classes (mod{\nobreakspace}\mbox{\texttt{\slshape m}}) which it fixes setwise. 



 The corresponding partition of a set of representatives for the residue
classes (mod{\nobreakspace}\mbox{\texttt{\slshape m}}) can be obtained by the operation \texttt{OrbitsModulo(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape m}})}. \index{OrbitsModulo@\texttt{OrbitsModulo}!for an rcwa group and a modulus} 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  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) ]
  
\end{Verbatim}
 }

 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: 

\subsection{\textcolor{Chapter }{RepresentativeAction (for RCWA(R) and 2 partitions of R into residue classes)}}
\logpage{[ 3, 3, 6 ]}\nobreak
\hyperdef{L}{X866843D08213067E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RepresentativeAction({\slshape RCWA(R), P1, P2})\index{RepresentativeAction@\texttt{RepresentativeAction}!for RCWA(R) and 2 partitions of R into residue classes}
\label{RepresentativeAction:for RCWA(R) and 2 partitions of R into residue classes}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 An element of RCWA($R$) which maps the partition{\nobreakspace}\mbox{\texttt{\slshape P1}} to{\nobreakspace}\mbox{\texttt{\slshape P2}}. 



 The arguments \mbox{\texttt{\slshape P1}} and \mbox{\texttt{\slshape P2}} 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 \texttt{IsTame}, which can be used to demand a tame result. If this option is set and there
is no tame rcwa permutation which maps \mbox{\texttt{\slshape P1}} to{\nobreakspace}\mbox{\texttt{\slshape P2}}, the method runs into an infinite loop. This happens if the condition in
Theorem{\nobreakspace}2.8.9 in{\nobreakspace}\cite{Kohl05} is not satisfied. If the option \texttt{IsTame} is not set and the partitions \mbox{\texttt{\slshape P1}} and \mbox{\texttt{\slshape P2}} both consist entirely of single residue classes, then the returned mapping is
affine on any residue class in{\nobreakspace}\mbox{\texttt{\slshape P1}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> P1 := AllResidueClassesModulo(3);
  [ 0(3), 1(3), 2(3) ]
  gap> P2 := List([[0,2],[1,4],[3,4]],ResidueClass);
  [ 0(2), 1(4), 3(4) ]
  gap> elm := RepresentativeAction(RCWA(Integers),P1,P2);
  <bijective rcwa mapping of Z with modulus 3>
  gap> P1^elm = P2;
  true
  gap> IsTame(elm);
  false
  gap> elm := RepresentativeAction(RCWA(Integers),P1,P2:IsTame);
  <tame bijective rcwa mapping of Z with modulus 24>
  gap> P1^elm = P2;
  true
  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) ]
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{ Special attributes of tame residue-class-wise affine groups }}\label{sec:MethodsForTameGroups}
\logpage{[ 3, 4, 0 ]}
\hyperdef{L}{X781CBEFA7F39B58D}{}
{
  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 \texttt{IsSolvable}, \texttt{IsPerfect} and \texttt{DerivedSubgroup} 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. 
\subsection{\textcolor{Chapter }{ RespectedPartition (of a tame rcwa group or -permutation) }}\logpage{[ 3, 4, 1 ]}
\hyperdef{L}{X86FAA72A7838CC13}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RespectedPartition({\slshape G})\index{RespectedPartition@\texttt{RespectedPartition}!of a tame rcwa group}
\label{RespectedPartition:of a tame rcwa group}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RespectedPartition({\slshape g})\index{RespectedPartition@\texttt{RespectedPartition}!of a tame rcwa permutation}
\label{RespectedPartition:of a tame rcwa permutation}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 A respected partition of the rcwa group \mbox{\texttt{\slshape G}} / of the rcwa permutation{\nobreakspace}\mbox{\texttt{\slshape g}}. 



 A tame element $g${\nobreakspace}$\in${\nobreakspace}RCWA($R$) permutes a partition of{\nobreakspace}$R$ into finitely many residue classes on all of which it is affine. Given a tame
group $G${\nobreakspace}$<${\nobreakspace}RCWA($R$), there is a common such partition for all elements of{\nobreakspace}$G$. We call the mentioned partitions \emph{respected partitions} of{\nobreakspace}$g$ or{\nobreakspace}$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{\nobreakspace}2.5.8
in{\nobreakspace}\cite{Kohl05}, depending on how one introduces the notion of tameness. 

 \index{RespectedPartitionShort@\texttt{RespectedPartitionShort}!for a tame rcwa group} \index{RespectedPartitionShort@\texttt{RespectedPartitionShort}!for a tame rcwa permutation} \index{RespectedPartitionLong@\texttt{RespectedPartitionLong}!for a tame rcwa group} \index{RespectedPartitionLong@\texttt{RespectedPartitionLong}!for a tame rcwa permutation} Related attributes are \texttt{RespectedPartitionShort} and \texttt{RespectedPartitionLong}. The first of these denotes a respected partition consisting of residue
classes $r(m)$ where $m$ divides the modulus of{\nobreakspace}\mbox{\texttt{\slshape G}} or{\nobreakspace}\mbox{\texttt{\slshape g}}, respectively. The second denotes a respected partition consisting of residue
classes $r(m)$ where the modulus of \mbox{\texttt{\slshape G}} (respectively \mbox{\texttt{\slshape g}}) divides{\nobreakspace}$m$. 

 \index{RespectsPartition@\texttt{RespectsPartition}!for an rcwa group} \index{RespectsPartition@\texttt{RespectsPartition}!for an rcwa permutation} There is an operation \texttt{RespectsPartition(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape P}})} / \texttt{RespectsPartition(\mbox{\texttt{\slshape g}},\mbox{\texttt{\slshape P}})}, which tests whether \mbox{\texttt{\slshape G}} or{\nobreakspace}\mbox{\texttt{\slshape g}} respects a given partition{\nobreakspace}\mbox{\texttt{\slshape P}}. The permutation induced by \mbox{\texttt{\slshape g}} on{\nobreakspace}\texttt{P} can be computed efficiently by \texttt{PermutationOpNC(\mbox{\texttt{\slshape g}},P,OnPoints)}. \index{PermutationOpNC@\texttt{PermutationOpNC}!g, P, OnPoints} 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  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) ]
  
\end{Verbatim}
 }

 
\subsection{\textcolor{Chapter }{ ActionOnRespectedPartition \& KernelOfActionOnRespectedPartition }}\logpage{[ 3, 4, 2 ]}
\hyperdef{L}{X7A6786727EC1E4BB}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ActionOnRespectedPartition({\slshape G})\index{ActionOnRespectedPartition@\texttt{ActionOnRespectedPartition}!for a tame rcwa group}
\label{ActionOnRespectedPartition:for a tame rcwa group}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{KernelOfActionOnRespectedPartition({\slshape G})\index{KernelOfActionOnRespectedPartition@\texttt{KernelOfActionOnRespectedPartition}!for a tame rcwa group}
\label{KernelOfActionOnRespectedPartition:for a tame rcwa group}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 The action of the tame rcwa group{\nobreakspace}\mbox{\texttt{\slshape G}} on \texttt{RespectedPartition(\mbox{\texttt{\slshape G}})} or the kernel of this action, respectively. 



 The method for \texttt{KernelOfActionOnRespectedPartition} uses the package \textsf{Polycyclic}{\nobreakspace}\cite{Polycyclic}. The rank of the largest free abelian subgroup of the kernel of the action
of{\nobreakspace}\mbox{\texttt{\slshape G}} on its stored respected partition can be computed by \texttt{RankOfKernelOfActionOnRespectedPartition(\mbox{\texttt{\slshape G}})}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(ClassTransposition(0,4,1,6),ClassShift(0,2));;
  gap> H := ActionOnRespectedPartition(G);
  Group([ (3,7)(5,8), (3,4,5,6) ])
  gap> H = Action(G,P);
  true
  gap> Size(H);
  48
  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> Image(IsomorphismPcpGroup(K));
  Pcp-group with orders [ 0, 0, 0 ]
  
\end{Verbatim}
 }

 Let $G$ be a tame rcwa group over{\nobreakspace}$\Z$, let $\mathcal{P}$ be a respected partition of{\nobreakspace}$G$ and put $m := |\mathcal{P}|$. Then there is an rcwa permutation $g$ which maps $\mathcal{P}$ to the partition of{\nobreakspace}$\Z$ into the residue classes (mod{\nobreakspace}$m$), and the conjugate $G^g$ of{\nobreakspace}$G$ under such a permutation is integral (cp. \cite{Kohl05}, Theorem{\nobreakspace}2.5.14). 

 \index{IntegralConjugate@\texttt{IntegralConjugate}!of a tame rcwa group} \index{IntegralConjugate@\texttt{IntegralConjugate}!of a tame rcwa permutation} \index{IntegralizingConjugator@\texttt{IntegralizingConjugator}!of a tame rcwa group} \index{IntegralizingConjugator@\texttt{IntegralizingConjugator}!of a tame rcwa permutation} The conjugate $G^g$ can be determined by the operation \texttt{IntegralConjugate}, and the conjugating permutation{\nobreakspace}$g$ can be determined by the operation \texttt{IntegralizingConjugator}. Both operations are applicable to rcwa permutations as well. Note that a
tame rcwa group does not determine its integral conjugate uniquely. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(ClassTransposition(0,4,1,6),ClassShift(0,2));;
  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
  
\end{Verbatim}
 }

  
\section{\textcolor{Chapter }{Generating pseudo-random elements of RCWA(R) and CT(R)}}\label{sec:Random}
\logpage{[ 3, 5, 0 ]}
\hyperdef{L}{X8302BA78810C1DEE}{}
{
  \index{Random@\texttt{Random}!RCWA(R)} \index{Random@\texttt{Random}!CT(R)} There are methods for the operation \texttt{Random} for RCWA($R$) and CT($R$). These methods are designed to be suitable for generating interesting
examples. No particular distribution is guaranteed. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> elm := Random(RCWA(Integers));;
  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
  
  
\end{Verbatim}
 The elements which are returned by this method are obtained by multiplying
class shifts (see \texttt{ClassShift} (\ref{ClassShift:r, m})), class reflections (see \texttt{ClassReflection} (\ref{ClassReflection:r, m})) and class transpositions (see \texttt{ClassTransposition} (\ref{ClassTransposition:r1, m1, r2, m2})). These factors can be retrieved by factoring: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Factorization(elm);
  [ ClassTransposition(0,2,3,4), ClassTransposition(3,4,4,6),
    ClassShift(0,2)^-1, ClassReflection(3,4), ClassReflection(1,4) ]
  
\end{Verbatim}
 There is an auxiliary function \texttt{ClassPairs([\mbox{\texttt{\slshape R}},] \mbox{\texttt{\slshape m}})}, which is used in this context. \index{ClassPairs@\texttt{ClassPairs}!m} \index{ClassPairs@\texttt{ClassPairs}!R, m} 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 \leq m$. In its two-argument form, it does ``the equivalent'' for the ring{\nobreakspace}\mbox{\texttt{\slshape R}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  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) ] ]
  
\end{Verbatim}
 }

  
\section{\textcolor{Chapter }{Drawing pictures of orbits on $\Z^2$ }}\label{sec:DrawingPictures}
\logpage{[ 3, 6, 0 ]}
\hyperdef{L}{X7BBC014580F51ABA}{}
{
  \textsf{RCWA} permits drawing pictures of orbits of rcwa groups on{\nobreakspace}$\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. 

\subsection{\textcolor{Chapter }{DrawOrbitPicture (G, p0, r, h, w, colored, palette, filename)}}
\logpage{[ 3, 6, 1 ]}\nobreak
\hyperdef{L}{X7B30F7207817D859}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DrawOrbitPicture({\slshape G, p0, r, h, w, colored, palette, filename})\index{DrawOrbitPicture@\texttt{DrawOrbitPicture}!G, p0, r, h, w, colored, palette, filename}
\label{DrawOrbitPicture:G, p0, r, h, w, colored, palette, filename}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 Nothing. 



 Draws a picture of the orbit(s) of the point(s) \mbox{\texttt{\slshape p0}} under the action of the group \mbox{\texttt{\slshape G}} on{\nobreakspace}$\Z^2$. The argument \mbox{\texttt{\slshape p0}} is either one point or a list of points. The argument \mbox{\texttt{\slshape r}} denotes the radius of the ball around \mbox{\texttt{\slshape p0}} to be computed. The size of the created picture is \mbox{\texttt{\slshape h}}{\nobreakspace}x{\nobreakspace}\mbox{\texttt{\slshape w}} pixels. The argument \mbox{\texttt{\slshape colored}} is a boolean which indicates whether a 24-bit True-Color picture or a
monochrome picture should be drawn. In the former case, \mbox{\texttt{\slshape palette}} 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, \mbox{\texttt{\slshape palette}} is not used, and any value can be passed. The picture is written in bitmap-
(bmp-) format to a file named \mbox{\texttt{\slshape filename}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> PSL2Z := Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(2),
  >                                                    CyclicGroup(3))));;
  gap> DrawOrbitPicture(PSL2Z,[0,1],20,512,512,false,fail,"~/images/example1.bmp");
  gap> DrawOrbitPicture(PSL2Z,Combinations([1..4],2),20,512,512,true,
  >                     [[255,0,0],[0,255,0],[0,0,255]],"~/images/example2.bmp");
  gap> G := Group(ClassShift(0,1),ClassTransposition(1,2,0,4));;
  gap> DrawOrbitPicture(G,[0,1],20,512,512,true,
  >                     List([1..20],i->[255-12*i,255-12*i,255]),
  >                     "~/images/example3.bmp");
  
\end{Verbatim}
 }

 \texttt{DrawOrbitPicture} (\ref{DrawOrbitPicture:G, p0, r, h, w, colored, palette, filename}) makes use of the following utility function: 

\subsection{\textcolor{Chapter }{SaveAsBitmapPicture (picture, filename)}}
\logpage{[ 3, 6, 2 ]}\nobreak
\hyperdef{L}{X81DE1E838615C214}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SaveAsBitmapPicture({\slshape picture, filename})\index{SaveAsBitmapPicture@\texttt{SaveAsBitmapPicture}!picture, filename}
\label{SaveAsBitmapPicture:picture, filename}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 Nothing. 



 Writes the pixel matrix \mbox{\texttt{\slshape picture}} to a bitmap- (bmp-) picture file named \mbox{\texttt{\slshape filename}}. The filename should include the entire pathname. The argument \mbox{\texttt{\slshape picture}} 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 \mbox{\texttt{\slshape picture}} 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 \cdot red + 256 \cdot green + blue$ in the range $0, \dots, 2^{24}-1$ specifying the RGB values of the colors of the pixels. 

 \index{ReadFromBitmapPicture@\texttt{ReadFromBitmapPicture}!filename} The picture can be read back into \textsf{GAP} by the function \texttt{ReadFromBitmapPicture(\mbox{\texttt{\slshape filename}})}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> color   := n->32*(n mod 8)+256*32*(Int(n/8) mod 8)+65536*32*Int(n/64);;
  gap> picture := List([1..512],y->List([1..512],x->color(Gcd(x,y)-1)));;
  gap> SaveAsBitmapPicture(picture,"~/images/gcd.bmp");
  
\end{Verbatim}
 }

 The pictures created in the examples are shown on \textsf{RCWA}'s webpage. }

  
\section{\textcolor{Chapter }{Some general utility functions}}\label{sec:UtilityFunctions}
\logpage{[ 3, 7, 0 ]}
\hyperdef{L}{X8677C67F7AD4C9C7}{}
{
  \index{GeneratorsAndInverses@\texttt{GeneratorsAndInverses}!for a group} \index{EpimorphismByGenerators@\texttt{EpimorphismByGenerators}!for two groups} \index{ListOfPowers@\texttt{ListOfPowers}} \index{AllProducts@\texttt{AllProducts}} \index{DifferencesList@\texttt{DifferencesList}} \index{FloatQuotients@\texttt{FloatQuotients}} \textsf{RCWA} introduces a couple of small utility functions which can be used in a more
general context: The function \texttt{GeneratorsAndInverses(\mbox{\texttt{\slshape G}})} returns a list of generators of \mbox{\texttt{\slshape G}} and their inverses, \texttt{EpimorphismByGenerators(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape H}})} is a shorthand for \texttt{GroupHomomorphismByImages(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape H}}, GeneratorsOfGroup(\mbox{\texttt{\slshape G}}),GeneratorsOfGroup(\mbox{\texttt{\slshape H}}))} (there is also an \texttt{NC} version of this), the function \texttt{ListOfPowers(\mbox{\texttt{\slshape g}},\mbox{\texttt{\slshape exp}})} returns the list \texttt{[\mbox{\texttt{\slshape g}},\mbox{\texttt{\slshape g}}\texttt{\symbol{94}}2,...,\mbox{\texttt{\slshape g}}\texttt{\symbol{94}}\mbox{\texttt{\slshape exp}}]} of powers of{\nobreakspace}\mbox{\texttt{\slshape g}}, the function \texttt{AllProducts(\mbox{\texttt{\slshape l}},\mbox{\texttt{\slshape k}})} returns the list of all products of \mbox{\texttt{\slshape k}} entries of the list{\nobreakspace}\mbox{\texttt{\slshape l}}, the function \texttt{DifferencesList(\mbox{\texttt{\slshape l}})} returns the list of differences of consecutive entries of the
list{\nobreakspace}\mbox{\texttt{\slshape l}}, and the function \texttt{FloatQuotients(\mbox{\texttt{\slshape l}})} returns the list of floating point approximations of quotients of consecutive
entries of the list{\nobreakspace}\mbox{\texttt{\slshape l}}. }

  
\section{\textcolor{Chapter }{The categories of residue-class-wise affine groups}}\label{sec:CategoriesOfRcwaGroups}
\logpage{[ 3, 8, 0 ]}
\hyperdef{L}{X86327F6C83D09798}{}
{
  

\subsection{\textcolor{Chapter }{IsRcwaGroup}}
\logpage{[ 3, 8, 1 ]}\nobreak
\hyperdef{L}{X84AFBB997B694A3D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaGroup({\slshape G})\index{IsRcwaGroup@\texttt{IsRcwaGroup}}
\label{IsRcwaGroup}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaGroupOverZ({\slshape G})\index{IsRcwaGroupOverZ@\texttt{IsRcwaGroupOverZ}}
\label{IsRcwaGroupOverZ}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaGroupOverZ{\textunderscore}pi({\slshape G})\index{IsRcwaGroupOverZpi@\texttt{IsRcwaGroupOverZ{\textunderscore}pi}}
\label{IsRcwaGroupOverZpi}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaGroupOverGFqx({\slshape G})\index{IsRcwaGroupOverGFqx@\texttt{IsRcwaGroupOverGFqx}}
\label{IsRcwaGroupOverGFqx}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} if \mbox{\texttt{\slshape G}} 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 \texttt{false} otherwise. 



 \index{IsRcwaGroupOverZOrZ_pi@\texttt{IsRcwaGroupOverZOrZ{\textunderscore}pi}} 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 \texttt{IsRcwaGroupOverZOrZ{\textunderscore}pi} which is the union of \texttt{IsRcwaGroupOverZ} and \texttt{IsRcwaGroupOverZ{\textunderscore}pi}. 

 \index{IsNaturalRCWA@\texttt{IsNaturalRCWA}} \index{IsNaturalCT@\texttt{IsNaturalCT}} To allow distinguishing the groups RCWA($R$) and CT($R$) from others, they have the characteristic property \texttt{IsNaturalRCWA} or \texttt{IsNaturalCT}, respectively. }

 }

  }

         
\chapter{\textcolor{Chapter }{Residue-Class-Wise Affine Monoids}}\label{ch:RcwaMonoids}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X7D6731AB7FE21290}{}
{
  In this short chapter, we describe how to compute with residue-class-wise
affine monoids. \index{rcwa monoid@rcwa monoid!definition} \emph{Residue-class-wise affine} monoids, or \emph{rcwa} monoids for short, are monoids whose elements are residue-class-wise affine
mappings.  
\section{\textcolor{Chapter }{Constructing residue-class-wise affine monoids}}\label{sec:ContructingRcwaMonoids}
\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X7F95328B7C7E49EA}{}
{
  \index{Monoid@\texttt{Monoid}} \index{MonoidByGenerators@\texttt{MonoidByGenerators}} As any other monoids in \textsf{GAP}, residue-class-wise affine monoids can be constructed by \texttt{Monoid} or \texttt{MonoidByGenerators}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> M := Monoid(RcwaMapping([[ 0,1,1],[1,1,1]]),
  >                RcwaMapping([[-1,3,1],[0,2,1]]));
  <rcwa monoid over Z with 2 generators>
  gap> Size(M);
  11
  gap> Display(MultiplicationTable(M));
  [ [   1,   2,   3,   4,   5,   6,   7,   8,   9,  10,  11 ], 
    [   2,   8,   5,  11,   8,   3,  10,   5,   2,   8,   5 ], 
    [   3,  10,  11,   5,   5,   5,   8,   8,   8,   2,   3 ], 
    [   4,   9,   6,   8,   8,   8,   5,   5,   5,   7,   4 ], 
    [   5,   8,   5,   8,   8,   8,   5,   5,   5,   8,   5 ], 
    [   6,   7,   4,   8,   8,   8,   5,   5,   5,   9,   6 ], 
    [   7,   5,   8,   6,   5,   4,   9,   8,   7,   5,   8 ], 
    [   8,   5,   8,   5,   5,   5,   8,   8,   8,   5,   8 ], 
    [   9,   5,   8,   4,   5,   6,   7,   8,   9,   5,   8 ], 
    [  10,   8,   5,   3,   8,  11,   2,   5,  10,   8,   5 ], 
    [  11,   2,   3,   5,   5,   5,   8,   8,   8,  10,  11 ] ]
  
\end{Verbatim}
 \index{View@\texttt{View}!for an rcwa monoid} \index{Display@\texttt{Display}!for an rcwa monoid} \index{Print@\texttt{Print}!for an rcwa monoid} \index{String@\texttt{String}!for an rcwa monoid} There are methods for the operations \texttt{View}, \texttt{Display}, \texttt{Print} and \texttt{String} which are applicable to rcwa monoids. All rcwa monoids over a ring $R$ are submonoids of Rcwa($R$). The monoid Rcwa($R$) itself is not finitely generated, thus cannot be constructed as described
above. It is handled as a special case: 

\subsection{\textcolor{Chapter }{Rcwa (the monoid of all rcwa mappings of a ring)}}
\logpage{[ 4, 1, 1 ]}\nobreak
\hyperdef{L}{X788C654D8358E642}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Rcwa({\slshape R})\index{Rcwa@\texttt{Rcwa}!the monoid of all rcwa mappings of a ring}
\label{Rcwa:the monoid of all rcwa mappings of a ring}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The monoid Rcwa(\mbox{\texttt{\slshape R}}) of all residue-class-wise affine mappings of the ring{\nobreakspace}\mbox{\texttt{\slshape R}}. 



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> RcwaZ := Rcwa(Integers);
  Rcwa(Z)
  gap> IsSubset(RcwaZ,M);
  true
  
\end{Verbatim}
 }

 \index{Restriction@\texttt{Restriction}!for an rcwa monoid, by an injective rcwa mapping} \index{Induction@\texttt{Induction}!for an rcwa monoid, by an injective rcwa mapping} In our methods to construct rcwa groups, two kinds of mappings played a
crucial role, namely the restriction monomorphisms (cp.{\nobreakspace}\texttt{Restriction} (\ref{Restriction:of an rcwa group, by an injective rcwa mapping})) and the induction epimorphisms (cp.{\nobreakspace}\texttt{Induction} (\ref{Induction:of an rcwa group, by an injective rcwa mapping})). The restriction monomorphisms extend in a natural way to the monoids Rcwa($R$), and the induction epimorphisms have corresponding generalizations, also.
Therefore the operations \texttt{Restriction} and \texttt{Induction} can be applied to rcwa monoids as well: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> M2 := Restriction(M,2*One(Rcwa(Integers)));
  <rcwa monoid over Z with 2 generators, of size 11>
  gap> Support(M2);
  0(2)
  gap> Action(M2,ResidueClass(1,2));
  Trivial rcwa group over Z
  gap> Induction(M2,2*One(Rcwa(Integers))) = M;
  true
  
\end{Verbatim}
 }

  
\section{\textcolor{Chapter }{Computing with residue-class-wise affine monoids}}\label{sec:ComputingWithRcwaMonoids}
\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X7C79D4DF831C57D1}{}
{
  \index{Size@\texttt{Size}!for an rcwa monoid} \index{rcwa monoids@\texttt{rcwa monoids}!membership test} \index{IsSubset@\texttt{IsSubset}!for two rcwa monoids} There is a method for \texttt{Size} which computes the order of an rcwa monoid. Further there is a method for \texttt{in} which checks whether a given rcwa mapping lies in a given rcwa monoid
(membership test), and there is a method for \texttt{IsSubset} which checks for a submonoid relation. 

 \index{Support@\texttt{Support}!of an rcwa monoid} \index{Modulus@\texttt{Modulus}!of an rcwa monoid} \index{IsTame@\texttt{IsTame}!for an rcwa monoid} \index{PrimeSet@\texttt{PrimeSet}!of an rcwa monoid} \index{IsIntegral@\texttt{IsIntegral}!for an rcwa monoid} \index{IsClassWiseOrderPreserving@\texttt{IsClassWiseOrderPreserving}!for an rcwa monoid} \index{IsSignPreserving@\texttt{IsSignPreserving}!for an rcwa monoid} There are also methods for \texttt{Support}, \texttt{Modulus}, \texttt{IsTame}, \texttt{PrimeSet}, \texttt{IsIntegral}, \texttt{IsClassWiseOrderPreserving} and \texttt{IsSignPreserving} available for rcwa monoids. 

 \index{rcwa monoid@rcwa monoid!modulus} \index{rcwa monoid@rcwa monoid!tame} \index{rcwa monoid@rcwa monoid!wild} \index{rcwa monoid@rcwa monoid!prime set} \index{rcwa monoid@rcwa monoid!integral} \index{rcwa monoid@rcwa monoid!class-wise order-preserving} \index{rcwa monoid@rcwa monoid!sign-preserving} The \emph{support} of an rcwa monoid is the union of the supports of its elements. The \emph{modulus} of an rcwa monoid is the lcm of the moduli of its elements in case such an lcm
exists and 0 otherwise. An rcwa monoid is called \emph{tame} if its modulus is nonzero, and \emph{wild} otherwise. The \emph{prime set} of an rcwa monoid is the union of the prime sets of its elements. An rcwa
monoid is called \emph{integral}, \emph{class-wise order-preserving} or \emph{sign-preserving} if all of its elements are so. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> f1 := RcwaMapping([[-1, 1, 1],[ 0,-1, 1]]);;
  gap> f2 := RcwaMapping([[ 1,-1, 1],[-1,-2, 1],[-1, 2, 1]]);; 
  gap> f3 := RcwaMapping([[ 1, 0, 1],[-1, 0, 1]]);; 
  gap> N := Monoid(f1,f2,f3);;
  gap> Size(N);
  366
  gap> List([Monoid(f1,f2),Monoid(f1,f3),Monoid(f2,f3)],Size);
  [ 96, 6, 66 ]
  gap> f1*f2*f3 in N;
  true
  gap> IsSubset(N,M);
  false
  gap> IsSubset(N,Monoid(f1*f2,f3*f2));
  true
  gap> Support(N);
  Integers
  gap> Modulus(N);
  6
  gap> IsTame(N) and IsIntegral(N);
  true
  gap> IsClassWiseOrderPreserving(N) or IsSignPreserving(N);
  false
  gap> Collected(List(AsList(N),Image)); # The images of the elements of N.
  [ [ Integers, 2 ], [ 1(2), 2 ], [ Z \ 1(3), 32 ], [ 0(6), 44 ], 
    [ 0(6) U 1(6), 4 ], [ Z \ 4(6) U 5(6), 32 ], [ 0(6) U 2(6), 4 ], 
    [ 0(6) U 5(6), 4 ], [ 1(6), 44 ], [ 1(6) U [ -1 ], 2 ], [ 1(6) U 3(6), 4 ], 
    [ 1(6) U 5(6), 40 ], [ 2(6), 44 ], [ 2(6) U 3(6), 4 ], [ 3(6), 44 ], 
    [ 3(6) U 5(6), 4 ], [ 5(6), 44 ], [ 5(6) U [ 1 ], 2 ], [ [ -5 ], 1 ], 
    [ [ -4 ], 1 ], [ [ -3 ], 1 ], [ [ -1 ], 1 ], [ [ 0 ], 1 ], [ [ 1 ], 1 ], 
    [ [ 2 ], 1 ], [ [ 3 ], 1 ], [ [ 5 ], 1 ], [ [ 6 ], 1 ] ]
  
\end{Verbatim}
 Finite forward orbits under the action of an rcwa monoid can be found by the
operation \texttt{ShortOrbits}: 

\subsection{\textcolor{Chapter }{ShortOrbits (for rcwa monoid, set of points and bound on length)}}
\logpage{[ 4, 2, 1 ]}\nobreak
\hyperdef{L}{X87DB896687475084}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ShortOrbits({\slshape M, S, maxlng})\index{ShortOrbits@\texttt{ShortOrbits}!for rcwa monoid, set of points and bound on length}
\label{ShortOrbits:for rcwa monoid, set of points and bound on length}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 A list of finite forward orbits of the rcwa monoid{\nobreakspace}\mbox{\texttt{\slshape M}} of length at most{\nobreakspace}\mbox{\texttt{\slshape maxlng}} which start at points in the set{\nobreakspace}\mbox{\texttt{\slshape S}}. 



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> ShortOrbits(M,[-5..5],20);
  [ [ -5, -4, 1, 2, 7, 8 ], [ -3, -2, 1, 2, 5, 6 ], [ -1, 0, 1, 2, 3, 4 ] ]
  gap> Display(Action(M,last[1]));
  Monoid( [ Transformation( [ 2, 3, 4, 3, 6, 3 ] ), 
    Transformation( [ 4, 5, 4, 3, 4, 1 ] ) ], ... )
  gap> orbs := ShortOrbits(N,[0..10],50);
  [ [ -5, -4, -3, -1, 0, 1, 2, 3, 5, 6 ], 
    [ -11, -10, -9, -7, -6, -5, -4, -3, -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 
        12 ], [ -17, -16, -15, -13, -12, -11, -10, -9, -7, -6, -5, -4, -3, -1, 
        0, 1, 2, 3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 17, 18 ] ]
  gap> quots := List(orbs,orb->Action(N,orb));
  [ <monoid with 3 generators>, <monoid with 3 generators>,
    <monoid with 3 generators> ]
  gap> List(quots,Size);
  [ 268, 332, 366 ]
  
\end{Verbatim}
 }

 Balls of given radius around an element of an rcwa monoid can be computed by
the operation \texttt{Ball}. This operation can also be used for computing forward orbits or subsets of
such under the action of an rcwa monoid: 
\subsection{\textcolor{Chapter }{ Ball (for monoid, element and radius or monoid, point, radius and action) }}\logpage{[ 4, 2, 2 ]}
\hyperdef{L}{X858D31247B53A76F}{}
{
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Ball({\slshape M, f, r})\index{Ball@\texttt{Ball}!for monoid, element and radius}
\label{Ball:for monoid, element and radius}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Ball({\slshape M, p, r, action})\index{Ball@\texttt{Ball}!for monoid, point, radius and action}
\label{Ball:for monoid, point, radius and action}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 The ball of radius{\nobreakspace}\mbox{\texttt{\slshape r}} around the element{\nobreakspace}\mbox{\texttt{\slshape f}} in the monoid{\nobreakspace}\mbox{\texttt{\slshape M}}, respectively the ball of radius{\nobreakspace}\mbox{\texttt{\slshape r}} around the point{\nobreakspace}\mbox{\texttt{\slshape p}} under the action{\nobreakspace}\mbox{\texttt{\slshape action}} of the monoid{\nobreakspace}\mbox{\texttt{\slshape M}}. 



 All balls are understood with respect to \texttt{GeneratorsOfMonoid(\mbox{\texttt{\slshape M}})}. As membership tests can be expensive, the first-mentioned method does not
check whether \mbox{\texttt{\slshape f}} is indeed an element of{\nobreakspace}\mbox{\texttt{\slshape M}}. The methods require that point- / element comparisons are cheap. They are
not only applicable to rcwa monoids. If the option \mbox{\texttt{\slshape Spheres}} is set, the ball is splitted up and returned as a list of spheres. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List([0..12],k->Length(Ball(N,One(N),k)));
  [ 1, 4, 11, 26, 53, 99, 163, 228, 285, 329, 354, 364, 366 ]
  gap> Ball(N,[0..3],2,OnTuples);
  [ [ -3, 3, 3, 3 ], [ -1, -3, 0, 2 ], [ -1, -1, -1, -1 ], [ -1, -1, 1, -1 ], 
    [ -1, 1, 1, 1 ], [ -1, 3, 0, -4 ], [ 0, -1, 2, -3 ], [ 0, 1, 2, 3 ], 
    [ 1, -1, -1, -1 ], [ 1, 3, 0, 2 ], [ 3, -4, -1, 0 ] ]
  gap> l := 2*IdentityRcwaMappingOfZ; r := l+1;
  Rcwa mapping of Z: n -> 2n
  Rcwa mapping of Z: n -> 2n + 1
  gap> Ball(Monoid(l,r),1,4,OnPoints:Spheres);
  [ [ 1 ], [ 2, 3 ], [ 4, 5, 6, 7 ], [ 8, 9, 10, 11, 12, 13, 14, 15 ], 
    [ 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ] ]
  
\end{Verbatim}
 }

 }

  }

         
\chapter{\textcolor{Chapter }{Examples}}\label{ch:Examples}
\logpage{[ 5, 0, 0 ]}
\hyperdef{L}{X7A489A5D79DA9E5C}{}
{
 This chapter discusses a number of ``nice'' examples of rcwa mappings and -groups in detail. All of them show different
aspects of the package, and the order in which they appear is entirely
arbitrary. In particular they are not ordered by degree of interestingness or
difficulty. 

 Please note that now since quite a while no further examples have been added
to this chapter, and that the capabilities of this package have been extended
considerably in the meantime. 

 The rcwa mappings defined in this chapter (and in fact many more) can be found
in the file \texttt{pkg/rcwa/examples/examples.g}, so there is no need to extract them from the manual files. This file can be
read into the current \textsf{GAP} session by issueing \texttt{RCWAReadExamples( );}. 

 The examples are typically far from discussing the respective aspects
exhaustively. It is quite likely that in many instances by just a few little
modifications or additional easy commands you can find out interesting things
yourself -- have fun!  
\section{\textcolor{Chapter }{ Factoring Collatz' permutation of the integers }}\label{sec:FactoringTheCollatzPermutation}
\logpage{[ 5, 1, 0 ]}
\hyperdef{L}{X86C2BAE3876985A6}{}
{
  In 1932, Lothar Collatz mentioned in his notebook the following permutation of
the integers: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Collatz := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);;
  gap> SetName(Collatz,"Collatz"); Display(Collatz);
  
  Rcwa mapping of Z with modulus 3
  
                  n mod 3                |              n^Collatz
  ---------------------------------------+--------------------------------------
    0                                    | 2n/3
    1                                    | (4n - 1)/3
    2                                    | (4n + 1)/3
  
  gap> ShortCycles(Collatz,[-50..50],50); # This permutation has some finite cycles:
  [ [ -111, -74, -99, -66, -44, -59, -79, -105, -70, -93, -62, -83 ],
    [ -9, -6, -4, -5, -7 ], [ -3, -2 ], [ -1 ], [ 0 ], [ 1 ], [ 2, 3 ],
    [ 4, 5, 7, 9, 6 ], [ 44, 59, 79, 105, 70, 93, 62, 83, 111, 74, 99, 66 ] ]
  
\end{Verbatim}
 The cycle structure of Collatz' permutation has not been completely determined
yet. In particular it is not known whether the cycle
containing{\nobreakspace}8 is finite or infinite. Nevertheless, the
factorization routine included in this package can determine a factorization
of this permutation into class transpositions, i.e. involutions interchanging
two disjoint residue classes: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Collatz in CT(Integers);  # `Collatz' lies in the simple group CT(Z).
  true
  gap> Length(Factorization(Collatz));
  212
  
\end{Verbatim}
 Setting the Info level of \texttt{InfoRCWA} equal to{\nobreakspace}2 (simply issue \texttt{RCWAInfo(2);}) causes the factorization routine to display detailed information on the
progress of the factoring process. For reasons of saving space, this is not
done in this manual. 

 We would like to get a factorization into fewer factors. Firstly, we try to
factor the inverse -- just like the various options interpreted by the
factorization routine, this has influence on decisions taken during the
factoring process: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Length(Factorization(Collatz^-1));
  129
  
\end{Verbatim}
 This is already a shorter product, but can still be improved. We remember the \texttt{mKnot}'s, of which the permutation \texttt{mKnot(3)} looks very similar to Collatz' permutation. Therefore it is straightforward to
try to factor both \texttt{mKnot(3)} and \texttt{Collatz/mKnot(3)}, and to look whether the sum of the numbers of factors is less
than{\nobreakspace}129: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> KnotFacts := Factorization(mKnot(3));;
  gap> QuotFacts := Factorization(Collatz/mKnot(3));;
  gap> List([KnotFacts,QuotFacts],Length);
  [ 59, 9 ]
  gap> CollatzFacts := Concatenation(QuotFacts,KnotFacts);
  [ ClassTransposition(0,6,4,6), ClassTransposition(0,6,5,6), 
    ClassTransposition(0,6,3,6), ClassTransposition(0,6,1,6), 
    ClassTransposition(0,6,2,6), ClassTransposition(2,3,4,6), 
    ClassTransposition(0,3,4,6), ClassTransposition(2,3,1,6), 
    ClassTransposition(0,3,1,6), ClassTransposition(0,36,35,36), 
    ClassTransposition(0,36,22,36), ClassTransposition(0,36,18,36), 
    ClassTransposition(0,36,17,36), ClassTransposition(0,36,14,36), 
    ClassTransposition(0,36,20,36), ClassTransposition(0,36,4,36), 
    ClassTransposition(2,36,8,36), ClassTransposition(2,36,16,36), 
    ClassTransposition(2,36,13,36), ClassTransposition(2,36,9,36), 
    ClassTransposition(2,36,7,36), ClassTransposition(2,36,6,36), 
    ClassTransposition(2,36,3,36), ClassTransposition(2,36,10,36), 
    ClassTransposition(2,36,15,36), ClassTransposition(2,36,12,36), 
    ClassTransposition(2,36,5,36), ClassTransposition(21,36,28,36), 
    ClassTransposition(21,36,33,36), ClassTransposition(21,36,30,36), 
    ClassTransposition(21,36,23,36), ClassTransposition(21,36,34,36), 
    ClassTransposition(21,36,31,36), ClassTransposition(21,36,27,36), 
    ClassTransposition(21,36,25,36), ClassTransposition(21,36,24,36), 
    ClassTransposition(26,36,32,36), ClassTransposition(26,36,29,36), 
    ClassTransposition(10,18,35,36), ClassTransposition(5,18,35,36), 
    ClassTransposition(10,18,17,36), ClassTransposition(5,18,17,36), 
    ClassTransposition(8,12,14,24), ClassTransposition(6,9,17,18), 
    ClassTransposition(3,9,17,18), ClassTransposition(0,9,17,18), 
    ClassTransposition(6,9,16,18), ClassTransposition(3,9,16,18), 
    ClassTransposition(0,9,16,18), ClassTransposition(6,9,11,18), 
    ClassTransposition(3,9,11,18), ClassTransposition(0,9,11,18), 
    ClassTransposition(6,9,4,18), ClassTransposition(3,9,4,18), 
    ClassTransposition(0,9,4,18), ClassTransposition(0,6,14,24), 
    ClassTransposition(0,6,2,24), ClassTransposition(8,12,17,18), 
    ClassTransposition(7,12,17,18), ClassTransposition(8,12,11,18), 
    ClassTransposition(7,12,11,18), PrimeSwitch(3)^-1, 
    ClassTransposition(7,12,17,18), ClassTransposition(2,6,17,18), 
    ClassTransposition(0,3,17,18), PrimeSwitch(3)^-1, PrimeSwitch(3)^-1, 
    PrimeSwitch(3)^-1 ]
  gap> Product(CollatzFacts) = Collatz; # Check.
  true
  
\end{Verbatim}
 The factors \texttt{PrimeSwitch(3)} are products of 6 class transpositions (cp.{\nobreakspace}\texttt{PrimeSwitch} (\ref{PrimeSwitch:p})). At the end of Section \ref{sec:WildButFiniteCycles}, a much smaller factorization task is performed ``manually'' for purposes of illustration. }

  
\section{\textcolor{Chapter }{ An rcwa mapping which seems to be contracting, but very slow }}\label{sec:SlowlyContractingMapping}
\logpage{[ 5, 2, 0 ]}
\hyperdef{L}{X878499AF7889FD9E}{}
{
  The iterates of an integer under the Collatz mapping $T$ seem to approach its contraction centre -- this is the finite set where all
trajectories end up after a finite number of steps -- rather quickly and do
not get very large before doing so (of course this is a purely heuristic
statement as the $3n+1$ Conjecture has not been proved so far!): 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> T := RcwaMapping([[1,0,2],[3,1,2]]);;
  gap> S0 := LikelyContractionCentre(T,100,1000);
  #I  Warning: `LikelyContractionCentre' is highly probabilistic.
  The returned result can only be regarded as a rough guess.
  See ?LikelyContractionCentre for information on how to improve this guess.
  [ -136, -91, -82, -68, -61, -55, -41, -37, -34, -25, -17, -10, -7, -5, -1, 0, 
    1, 2 ]
  gap> S0^T = S0; # This holds by definition of the contraction centre.
  true
  gap> List([1..40],n->Length(Trajectory(T,n,S0)));
  [ 1, 1, 5, 2, 4, 6, 11, 3, 13, 5, 10, 7, 7, 12, 12, 4, 9, 14, 14, 6, 6, 11, 
    11, 8, 16, 8, 70, 13, 13, 13, 67, 5, 18, 10, 10, 15, 15, 15, 23, 7 ]
  gap> Maximum(List([1..1000],n->Length(Trajectory(T,n,S0))));
  113
  gap> Maximum(List([1..1000],n->Maximum(Trajectory(T,n,S0))));
  125252
  
\end{Verbatim}
 \pagebreak[4] The following mapping seems to be contracting as well, but its trajectories
are much longer: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> f6 := RcwaMapping([[ 1,0,6],[ 5, 1,6],[ 7,-2,6],
  >                       [11,3,6],[11,-2,6],[11,-1,6]]);;
  gap> SetName(f6,"f6");
  gap> Display(f6);
  
  Rcwa mapping of Z with modulus 6
  
                  n mod 6                |                 n^f6
  ---------------------------------------+--------------------------------------
    0                                    | n/6
    1                                    | (5n + 1)/6
    2                                    | (7n - 2)/6
    3                                    | (11n + 3)/6
    4                                    | (11n - 2)/6
    5                                    | (11n - 1)/6
  
  gap> S0 := LikelyContractionCentre(f6,1000,100000);;
  #I  Warning: `LikelyContractionCentre' is highly probabilistic.
  The returned result can only be regarded as a rough guess.
  gap> Trajectory(f6,25,S0);
  [ 25, 21, 39, 72, 12, 2 ]
  gap> List([1..100],n->Length(Trajectory(f6,n,S0)));
  [ 2, 2, 3, 4, 2, 2, 3, 2, 2, 5, 7, 2, 8, 17, 3, 16, 2, 4, 17, 6, 5, 2, 5, 5, 
    6, 2, 4, 2, 15, 2, 2, 3, 2, 5, 13, 3, 2, 3, 4, 2, 8, 4, 4, 2, 7, 19, 23517, 
    3, 9, 3, 2, 18, 14, 2, 20, 23512, 14, 2, 6, 6, 2, 4, 19, 12, 23511, 8, 
    23513, 10, 2, 13, 13, 3, 2, 23517, 7, 20, 7, 9, 9, 6, 12, 8, 6, 18, 14, 
    23516, 31, 12, 23545, 4, 21, 19, 5, 2, 17, 17, 13, 19, 6, 23515 ]
  gap> Maximum(Trajectory(f6,47,S0));;
  736339177776247330443187705477107581873369010805146980871580925673774229545698\
  886054
  
\end{Verbatim}
 Computing the trajectory of 3224 takes quite a while -- this trajectory
ascends to about $3 \cdot 10^{2197}$, before it approaches the fixed point{\nobreakspace}2 after 19949562 steps. 

 When constructing the mapping \texttt{f6}, the denominators of the partial mappings have been chosen to be equal and
the numerators have been chosen to be numbers coprime to the common
denominator, whose product is just a little bit smaller than the \texttt{Modulus(f6)}th power of the denominator. In the example we have $5 \cdot 7 \cdot 11^3 = 46585$ and $6^6 = 46656$. 

 Although the trajectories of \texttt{T} are much shorter than those of \texttt{f6}, it seems likely that this does not make the problem of deciding whether the
mapping{\nobreakspace}\texttt{T} is contracting essentially easier -- even for mappings with much shorter
trajectories than{\nobreakspace}\texttt{T} the problem seems to be equally hard. A solution can usually only be found in
trivial cases, i.e. for example when there is some $k$ such that applying the $k$th power of the respective mapping to any integer decreases its absolute
value. }

 \pagebreak[4]  
\section{\textcolor{Chapter }{Checking a result by P. Andaloro}}\label{sec:AndaloroResult}
\logpage{[ 5, 3, 0 ]}
\hyperdef{L}{X84A915BA833E0BDE}{}
{
  In \cite{Andaloro00}, P.{\nobreakspace}Andaloro has shown that proving that trajectories of
integers $n \in 1(16)$ under the Collatz mapping always contain{\nobreakspace}1 would be sufficient
to prove the $3n+1$ Conjecture. In the sequel, this result is verified by \textsf{RCWA}. Checking that the union of the images of the residue class 1(16) under
powers of the Collatz mapping{\nobreakspace}$T$ contains $\Z \setminus 0(3)$ is obviously enough. Thus we put $S := 1(16)$, and successively unite the set{\nobreakspace}$S$ with its image under{\nobreakspace}$T$: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> S := ResidueClass(Integers,16,1);
  1(16)
  gap> S := Union(S,S^T);
  1(16) U 2(24)
  gap> S := Union(S,S^T);
  1(12) U 2(24) U 17(48) U 33(48)
  gap> S := Union(S,S^T);
  <union of 30 residue classes (mod 144)>
  gap> S := Union(S,S^T);
  <union of 42 residue classes (mod 144)>
  gap> S := Union(S,S^T);
  <union of 172 residue classes (mod 432)>
  gap> S := Union(S,S^T);
  <union of 676 residue classes (mod 1296)>
  gap> S := Union(S,S^T);
  <union of 810 residue classes (mod 1296)>
  gap> S := Union(S,S^T);
  <union of 2638 residue classes (mod 3888)>
  gap> S := Union(S,S^T);
  <union of 33 residue classes (mod 48)>
  gap> S := Union(S,S^T);
  <union of 33 residue classes (mod 48)>
  gap> Union(S,ResidueClass(Integers,3,0)); # Et voila ...
  Integers
  
\end{Verbatim}
 Further similar computations are shown in Section{\nobreakspace}\ref{sec:CollatzImagesAndPreImages}. }

 \pagebreak[4]  
\section{\textcolor{Chapter }{Two examples by Matthews and Leigh}}\label{sec:MatthewsLeighExamples}
\logpage{[ 5, 4, 0 ]}
\hyperdef{L}{X7E8CD9B67ED78735}{}
{
  In \cite{MatthewsLeigh87}, K.{\nobreakspace}R.{\nobreakspace}Matthews and
G.{\nobreakspace}M.{\nobreakspace}Leigh have shown that two trajectories of
the following (surjective, but not injective) mappings are acyclic
(mod{\nobreakspace}$x$) and divergent: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> x := Indeterminate(GF(4),1);; SetName(x,"x");
  gap> R := PolynomialRing(GF(2),1);
  GF(2)[x]
  gap> ML1 := RcwaMapping(R,x,[[1,0,x],[(x+1)^3,1,x]]*One(R));;
  gap> ML2 := RcwaMapping(R,x,[[1,0,x],[(x+1)^2,1,x]]*One(R));;
  gap> SetName(ML1,"ML1"); SetName(ML2,"ML2");
  gap> Display(ML1);
  
  Rcwa mapping of GF(2)[x] with modulus x
  
           P mod x          |                       P^ML1
  --------------------------+---------------------------------------------------
   0*Z(2)                   | P/x
   Z(2)^0                   | ((x^3+x^2+x+Z(2)^0)*P + Z(2)^0)/x
  
  gap> Display(ML2);
  
  Rcwa mapping of GF(2)[x] with modulus x
  
           P mod x          |                       P^ML2
  --------------------------+---------------------------------------------------
   0*Z(2)                   | P/x
   Z(2)^0                   | ((x^2+Z(2)^0)*P + Z(2)^0)/x
  
  gap> List([ML1,ML2],IsSurjective);
  [ true, true ]
  gap> List([ML1,ML2],IsInjective);
  [ false, false ]
  gap> traj1 := Trajectory(ML1,One(R),16);
  [ Z(2)^0, x^2+x+Z(2)^0, x^4+x^2+x, x^3+x+Z(2)^0, x^5+x^4+x^2, x^4+x^3+x, 
    x^3+x^2+Z(2)^0, x^5+x^2+Z(2)^0, x^7+x^6+x^5+x^3+Z(2)^0, 
    x^9+x^7+x^6+x^5+x^3+x+Z(2)^0, x^11+x^10+x^8+x^7+x^6+x^5+x^2, 
    x^10+x^9+x^7+x^6+x^5+x^4+x, x^9+x^8+x^6+x^5+x^4+x^3+Z(2)^0, 
    x^11+x^8+x^7+x^6+x^4+x+Z(2)^0, x^13+x^12+x^11+x^8+x^7+x^6+x^4, 
    x^12+x^11+x^10+x^7+x^6+x^5+x^3 ]
  gap> traj2 := Trajectory(ML2,(x^3+x+1)*One(R),16);
  [ x^3+x+Z(2)^0, x^4+x+Z(2)^0, x^5+x^3+x^2+x+Z(2)^0, x^6+x^3+Z(2)^0, 
    x^7+x^5+x^4+x^2+x, x^6+x^4+x^3+x+Z(2)^0, x^7+x^4+x^3+x+Z(2)^0, 
    x^8+x^6+x^5+x^4+x^3+x+Z(2)^0, x^9+x^6+x^3+x+Z(2)^0, 
    x^10+x^8+x^7+x^5+x^4+x+Z(2)^0, x^11+x^8+x^7+x^5+x^4+x^3+x^2+x+Z(2)^0, 
    x^12+x^10+x^9+x^8+x^7+x^5+Z(2)^0, x^13+x^10+x^7+x^4+x, 
    x^12+x^9+x^6+x^3+Z(2)^0, x^13+x^11+x^10+x^8+x^7+x^5+x^4+x^2+x, 
    x^12+x^10+x^9+x^7+x^6+x^4+x^3+x+Z(2)^0 ]
  
\end{Verbatim}
 \pagebreak[4] The pattern which Matthews and Leigh used to show the divergence of the above
trajectories can be recognized easily by looking at the corresponding Markov
chains with the two states 0{\nobreakspace}mod{\nobreakspace}$x$ and 1{\nobreakspace}mod{\nobreakspace}$x$: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> traj1modx := Trajectory(ML1,One(R),400,x);;
  gap> traj2modx := Trajectory(ML2,(x^3+x+1)*One(R),600,x);;
  gap> List(traj1modx{[1..200]},val->Position([Zero(R),One(R)],val)-1);
  [ 1, 1, 0, 1, 0, 0, 1, 1, 1, 1, 0, 0, 1, 1, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 
    1, 0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 
    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ]
  gap> List(traj2modx{[1..200]},val->Position([Zero(R),One(R)],val)-1);
  [ 1, 1, 1, 1, 0, 1, 1, 1, 1, 1, 1, 1, 0, 1, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 1, 1, 0, 1, 0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 
    1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 
    1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 
    0, 1, 0, 1, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ]
  
\end{Verbatim}
 What is important here are the lengths of the intervals between two changes
from one state to the other: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> ChangePoints := l -> Filtered([1..Length(l)-1],pos->l[pos]<>l[pos+1]);;
  gap> Diffs := l -> List([1..Length(l)-1],pos->l[pos+1]-l[pos]);;
  gap> Diffs(ChangePoints(traj1modx)); # The pattern in the first ...
  [ 1, 1, 2, 4, 2, 2, 4, 8, 4, 4, 8, 16, 8, 8, 16, 32, 16, 16, 32, 64, 32, 32, 
    64 ]
  gap> Diffs(ChangePoints(traj2modx)); # ... and in the second example.
  [ 1, 7, 1, 1, 1, 13, 1, 1, 1, 1, 1, 1, 1, 25, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 1, 1, 1, 1, 49, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 97, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 193, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 
    1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ]
  gap> Diffs(ChangePoints(last)); # Make this a bit more obvious.
  [ 1, 3, 1, 7, 1, 15, 1, 31, 1, 63, 1 ]
  
\end{Verbatim}
 This looks clearly acyclic, thus the trajectories diverge. Needless to say
however that this computational evidence does not replace the proof along
these lines given in the article cited above, but just sheds a light on the
idea behind it. }

  
\section{\textcolor{Chapter }{Exploring the structure of a wild rcwa group}}\label{sec:StructureOfWildGroup}
\logpage{[ 5, 5, 0 ]}
\hyperdef{L}{X7A8F55CA87A16900}{}
{
  In this example, a simple attempt to should be made to investigate the
structure of a given wild group by finding orders of torsion elements. In
general, determining the structure of a given wild group seems to be a very
hard task. First of all, the group in question has to be defined: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> u := RcwaMapping([[3,0,5],[9,1,5],[3,-1,5],[9,-2,5],[9,4,5]]);;
  gap> SetName(u,"u");
  gap> Display(u);
  
  Rcwa mapping of Z with modulus 5
  
                  n mod 5                |                 n^u
  ---------------------------------------+--------------------------------------
    0                                    | 3n/5
    1                                    | (9n + 1)/5
    2                                    | (3n - 1)/5
    3                                    | (9n - 2)/5
    4                                    | (9n + 4)/5
  
  gap> nu := ClassShift(0,1);;
  gap> G := Group(u,nu);
  <rcwa group over Z with 2 generators>
  gap> IsTame(G);
  false
  
\end{Verbatim}
 Now we would like to know which orders torsion elements of{\nobreakspace}\texttt{G} can have -- taking a look at the above generators it seems to make sense to
try commutators: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> l := Filtered([0..100],k->IsTame(Comm(u,nu^k)));
  [ 0, 2, 3, 5, 6, 9, 10, 12, 13, 15, 17, 18, 20, 21, 24, 25, 27, 28, 30, 32, 
    33, 35, 36, 39, 40, 42, 43, 45, 47, 48, 50, 51, 54, 55, 57, 58, 60, 62, 63, 
    65, 66, 69, 70, 72, 73, 75, 77, 78, 80, 81, 84, 85, 87, 88, 90, 92, 93, 95, 
    96, 99, 100 ]
  gap> List(l,k->Order(Comm(u,nu^k)));
  [ 1, 6, 5, 3, 5, 5, 3, infinity, 7, infinity, 7, 5, 3, infinity, infinity, 3, 
    5, 7, infinity, 7, infinity, 3, 5, 5, 3, 5, infinity, infinity, infinity, 
    5, 3, 5, 5, 3, infinity, 7, infinity, 7, 5, 3, infinity, infinity, 3, 5, 7, 
    infinity, 7, infinity, 3, 5, 5, 3, 5, infinity, infinity, infinity, 5, 3, 
    5, 5, 3 ]
  
\end{Verbatim}
 \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Display(Comm(u,nu^13));
  
  Bijective rcwa mapping of Z with modulus 9
  
                  n mod 9                |                 n^f
  ---------------------------------------+--------------------------------------
    0 3 6                                | n + 5
    1 4 7                                | 3n - 9
    2 8                                  | n - 11
    5                                    | (n + 16)/3
  
  gap> Order(Comm(u,nu^13));
  7
  gap> u2 := u^2;
  <wild bijective rcwa mapping of Z with modulus 25>
  gap> Filtered([1..16],k->IsTame(Comm(u2,nu^k))); # k < 15 -> commutator wild!
  [ 15 ]
  gap> Order(Comm(u2,nu^15));
  infinity
  gap> u2nu17 := Comm(u2,nu^17);
  <bijective rcwa mapping of Z with modulus 81>
  gap> orbs := ShortOrbits(Group(u2nu17),[-100..100],100);;
  gap> List(orbs,Length);
  [ 72, 72, 73, 72, 73, 72, 72, 73, 72, 72, 72, 73, 72, 72, 73, 72, 72, 73, 72, 
    72, 73, 72, 72 ]
  gap> Lcm(last);
  5256
  gap> u2nu17^5256; # This element has indeed order 2^3*3^2*73 = 5256.
  IdentityMapping( Integers )
  gap> u2nu18 := Comm(u2,nu^18);
  <bijective rcwa mapping of Z with modulus 81>
  gap> orbs := ShortOrbits(Group(u2nu18),[-100..100],100);;
  gap> List(orbs,Length);
  [ 22, 22, 22, 21, 22, 22, 22, 21, 21, 22, 22, 21, 22, 21, 22, 22, 21, 22, 22, 
    21, 22, 22, 21 ]
  gap> Lcm(last);
  462
  gap> u2nu18^462; # This is an element of order 2*3*7*11 = 462.
  IdentityMapping( Integers )
  gap> Order(Comm(u2,nu^20));
  29
  gap> Order(Comm(u2,nu^25));
  9
  gap> Order(Comm(u2,nu^30));
  15
  
\end{Verbatim}
 Thus even this rather simple-minded approach reveals various different orders
of torsion elements, and the involved primes are also not all very ``small''. }

  
\section{\textcolor{Chapter }{A wild rcwa mapping which has only finite cycles}}\label{sec:WildButFiniteCycles}
\logpage{[ 5, 6, 0 ]}
\hyperdef{L}{X7D0928AE839F1C49}{}
{
  Some wild rcwa mappings of $\Z$ have only finite cycles. In this section, a permutation is examined which can
be shown to be such a mapping and which is likely to be something like a ``minimal'' example. 

 Over $R$ = GF($q$)[$x$], the degree function gives rise to a partition of $R$ into finite sets which is left invariant by suitable wild rcwa mappings. Over $R = \Z$ the situation looks different -- there is no such ``natural'' partition into finite sets which can be fixed by a wild rcwa mapping. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> kappa := RcwaMapping([[1,0,1],[1,0,1],[3,2,2],[1,-1,1],
  >                          [2,0,1],[1,0,1],[3,2,2],[1,-1,1],
  >                          [1,1,3],[1,0,1],[3,2,2],[2,-2,1]]);;
  gap> SetName(kappa,"kappa");
  gap> List([-5..5],k->Modulus(kappa^k));
  [ 7776, 1296, 432, 72, 24, 1, 12, 72, 144, 864, 1728 ]
  gap> Display(kappa);
  
  Bijective rcwa mapping of Z with modulus 12
  
                 n mod 12                |               n^kappa
  ---------------------------------------+--------------------------------------
     0  1  5  9                          | n
     2  6 10                             | (3n + 2)/2
     3  7                                | n - 1
     4                                   | 2n
     8                                   | (n + 1)/3
    11                                   | 2n - 2
  
  gap> List([-32..32],n->Length(Cycle(kappa,n)));
  [ 4, 1, 4, 4, 7, 1, 10, 10, 1, 1, 4, 4, 7, 1, 10, 10, 4, 1, 7, 7, 1, 1, 7, 7, 
    4, 1, 4, 4, 2, 1, 1, 2, 1, 1, 4, 4, 4, 1, 7, 7, 4, 1, 7, 7, 1, 1, 10, 10, 
    7, 1, 4, 4, 7, 1, 10, 10, 1, 1, 4, 4, 4, 1, 13, 13, 7 ]
  gap> List([2..14],k->Maximum(List([1..2^k],n->Length(Cycle(kappa,n)))));
  [ 4, 7, 10, 13, 16, 19, 22, 25, 28, 31, 34, 37, 40 ]
  gap> List([2..14],k->Length(Cycle(kappa,2^k-2)));
  [ 4, 7, 10, 13, 16, 19, 22, 25, 28, 31, 34, 37, 40 ]
  gap> Cycle(kappa,2^12-2);
  [ 4094, 6142, 9214, 13822, 20734, 31102, 46654, 69982, 104974, 157462, 
    236194, 354292, 708584, 236195, 472388, 157463, 314924, 104975, 209948, 
    69983, 139964, 46655, 93308, 31103, 62204, 20735, 41468, 13823, 27644, 
    9215, 18428, 6143, 12284, 4095 ]
  gap> last mod 12;
  [ 2, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 4, 8, 11, 8, 11, 8, 11, 8, 11, 
    8, 11, 8, 11, 8, 11, 8, 11, 8, 11, 8, 11, 8, 3 ]
  gap> lengthstatistics := Collected(List(ShortOrbits(Group(kappa),
  >                                                   [1..12^4],100),Length));
  [ [ 1, 6912 ], [ 4, 1728 ], [ 7, 864 ], [ 10, 432 ], [ 13, 216 ], 
    [ 16, 108 ], [ 19, 54 ], [ 22, 27 ], [ 25, 13 ], [ 28, 7 ], [ 31, 3 ], 
    [ 34, 2 ], [ 37, 1 ], [ 40, 1 ] ]
  
\end{Verbatim}
 \pagebreak[4] We would like to determine a partition of{\nobreakspace}$\Z$ into unions of cycles of equal length: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> C := [Difference(Integers,MovedPoints(kappa))];; pow := [kappa^0];;
  gap> rc := function(r,m) return ResidueClass(r,m); end;;
  gap> for i in [1..3] do
  >      Add(pow,kappa^i);
  >      C[i+1] := Difference(rc(2,4),
  >                           Union(Union(C{[1..i]}),
  >                                 Union(List([0..i],
  >                                       j->Intersection(rc(2,4)^pow[j+1],
  >                                                       rc(2,4)^(pow[i-j+1]^-1))))));
  >    od;
  gap> C;
  [ 1(4) U 0(12) U [ -2 ], 2(24) U 18(24), 6(48) U 38(48) U 10(72) U 58(72), 
    <union of 38 residue classes (mod 864)> ]
  gap> List(C,S->Length(Cycle(kappa,S)));
  [ 1, 4, 7, 10 ]
  gap> Cycle(kappa,C[1]);
  [ 1(4) U 0(12) U [ -2 ] ]
  gap> Cycle(kappa,C[2]);
  [ 2(24) U 18(24), 4(36) U 28(36), 8(72) U 56(72), 3(24) U 19(24) ]
  gap> cycle7 := Cycle(kappa,C[3]);;
  gap> for S in cycle7 do View(S); Print("\n"); od;
  6(48) U 38(48) U 10(72) U 58(72)
  10(72) U 58(72) U 16(108) U 88(108)
  16(108) U 88(108) U 32(216) U 176(216)
  11(72) U 59(72) U 32(216) U 176(216)
  11(72) U 59(72) U 20(144) U 116(144)
  7(48) U 39(48) U 20(144) U 116(144)
  6(48) U 7(48) U 38(48) U 39(48)
  gap> cycle10 := Cycle(kappa,C[4]);;
  gap> for S in cycle10 do View(S); Print("\n"); od;
  <union of 38 residue classes (mod 864)>
  <union of 38 residue classes (mod 1296)>
  <union of 12 residue classes (mod 648)>
  <union of 12 residue classes (mod 648)>
  <union of 22 residue classes (mod 1296)>
  <union of 12 residue classes (mod 432)>
  <union of 22 residue classes (mod 864)>
  <union of 12 residue classes (mod 288)>
  <union of 14 residue classes (mod 288)>
  <union of 16 residue classes (mod 288)>
  gap> List(cycle10,Density);
  [ 19/432, 19/648, 1/54, 1/54, 11/648, 1/36, 11/432, 1/24, 7/144, 1/18 ]
  gap> List(last,Float);
  [ 0.0439815, 0.029321, 0.0185185, 0.0185185, 0.0169753, 0.0277778, 0.025463, 
    0.0416667, 0.0486111, 0.0555556 ]
  gap> Sum(last2);
  47/144
  gap> Density(Union(cycle10));
  47/432
  
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> P := List(C,S->Union(Cycle(kappa,S)));;
  gap> for S in P do View(S); Print("\n"); od;
  1(4) U 0(12) U [ -2 ]
  <union of 18 residue classes (mod 72)>
  <union of 78 residue classes (mod 432)>
  <union of 282 residue classes (mod 2592)>
  gap> P2 := AsUnionOfFewClasses(P[2]);
  [ 2(24), 3(24), 18(24), 19(24), 4(36), 28(36), 8(72), 56(72) ]
  gap> Permutation(kappa,P2);
  (1,5,7,2)(3,6,8,4)
  gap> P3 := AsUnionOfFewClasses(P[3]);
  [ 6(48), 7(48), 38(48), 39(48), 10(72), 11(72), 58(72), 59(72), 16(108), 
    88(108), 20(144), 116(144), 32(216), 176(216) ]
  gap> Permutation(kappa,P3);
  (1,5,9,13,6,11,2)(3,7,10,14,8,12,4)
  gap> P4 := AsUnionOfFewClasses(P[4]);
  [ 14(96), 15(96), 78(96), 79(96), 22(144), 23(144), 118(144), 119(144), 
    34(216), 35(216), 178(216), 179(216), 44(288), 236(288), 52(324), 268(324), 
    68(432), 356(432), 104(648), 536(648) ]
  gap> Permutation(kappa,P4);
  (1,5,9,15,19,10,17,6,13,2)(3,7,11,16,20,12,18,8,14,4)
  gap> List(P,S->Set(List(Intersection([1..12^4],S),n->Length(Cycle(kappa,n)))));
  [ [ 1 ], [ 4 ], [ 7 ], [ 10 ] ]
  gap> Set(List(Intersection([1..12^4],Difference(Integers,Union(P))),
  >             n->Length(Cycle(kappa,n))));
  [ 13, 16, 19, 22, 25, 28, 31, 34, 37, 40 ]
  
\end{Verbatim}
 Finally, the permutation \texttt{kappa} should be factored into involutions (this time ``by hand'', for purposes of illustration): 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> elm1 := kappa;
  kappa
  gap> Multpk(elm1,2,1)^elm1;
  8(12)
  gap> Multpk(elm1,2,-1)^elm1;
  4(6)
  gap> fact1 := ClassTransposition(4,6,8,12);;
  
\end{Verbatim}
 \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> elm2 := elm1/fact1;
  <bijective rcwa mapping of Z with modulus 12>
  gap> Display(elm2);
  
  Bijective rcwa mapping of Z with modulus 12
  
                 n mod 12                |                 n^f
  ---------------------------------------+--------------------------------------
     0  1  4  5  9                       | n
     2  6 10                             | 3n + 2
     3  7 11                             | n - 1
     8                                   | (n + 1)/3
  
  gap> Multpk(elm2,3,1)^elm2;
  8(12)
  gap> Multpk(elm2,3,-1)^elm2;
  3(4)
  gap> fact2 := ClassTransposition(3,4,8,12);;
  gap> elm3 := elm2/fact2;
  <bijective rcwa mapping of Z with modulus 4>
  gap> Display(elm3);
  
  Bijective rcwa mapping of Z with modulus 4
  
                  n mod 4                |                 n^f
  ---------------------------------------+--------------------------------------
    0 1                                  | n
    2                                    | n + 1
    3                                    | n - 1
  
  gap> fact3 := ClassTransposition(2,4,3,4);;
  gap> elm4 := elm3/fact3;
  IdentityMapping( Integers )
  gap> kappafacts := [ fact3, fact2, fact1 ];
  [ ClassTransposition(2,4,3,4), ClassTransposition(3,4,8,12),
    ClassTransposition(4,6,8,12) ]
  gap> kappa = Product(kappafacts);
  true
  
\end{Verbatim}
 }

 \pagebreak[4]  
\section{\textcolor{Chapter }{An abelian rcwa group over a polynomial ring}}\label{sec:AbelianModularGroup}
\logpage{[ 5, 7, 0 ]}
\hyperdef{L}{X7A8605E680F664BF}{}
{
  In this section, a wild rcwa group over GF(4)[$x$] should be invstigated, which happens to be abelian. Of course in general,
rcwa groups also over this ring are usually far from being abelian (see
below). We start by defining this group: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> x := Indeterminate(GF(4),1);; SetName(x,"x");
  gap> R := PolynomialRing(GF(4),1);
  GF(2^2)[x]
  gap> e := One(GF(4));;
  gap> p := x^2 + x + e;;    q := x^2 + e;;
  gap> r := x^2 + x + Z(4);; s := x^2 + x + Z(4)^2;;
  gap> cg := List( AllResidues(R,x^2), pol -> [ p, p * pol mod q, q ] );;
  gap> ch := List( AllResidues(R,x^2), pol -> [ r, r * pol mod s, s ] );;
  gap> g := RcwaMapping( R, q, cg );
  <rcwa mapping of GF(2^2)[x] with modulus x^2+Z(2)^0>
  gap> h := RcwaMapping( R, s, ch );
  <rcwa mapping of GF(2^2)[x] with modulus x^2+x+Z(2^2)^2>
  gap> List([g,h],Order);
  [ infinity, infinity ]
  gap> List([g,h],IsTame);
  [ false, false ]
  gap> G := Group(g,h);
  <rcwa group over GF(2^2)[x] with 2 generators>
  gap> IsAbelian(G);
  true
  
\end{Verbatim}
 Now we compute the action of the group \texttt{G} on one of its orbits, and make some statistics of the orbits of \texttt{G} containing polynomials of degree less than{\nobreakspace}4: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> orb := Orbit(G,x^5);
  [ x^5, x^5+x^4+x^2+Z(2)^0, x^5+x^3+x^2+Z(2^2)*x+Z(2)^0, x^5+x^3, 
    x^5+x^4+x^3+x^2+Z(2^2)^2*x+Z(2^2)^2, x^5+x, x^5+x^4+x^3, x^5+x^2+Z(2^2)^2*x,
    x^5+x^4+x^2+x, x^5+x^3+x^2+Z(2^2)^2*x+Z(2)^0, x^5+x^4+Z(2^2)*x+Z(2^2), 
    x^5+x^3+x, x^5+x^4+x^3+x^2+Z(2^2)*x+Z(2^2), x^5+x^4+x^3+x+Z(2)^0, 
    x^5+x^2+Z(2^2)*x, x^5+x^4+Z(2^2)^2*x+Z(2^2)^2 ]
  gap> H := Action(G,orb);
  Group([ (1,2,4,7,6,9,12,14)(3,5,8,11,10,13,15,16), 
    (1,3,6,10)(2,5,9,13)(4,8,12,15)(7,11,14,16) ])
  gap> IsAbelian(H); # check ...
  true
  gap> Exponent(H);
  8
  gap> Collected(List(ShortOrbits(G,AllResidues(R,x^4),100),Length));
  [ [ 1, 4 ], [ 2, 6 ], [ 4, 12 ], [ 8, 24 ] ]
  
\end{Verbatim}
 \pagebreak[4] Changing the generators a little causes the group structure to change a lot: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> cg[1][2] := cg[1][2] + (x^2 + e) * p * q;;
  gap> ch[7][2] := ch[7][2] + x * r * s;;
  gap> g := RcwaMapping( R, q, cg );; h := RcwaMapping( R, s, ch );;
  gap> G := Group(g,h);
  <rcwa group over GF(2^2)[x] with 2 generators>
  gap> orb := Orbit(G,Zero(R));;
  gap> Length(orb);
  87
  gap> Collected(List(orb,DegreeOfLaurentPolynomial));
  [ [ 1, 2 ], [ 2, 4 ], [ 3, 16 ], [ 4, 64 ], [ infinity, 1 ] ]
  gap> H := Action(G,orb);
  <permutation group with 2 generators>
  gap> IsNaturalAlternatingGroup(H);
  true
  gap> orb := Orbit(G,x^6);;
  gap> Length(orb);
  512
  gap> H := Action(G,orb);
  <permutation group with 2 generators>
  gap> IsNaturalSymmetricGroup(H) or IsNaturalAlternatingGroup(H);
  false
  gap> blk := Blocks(H,[1..512]);;
  gap> List(blk,Length);
  [ 128, 128, 128, 128 ]
  gap> Action(H,blk,OnSets);
  Group([ (1,2)(3,4), (1,3)(2,4) ])
  
\end{Verbatim}
 Thus the modified group has a quotient isomorphic to the alternating group of
degree{\nobreakspace}87, and a quotient isomorphic to some wreath product or a
subgroup thereof acting transitively, but not primitively on 512 points. }

  
\section{\textcolor{Chapter }{ A tame group generated by commutators of wild permutations }}\label{sec:TameByCommsOfWildPerms}
\logpage{[ 5, 8, 0 ]}
\hyperdef{L}{X87383623856ED81B}{}
{
  In this section, we have a look at 3 wild rcwa mappings whose commutators
generate tame groups: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> a := RcwaMapping([[3,0,2],[3, 1,4],[3,0,2],[3,-1,4]]);;
  gap> b := RcwaMapping([[3,0,2],[3,13,4],[3,0,2],[3,-1,4]]);;
  gap> c := RcwaMapping([[3,0,2],[3, 1,4],[3,0,2],[3,11,4]]);;
  gap> SetName(a,"a"); SetName(b,"b"); SetName(c,"c");
  gap> List([a,b,c],IsTame);
  [ false, false, false ]
  gap> ab := Comm(a,b);; ac := Comm(a,c);; bc := Comm(b,c);;
  gap> SetName(ab,"[a,b]"); SetName(ac,"[a,c]"); SetName(bc,"[b,c]");
  gap> List([ab,ac,bc],Order);
  [ 6, 6, 12 ]
  
\end{Verbatim}
 Now we would like to have a look at [\mbox{\texttt{\slshape a}},\mbox{\texttt{\slshape b}}] ... 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Display(ab);
  
  Bijective rcwa mapping of Z with modulus 18, of order 6
  
                 n mod 18                |               n^[a,b]
  ---------------------------------------+--------------------------------------
     0  2  3  8  9 11 12 17              | n
     1 10                                | 2n - 5
     4  7 13 16                          | n + 3
     5 14                                | 2n - 4
     6                                   | (n + 2)/2
    15                                   | (n - 5)/2
  
  
\end{Verbatim}
 ... form the group generated by [\mbox{\texttt{\slshape a}},\mbox{\texttt{\slshape b}}] and [\mbox{\texttt{\slshape a}},\mbox{\texttt{\slshape c}}] and compute its action on one of its orbits: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(ab,ac);
  <rcwa group over Z with 2 generators>
  gap> orb := Orbit(G,1);
  [ -15, -12, -7, -6, -5, -4, -3, -2, -1, 1 ]
  gap> H := Action(G,orb);
  Group([ (2,5,8,10,7,6), (1,3,6,9,4,5) ])
  gap> Size(H);
  3628800
  gap> Size(G); # G acts faithfully on orb.
  3628800
  
\end{Verbatim}
 Hence the group \mbox{\texttt{\slshape G}} is isomorphic to the symmetric group on 10{\nobreakspace}points and acts
faithfully on the orbit containing{\nobreakspace}1. Another question is which
groups arise if we take as generators either \mbox{\texttt{\slshape ab}}, \mbox{\texttt{\slshape ac}} or \mbox{\texttt{\slshape bc}} and the involution which maps any integer to its additive inverse: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> t := ClassReflection(0,1);;
  gap> Display(t);
  Bijective rcwa mapping of Z: n -> -n
  gap> G := Group(ab,t);
  <rcwa group over Z with 2 generators>
  gap> Size(G);
  7257600
  gap> phi := IsomorphismPermGroup(G);
  [ [a,b], ClassReflection(0,1) ] -> 
  [ (1,36,12,27,9,15)(2,34,10,25,7,13)(3,35,11,26,8,14), 
    (1,18)(2,17)(3,16)(4,15)(5,14)(6,13)(7,12)(8,11)(9,10)(20,21)(22,36)(23,
      35)(24,34)(25,33)(26,32)(27,31)(28,30) ]
  gap> StructureDescription(Image(phi));
  "C2 x S10"
  
\end{Verbatim}
 Thus the group generated by \mbox{\texttt{\slshape ab}} and \mbox{\texttt{\slshape t}} is isomorphic to ${\rm C}_2 \times {\rm S}_{10}$ . The next group is an extension of a perfect group of
order{\nobreakspace}960: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(ac,t);;
  gap> Size(G);
  3840
  gap> H := Image(IsomorphismPermGroup(G));;
  gap> P := DerivedSubgroup(H);;
  gap> Size(P);
  960
  gap> IsPerfect(P);
  true
  gap> PerfectGroup(PerfectIdentification(P));
  A5 2^4'
  
\end{Verbatim}
 The last group is infinite: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(bc,t);;
  gap> Size(G);
  infinity
  gap> Order(bc*t);
  infinity
  gap> Modulus(G);
  18
  gap> RespectedPartition(G);
  [ 1(9), 2(9), 4(9), 5(9), 7(9), 8(9), 0(18), 3(18), 6(18), 9(18), 12(18),
    15(18) ]
  gap> ActionOnRespectedPartition(G);
  Group([ (1,5,8,2,4,12)(3,9,6,11), (1,6)(2,5)(3,4)(8,12)(9,11) ])
  gap> StructureDescription(last);
  "S10"
  gap> RankOfKernelOfActionOnRespectedPartition(G);
  9
  
\end{Verbatim}
 }

 \pagebreak[4]  
\section{\textcolor{Chapter }{Checking for solvability}}\label{sec:CheckingForSolvability}
\logpage{[ 5, 9, 0 ]}
\hyperdef{L}{X78DFE4B4821E07A6}{}
{
  Is the group generated by the permutations \mbox{\texttt{\slshape a}} and \mbox{\texttt{\slshape b}} from the last paragraph solvable? 

 This group is wild. Presently there is no general method available for testing
wild rcwa groups for solvability. But nevertheless, for the given group we can
obtain a negative answer to this question. The idea is to find a
subgroup{\nobreakspace}\mbox{\texttt{\slshape U}} which acts on a finite set{\nobreakspace}\mbox{\texttt{\slshape S}} of integers, and which induces on{\nobreakspace}\mbox{\texttt{\slshape S}} a non-solvable finite permutation group: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> a := RcwaMapping([[3,0,2],[3, 1,4],[3,0,2],[3,-1,4]]);; SetName(a,"a");
  gap> b := RcwaMapping([[3,0,2],[3,13,4],[3,0,2],[3,-1,4]]);; SetName(b,"b");
  gap> G := Group(a,b);;
  gap> ShortOrbits(Group(Comm(a,b)),[-10..10],100);
  [ [ -10 ], [ -9 ], [ -30, -21, -14, -13, -11, -8 ], [ -7 ], [ -6 ], 
    [ -12, -5, -4, -3, -2, 1 ], [ -1 ], [ 0 ], [ 2 ], [ 3 ], 
    [ 4, 5, 6, 7, 10, 15 ], [ 8 ], [ 9 ] ]
  gap> S := [ 4, 5, 6, 7, 10, 15 ];;
  gap> Cycle(Comm(a,b),4);
  [ 4, 7, 10, 15, 5, 6 ]
  gap> elm := RepresentativeAction(G,S,Permuted(S,(1,4)),OnTuples);
  <bijective rcwa mapping of Z with modulus 81>
  gap> List(S,n->n^elm);
  [ 7, 5, 6, 4, 10, 15 ]
  gap> U := Group(Comm(a,b),elm);
  <rcwa group over Z with 2 generators>
  gap> Action(U,S);
  Group([ (1,4,5,6,2,3), (1,4) ])
  gap> IsNaturalSymmetricGroup(last);
  true
  
\end{Verbatim}
 Thus the subgroup \mbox{\texttt{\slshape U}} induces on \mbox{\texttt{\slshape S}} a natural symmetric group of degree{\nobreakspace}6. Therefore the
group{\nobreakspace}\mbox{\texttt{\slshape G}} is not solvable, as claimed. We conclude this example by factoring the group
element \mbox{\texttt{\slshape elm}} into generators: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> F := FreeGroup("a","b");
  <free group on the generators [ a, b ]>
  gap> RepresentativeActionPreImage(G,S,Permuted(S,(1,4)),OnTuples,F);
  a^-2*b^-2*a*b*a^-1*b*a*b^-2*a
  gap> a^-2*b^-2*a*b*a^-1*b*a*b^-2*a = elm;
  true
  
\end{Verbatim}
 }

 \pagebreak[4]  
\section{\textcolor{Chapter }{Some examples over (semi)localizations of the integers}}\label{sec:LocalExample}
\logpage{[ 5, 10, 0 ]}
\hyperdef{L}{X783D54DC7A646273}{}
{
  We start with something one can observe when trying to ``transfer'' an rcwa mapping from the ring of integers to one of its localizations: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> a2 := LocalizedRcwaMapping(a,2);
  <rcwa mapping of Z_( 2 ) with modulus 4>
  gap> IsSurjective(a2); # As expected
  true
  gap> IsInjective(a2); # Why not??
  false
  gap> 0^a2;
  0
  gap> (1/3)^a2; # That's the reason!
  0
  
\end{Verbatim}
 The above can also be explained easily by pointing out that the modulus of the
inverse of \texttt{a} is 3, and that 3 is a unit of $\Z_{(2)}$. Moving to $\Z_{(2,3)}$ solves this problem: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> a23 := SemilocalizedRcwaMapping(a,[2,3]);
  <rcwa mapping of Z_( 2, 3 ) with modulus 4>
  gap> IsBijective(a23);
  true
  
\end{Verbatim}
 We get additional finite cycles, e.g.: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List(ShortOrbits(Group(a23),[0..50]/5,50),orb->Cycle(a23,orb[1]));
  [ [ 0 ], [ 1/5, 2/5, 3/5 ], 
    [ 4/5, 6/5, 9/5, 8/5, 12/5, 18/5, 27/5, 19/5, 13/5, 11/5, 7/5 ], [ 1 ], 
    [ 2, 3 ], [ 14/5, 21/5, 17/5 ], 
    [ 16/5, 24/5, 36/5, 54/5, 81/5, 62/5, 93/5, 71/5, 52/5, 78/5, 117/5, 89/5, 
        68/5, 102/5, 153/5, 116/5, 174/5, 261/5, 197/5, 149/5, 113/5, 86/5, 
        129/5, 98/5, 147/5, 109/5, 83/5, 61/5, 47/5, 34/5, 51/5, 37/5, 29/5, 
        23/5 ], [ 4, 6, 9, 7, 5 ] ]
  gap> List(last,Length);
  [ 1, 3, 11, 1, 2, 3, 34, 5 ]
  gap> List(ShortOrbits(Group(a23),[0..50]/7,50),orb->Cycle(a23,orb[1]));
  [ [ 0 ], [ -1/7, 1/7 ], [ 2/7, 3/7, 4/7, 6/7, 9/7, 5/7 ], [ 1 ], [ 2, 3 ], 
    [ 4, 6, 9, 7, 5 ] ]
  gap> List(last,Length);
  [ 1, 2, 6, 1, 2, 5 ]
  
\end{Verbatim}
 \pagebreak[4] But the group structure remains invariant under the ``transfer'' of a group with prime set $\{2,3\}$ from $\Z$ to $\Z_{(2,3)}$: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> b23 := SemilocalizedRcwaMapping(b,[2,3]);;
  gap> c23 := SemilocalizedRcwaMapping(c,[2,3]);;
  gap> ab23 := Comm(a23,b23);
  <rcwa mapping of Z_( 2, 3 ) with modulus 18>
  gap> ac23 := Comm(a23,c23);
  <rcwa mapping of Z_( 2, 3 ) with modulus 18>
  gap> G := Group(ab23,ac23);
  <rcwa group over Z_( 2, 3 ) with 2 generators>
  gap> S := Intersection(Enumerator(Rationals){[1..200]},Z_pi([2,3]));
  [ -12, -11, -10, -9, -8, -7, -6, -5, -4, -3, -12/5, -11/5, -2, -9/5, -12/7, 
    -8/5, -11/7, -10/7, -7/5, -9/7, -6/5, -8/7, -12/11, -1, -10/11, -6/7, 
    -9/11, -4/5, -8/11, -5/7, -7/11, -3/5, -4/7, -6/11, -5/11, -3/7, -2/5, 
    -4/11, -2/7, -3/11, -1/5, -2/11, -1/7, -1/11, 0, 1/13, 1/11, 1/7, 2/13, 
    2/11, 1/5, 3/13, 3/11, 2/7, 4/13, 4/11, 5/13, 2/5, 3/7, 5/11, 6/13, 7/13, 
    6/11, 4/7, 3/5, 8/13, 7/11, 9/13, 5/7, 8/11, 10/13, 4/5, 9/11, 11/13, 6/7, 
    10/11, 12/13, 1, 12/11, 8/7, 13/11, 6/5, 9/7, 7/5, 10/7, 11/7, 8/5, 12/7, 
    9/5, 2, 11/5, 12/5, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ]
  gap> orbs := ShortOrbits(G,S,50);;
  gap> List(orbs,Length);
  [ 10, 10, 1, 10, 1, 10, 10, 10, 10, 10, 1, 10, 10, 10, 1, 10, 10, 10, 10, 10, 
    10, 10, 10, 10, 10, 10, 10, 10, 1, 10, 10, 10, 10, 10, 10, 10, 10, 10, 1, 
    10, 1, 10, 10, 10, 1, 1, 10, 1, 10 ]
  gap> ForAll(orbs,orb->IsNaturalSymmetricGroup(Action(G,orb)));
  true
  
\end{Verbatim}
 ``Transferring'' a non-invertible rcwa mapping from the ring of integers to some of its
(semi)localizations can also turn it into an invertible one: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> v := RcwaMapping([[6,0,1],[1,-7,2],[6,0,1],[1,-1,1],
  >                      [6,0,1],[1, 1,2],[6,0,1],[1,-1,1]]);;
  gap> SetName(v,"v");
  gap> Display(v);
  
  Rcwa mapping of Z with modulus 8
  
                  n mod 8                |                 n^v
  ---------------------------------------+--------------------------------------
    0 2 4 6                              | 6n
    1                                    | (n - 7)/2
    3 7                                  | n - 1
    5                                    | (n + 1)/2
  
  
\end{Verbatim}
 \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> IsInjective(v);
  true
  gap> IsSurjective(v);
  false
  gap> Image(v);
  Z \ 4(12) U 8(12)
  gap> Difference(Integers,last);
  4(12) U 8(12)
  gap> v2 := LocalizedRcwaMapping(v,2);
  <rcwa mapping of Z_( 2 ) with modulus 8>
  gap> IsBijective(v2);
  true
  gap> Display(v2^-1);
  
  Bijective rcwa mapping of Z_( 2 ) with modulus 4
  
                  n mod 4                |                 n^f
  ---------------------------------------+--------------------------------------
    0                                    | 1/3 n / 2
    1                                    | 2 n + 7
    2                                    | n + 1
    3                                    | 2 n - 1
  
  gap> S := ResidueClass(Z_pi(2),2,0);; l := [S];;
  gap> for i in [1..10] do Add(l,l[Length(l)]^v2); od;
  gap> l; # Visibly v2 is wild ...
  [ 0(2), 0(4), 0(8), 0(16), 0(32), 0(64), 0(128), 0(256), 0(512), 0(1024), 
    0(2048) ]
  gap> w2 := RcwaMapping(Z_pi(2),[[1,0,2],[2,-1,1],[1,1,1],[2,-1,1]]);;
  gap> v2w2 := Comm(v2,w2);; SetName(v2w2,"[v2,w2]"); v2w2^-1;;
  gap> Display(v2w2);
  
  Bijective rcwa mapping of Z_( 2 ) with modulus 8
  
                  n mod 8                |              n^[v2,w2]
  ---------------------------------------+--------------------------------------
    0 3 4 7                              | n
    1                                    | n + 4
    2 6                                  | 3 n
    5                                    | n - 4
  
  
\end{Verbatim}
 Again, viewed as an rcwa mapping of the integers the commutator given at the
end of the example would not be surjective. }

 \pagebreak[4]  
\section{\textcolor{Chapter }{ Twisting 257-cycles into an rcwa mapping with modulus 32 }}\label{sec:Twisting257CyclesToModulus32}
\logpage{[ 5, 11, 0 ]}
\hyperdef{L}{X846D7D087861E0AC}{}
{
  We define an rcwa mapping \mbox{\texttt{\slshape x}} of order{\nobreakspace}257 with modulus{\nobreakspace}32. The easiest way to
construct such a mapping is to prescribe a transition graph and then to assign
suitable affine mappings to its vertices. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> x := RcwaMapping(
  >           [[ 16,  2,  1], [ 16, 18,  1], [  1, 16,  1], [ 16, 18,  1],
  >            [  1, 16,  1], [ 16, 18,  1], [  1, 16,  1], [ 16, 18,  1],
  >            [  1, 16,  1], [ 16, 18,  1], [  1, 16,  1], [ 16, 18,  1],
  >            [  1, 16,  1], [ 16, 18,  1], [  1, 16,  1], [ 16, 18,  1],
  >            [  1,  0, 16], [ 16, 18,  1], [  1,-14,  1], [ 16, 18,  1],
  >            [  1,-14,  1], [ 16, 18,  1], [  1,-14,  1], [ 16, 18,  1],
  >            [  1,-14,  1], [ 16, 18,  1], [  1,-14,  1], [ 16, 18,  1],
  >            [  1,-14,  1], [ 16, 18,  1], [  1,-14,  1], [  1,-31,  1]]);;
  gap> SetName(x,"x"); Display(x);
  
  Rcwa mapping of Z with modulus 32
  
                 n mod 32                |                 n^x
  ---------------------------------------+--------------------------------------
     0                                   | 16n + 2
     1  3  5  7  9 11 13 15 17 19 21 23  | 
    25 27 29                             | 16n + 18
     2  4  6  8 10 12 14                 | n + 16
    16                                   | n/16
    18 20 22 24 26 28 30                 | n - 14
    31                                   | n - 31
  
  gap> Order(x);
  257
  gap> Cycle(x,[1],0);
  [ 0, 2, 18, 4, 20, 6, 22, 8, 24, 10, 26, 12, 28, 14, 30, 16, 1, 34, 50, 36, 
    52, 38, 54, 40, 56, 42, 58, 44, 60, 46, 62, 48, 3, 66, 82, 68, 84, 70, 86, 
    72, 88, 74, 90, 76, 92, 78, 94, 80, 5, 98, 114, 100, 116, 102, 118, 104, 
    120, 106, 122, 108, 124, 110, 126, 112, 7, 130, 146, 132, 148, 134, 150, 
    136, 152, 138, 154, 140, 156, 142, 158, 144, 9, 162, 178, 164, 180, 166, 
    182, 168, 184, 170, 186, 172, 188, 174, 190, 176, 11, 194, 210, 196, 212, 
    198, 214, 200, 216, 202, 218, 204, 220, 206, 222, 208, 13, 226, 242, 228, 
    244, 230, 246, 232, 248, 234, 250, 236, 252, 238, 254, 240, 15, 258, 274, 
    260, 276, 262, 278, 264, 280, 266, 282, 268, 284, 270, 286, 272, 17, 290, 
    306, 292, 308, 294, 310, 296, 312, 298, 314, 300, 316, 302, 318, 304, 19, 
    322, 338, 324, 340, 326, 342, 328, 344, 330, 346, 332, 348, 334, 350, 336, 
    21, 354, 370, 356, 372, 358, 374, 360, 376, 362, 378, 364, 380, 366, 382, 
    368, 23, 386, 402, 388, 404, 390, 406, 392, 408, 394, 410, 396, 412, 398, 
    414, 400, 25, 418, 434, 420, 436, 422, 438, 424, 440, 426, 442, 428, 444, 
    430, 446, 432, 27, 450, 466, 452, 468, 454, 470, 456, 472, 458, 474, 460, 
    476, 462, 478, 464, 29, 482, 498, 484, 500, 486, 502, 488, 504, 490, 506, 
    492, 508, 494, 510, 496, 31 ]
  gap> Length(last);
  257
  
\end{Verbatim}
 }

 \pagebreak[4]  
\section{\textcolor{Chapter }{ The behaviour of the moduli of powers }}\label{sec:ModuliOfPowers}
\logpage{[ 5, 12, 0 ]}
\hyperdef{L}{X78D5DC93845CA6A0}{}
{
  In this section some examples are given, which illustrate how different the
series of the moduli of powers of a given rcwa mapping of the integers can
look like. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List([0..4],i->Modulus(a^i));
  [ 1, 4, 16, 64, 256 ]
  gap> List([0..6],i->Modulus(ab^i));
  [ 1, 18, 18, 18, 18, 18, 1 ]
  gap> g := RcwaMapping([[2,2,1],[1, 4,1],[1,0,2],[2,2,1],[1,-4,1],[1,-2,1]]);;
  gap> h := RcwaMapping([[2,2,1],[1,-2,1],[1,0,2],[2,2,1],[1,-1,1],[1, 1,1]]);;
  gap> List([0..7],i->Modulus(g^i));
  [ 1, 6, 12, 12, 12, 12, 6, 1 ]
  gap> List([1..20],i->Modulus((g^3*h)^i));
  [ 12, 6, 12, 12, 12, 6, 12, 6, 12, 12, 12, 6, 12, 6, 12, 12, 12, 6, 12, 6 ]
  gap> u := RcwaMapping([[3,0,5],[9,1,5],[3,-1,5],[9,-2,5],[9,4,5]]);;
  gap> List([0..3],i->Modulus(u^i));
  [ 1, 5, 25, 125 ]
  gap> v6 := RcwaMapping([[-1,2,1],[1,-1,1],[1,-1,1]]);;
  gap> List([0..6],i->Modulus(v6^i));
  [ 1, 3, 3, 3, 3, 3, 1 ]
  gap> w8 := RcwaMapping([[-1,3,1],[1,-1,1],[1,-1,1],[1,-1,1]]);;
  gap> List([0..8],i->Modulus(w8^i));
  [ 1, 4, 4, 4, 4, 4, 4, 4, 1 ]
  gap> z := RcwaMapping([[2,  1, 1],[1,  1,1],[2, -1,1],[2, -2,1],
  >                      [1,  6, 2],[1,  1,1],[1, -6,2],[2,  5,1],
  >                      [1,  6, 2],[1,  1,1],[1,  1,1],[2, -5,1],
  >                      [1,  0, 1],[1, -4,1],[1,  0,1],[2,-10,1]]);;
  gap> SetName(z,"z");
  gap> IsBijective(z);
  true
  gap> Display(z);
  
  Bijective rcwa mapping of Z with modulus 16
  
                 n mod 16                |                 n^z
  ---------------------------------------+--------------------------------------
     0                                   | 2n + 1
     1  5  9 10                          | n + 1
     2                                   | 2n - 1
     3                                   | 2n - 2
     4  8                                | (n + 6)/2
     6                                   | (n - 6)/2
     7                                   | 2n + 5
    11                                   | 2n - 5
    12 14                                | n
    13                                   | n - 4
    15                                   | 2n - 10
  
  
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List([0..25],i->Modulus(z^i));
  [ 1, 16, 32, 64, 64, 128, 128, 128, 128, 128, 128, 256, 256, 256, 256, 256, 
    256, 512, 512, 512, 512, 512, 512, 1024, 1024, 1024 ]
  gap> e1 := RcwaMapping([[1,4,1],[2,0,1],[1,0,2],[2,0,1]]);;
  gap> e2 := RcwaMapping([[1,4,1],[2,0,1],[1,0,2],[1,0,1],
  >                       [1,4,1],[2,0,1],[1,0,1],[1,0,1]]);;
  gap> List([e1,e2],Order);
  [ infinity, infinity ]
  gap> List([1..20],i->Modulus(e1^i));
  [ 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4 ]
  gap> List([1..20],i->Modulus(e2^i));
  [ 8, 4, 8, 4, 8, 4, 8, 4, 8, 4, 8, 4, 8, 4, 8, 4, 8, 4, 8, 4 ]
  gap> SetName(e1,"e1"); SetName(e2,"e2");
  gap> Display(e2);
  
  Bijective rcwa mapping of Z with modulus 8, of order infinity
  
                  n mod 8                |                 n^e2
  ---------------------------------------+--------------------------------------
    0 4                                  | n + 4
    1 5                                  | 2n
    2                                    | n/2
    3 6 7                                | n
  
  gap> e2^2 = Restriction(RcwaMapping([[1,2,1]]),RcwaMapping([[4,0,1]]));
  true
  
\end{Verbatim}
 }

  
\section{\textcolor{Chapter }{ Images and preimages under the Collatz mapping }}\label{sec:CollatzImagesAndPreImages}
\logpage{[ 5, 13, 0 ]}
\hyperdef{L}{X855A3CD88459958B}{}
{
  We have a look at the images of the residue class 1(2) under powers of the
Collatz mapping. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> T := RcwaMapping([[1,0,2],[3,1,2]]);; S0 := ResidueClass(Integers,2,1);;
  gap> S1 := S0^T;
  2(3)
  gap> S2 := S1^T;
  1(3) U 8(9)
  gap> S3 := S2^T;
  2(3) U 4(9)
  gap> S4 := S3^T;
  Z \ 0(3) U 5(9)
  gap> S5 := S4^T;
  Z \ 0(3) U 7(9)
  gap> S6 := S5^T;
  Z \ 0(3)
  gap> S7 := S6^T;
  Z \ 0(3)
  
\end{Verbatim}
 Thus the image gets stable after applying the mapping $T$ for the 6th time. Hence $T^6$ maps the residue class 1(2) surjectively onto the union of the residue classes
1(3) and 2(3), which $T$ stabilizes setwise. Now we would like to determine the preimages of 1(3) and
2(3) in 1(2) under $T^6$. The residue class 1(2) has to be the disjoint union of these sets. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> U := Intersection(PreImage(T^6,ResidueClass(Integers,3,1)),S0);
  <union of 11 residue classes (mod 64)>
  gap> V := Intersection(PreImage(T^6,ResidueClass(Integers,3,2)),S0);
  <union of 21 residue classes (mod 64)>
  gap> AsUnionOfFewClasses(U);
  [ 1(64), 5(64), 7(64), 9(64), 21(64), 23(64), 29(64), 31(64), 49(64), 51(64), 
    59(64) ]
  gap> AsUnionOfFewClasses(V);
  [ 3(32), 11(32), 13(32), 15(32), 25(32), 17(64), 19(64), 27(64), 33(64), 
    37(64), 39(64), 41(64), 53(64), 55(64), 61(64), 63(64) ]
  gap> Union(U,V) = S0 and Intersection(U,V) = [];  # consistency check
  true
  
\end{Verbatim}
 The images of the residue class 0(3) under powers of{\nobreakspace}$T$ look as follows: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> S0 := ResidueClass(Integers,3,0);
  0(3)
  gap> S1 := S0^T;
  0(3) U 5(9)
  gap> S2 := S1^T;
  0(3) U 5(9) U 7(9) U 8(27)
  gap> S3 := S2^T;
  <union of 20 residue classes (mod 27)>
  gap> S4 := S3^T;
  <union of 73 residue classes (mod 81)>
  gap> S5 := S4^T;
  Z \ 10(81) U 37(81)
  gap> S6 := S5^T;
  Integers
  gap> S7 := S6^T;
  Integers
  
\end{Verbatim}
 Thus every integer is the image of a multiple of{\nobreakspace}3
under{\nobreakspace}$T^6$. This means that it would be sufficient to prove the $3n+1$ Conjecture for multiples of{\nobreakspace}3. We can obtain the corresponding
result for multiples of{\nobreakspace}5 as follows: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> S := [ResidueClass(Integers,5,0)];
  [ 0(5) ]
  gap> for i in [1..12] do Add(S,S[i]^T); od;
  
\end{Verbatim}
 \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> for s in S do View(s); Print("\n"); od;
  0(5)
  0(5) U 8(15)
  0(5) U 4(15) U 8(15)
  0(5) U 2(15) U 4(15) U 8(15) U 29(45)
  <union of 73 residue classes (mod 135)>
  <union of 244 residue classes (mod 405)>
  <union of 784 residue classes (mod 1215)>
  <union of 824 residue classes (mod 1215)>
  <union of 2593 residue classes (mod 3645)>
  <union of 2647 residue classes (mod 3645)>
  <union of 2665 residue classes (mod 3645)>
  <union of 2671 residue classes (mod 3645)>
  1(3) U 2(3) U 0(15)
  gap> Union(S[13],ResidueClass(Integers,3,0));
  Integers
  gap> List(S,Si->Float(Density(Si)));
  [ 0.2, 0.266667, 0.333333, 0.422222, 0.540741, 0.602469, 0.645267, 0.678189, 
    0.711385, 0.7262, 0.731139, 0.732785, 0.733333 ]
  
\end{Verbatim}
 }

  
\section{\textcolor{Chapter }{ A group which acts 4-transitively on the positive integers }}\label{sec:FourTransitiveGroup}
\logpage{[ 5, 14, 0 ]}
\hyperdef{L}{X7968C1DF7EF0BD8E}{}
{
  In this section, we would like to show that the group $G$ generated by the two wild mappings 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> a := RcwaMapping([[3,0,2],[3,1,4],[3,0,2],[3,-1,4]]);;
  gap> u := RcwaMapping([[3,0,5],[9,1,5],[3,-1,5],[9,-2,5],[9,4,5]]);;
  gap> SetName(a,"a"); SetName(u,"u"); G := Group(a,u);;
  
\end{Verbatim}
 which we have already investigated in earlier examples acts 4-transitively on
the set of positive integers. Obviously, it acts on the set of positive
integers. First we show that this action is transitive. We start by checking
in which residue classes sufficiently large positive integers are mapped to
smaller ones by a suitable group element: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List([a,a^-1,u,u^-1],DecreasingOn);
  [ 1(2), 0(3), 0(5) U 2(5), 2(3) ]
  gap> Union(last);
  Z \ 4(30) U 16(30) U 28(30)
  
\end{Verbatim}
 We see that we cannot always choose such a group element from the set of
generators and their inverses -- otherwise the union would be \texttt{Integers}. \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List([a,a^-1,u,u^-1,a^2,a^-2,u^2,u^-2],DecreasingOn);
  [ 1(2), 0(3), 0(5) U 2(5), 2(3), 1(8) U 7(8), 0(3) U 2(9) U 7(9), 
    0(25) U 12(25) U 17(25) U 20(25), 2(3) U 1(9) U 3(9) ]
  gap> Union(last); # Still not enough ...
  Z \ 4(90) U 58(90) U 76(90)
  gap> List([a,a^-1,u,u^-1,a^2,a^-2,u^2,u^-2,a*u,u*a,(a*u)^-1,(u*a)^-1],
  >         DecreasingOn);
  [ 1(2), 0(3), 0(5) U 2(5), 2(3), 1(8) U 7(8), 0(3) U 2(9) U 7(9), 
    0(25) U 12(25) U 17(25) U 20(25), 2(3) U 1(9) U 3(9), 
    3(5) U 0(10) U 7(20) U 9(20), 0(5) U 2(5), 2(3), 3(9) U 4(9) U 8(9) ]
  gap> Union(last); # ... but that's it!
  Integers
  
\end{Verbatim}
 Finally, we have to deal with ``small'' integers. We use the notation for the coefficients of rcwa mappings introduced
at the beginning of this manual. Let $c_{r(m)} > a_{r(m)}$. Then we easily see that $(a_{r(m)}n+b_{r(m)})/c_{r(m)} > n$ implies $n < b_{r(m)}/(c_{r(m)}-a_{r(m)})$. Thus we can restrict our considerations to integers $n < b_{\rm max}$, where $b_{\rm max}$ is the largest second entry of a coefficient triple of one of the group
elements in our list: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List([a,a^-1,u,u^-1,a^2,a^-2,u^2,u^-2,a*u,u*a,(a*u)^-1,(u*a)^-1],
  >         f->Maximum(List(Coefficients(f),c->c[2])));
  [ 1, 1, 4, 2, 7, 7, 56, 28, 25, 17, 17, 11 ]
  gap> Maximum(last);
  56
  
\end{Verbatim}
 Thus this upper bound is 56. The rest is easy -- all we have to do is to check
that the orbit containing{\nobreakspace}1 contains also all other positive
integers less than or equal to{\nobreakspace}56: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> S := [1];;
  gap> while not IsSubset(S,[1..56]) do
  >      S := Union(S,S^a,S^u,S^(a^-1),S^(u^-1));
  >    od;
  gap> IsSubset(S,[1..56]);
  true
  
\end{Verbatim}
 Checking 2-transitivity is computationally harder, and in the sequel we will
omit some steps which are in practice needed to find out ``what{\nobreakspace}to{\nobreakspace}do''. The approach taken here is to show that the stabilizer of{\nobreakspace}1
in{\nobreakspace}$G$ acts transitively on the set of positive integers greater
than{\nobreakspace}1. We do this by similar means as used above for showing
the transitivity of the action of $G$ on the positive integers. We start by determining all products of at most 5
generators and their inverses, which stabilize{\nobreakspace}1 (taking at most
4-generator products would not suffice!): \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> gens := [a,u,a^-1,u^-1];;
  gap> tups := Concatenation(List([1..5],k->Tuples([1..4],k)));;
  gap> Length(tups);
  1364
  gap> tups := Filtered(tups,tup->ForAll([[1,3],[3,1],[2,4],[4,2]],
  >                                      l->PositionSublist(tup,l)=fail));;
  gap> Length(tups);
  484
  gap> stab := [];;
  gap> for tup in tups do
  >      n := 1;
  >      for i in tup do n := n^gens[i]; od;
  >      if n = 1 then Add(stab,tup); fi;
  >    od;
  gap> Length(stab);
  118
  gap> stabelm := List(stab,tup->Product(List(tup,i->gens[i])));;
  gap> ForAll(stabelm,elm->1^elm=1); # Check.
  true
  
\end{Verbatim}
 The resulting products have various different not quite small moduli: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List(stabelm,Modulus);
  [ 4, 3, 16, 25, 9, 81, 64, 100, 108, 100, 25, 75, 27, 243, 324, 243, 256, 
    400, 144, 400, 100, 432, 324, 400, 80, 400, 625, 25, 75, 135, 150, 75, 225, 
    81, 729, 486, 729, 144, 144, 81, 729, 1296, 729, 6561, 1024, 1600, 192, 
    1600, 400, 576, 432, 1600, 320, 1600, 2500, 100, 100, 180, 192, 192, 108, 
    972, 1728, 972, 8748, 1600, 400, 320, 80, 1600, 2500, 300, 2500, 625, 625, 
    75, 675, 75, 75, 135, 405, 600, 120, 600, 1875, 75, 225, 405, 225, 225, 
    675, 243, 2187, 729, 2187, 216, 216, 243, 2187, 1944, 2187, 19683, 576, 
    144, 576, 432, 81, 81, 729, 2187, 5184, 324, 8748, 243, 2187, 19683, 26244, 
    19683 ]
  gap> Lcm(last);
  12597120000
  gap> Collected(Factors(last));
  [ [ 2, 10 ], [ 3, 9 ], [ 5, 4 ] ]
  
\end{Verbatim}
 Similar as before, we determine for any of the above mappings the residue
classes whose elements larger than the largest $b_{r(m)}$ - coefficient of the respective mapping are mapped to smaller integers: \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> decs := List(stabelm,DecreasingOn);;
  gap> List(decs,Modulus);
  [ 2, 3, 8, 25, 9, 9, 16, 100, 12, 50, 25, 75, 27, 81, 54, 81, 64, 400, 48, 
    200, 100, 72, 108, 400, 80, 200, 625, 25, 75, 45, 75, 75, 225, 81, 243, 81, 
    243, 144, 144, 81, 243, 216, 243, 243, 128, 1600, 64, 400, 400, 48, 144, 
    1600, 320, 400, 2500, 100, 100, 60, 96, 192, 108, 324, 144, 324, 972, 400, 
    400, 80, 80, 400, 2500, 100, 1250, 625, 625, 25, 75, 75, 75, 45, 135, 600, 
    120, 150, 1875, 75, 225, 135, 225, 225, 675, 243, 729, 243, 729, 108, 216, 
    243, 729, 162, 729, 2187, 144, 144, 144, 144, 81, 81, 243, 729, 1296, 324, 
    972, 243, 729, 2187, 1458, 2187 ]
  gap> Lcm(last);
  174960000
  
\end{Verbatim}
 Since the least common multiple of the moduli of these unions of residue
classes is as large as 174960000, directly forming their union and checking
whether it is equal to the set of integers would take relatively much time and
memory. However, starting with the set of integers and subtracting the above
sets one-by-one in a suitably chosen order is cheap: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> SortParallel(decs,stabelm,
  >                 function(S1,S2)
  >                   return First([1..100],k->Factorial(k) mod Modulus(S1) = 0)
  >                        < First([1..100],k->Factorial(k) mod Modulus(S2) = 0);
  >                 end);
  gap> S := Integers;;
  gap> for i in [1..Length(decs)] do
  >      S_old := S; S := Difference(S,decs[i]);
  >      if S <> S_old then ViewObj(S); Print("\n"); fi;
  >      if S = [] then maxind := i; break; fi;
  >    od;
  0(2)
  2(6) U 4(6)
  <union of 8 residue classes (mod 30)>
  <union of 19 residue classes (mod 90)>
  <union of 114 residue classes (mod 720)>
  <union of 99 residue classes (mod 720)>
  <union of 57 residue classes (mod 720)>
  <union of 54 residue classes (mod 720)>
  <union of 41 residue classes (mod 720)>
  <union of 35 residue classes (mod 720)>
  <union of 8 residue classes (mod 720)>
  4(720) U 94(720) U 148(720) U 238(720)
  <union of 24 residue classes (mod 5760)>
  <union of 72 residue classes (mod 51840)>
  <union of 48 residue classes (mod 51840)>
  <union of 192 residue classes (mod 259200)>
  <union of 168 residue classes (mod 259200)>
  <union of 120 residue classes (mod 259200)>
  <union of 96 residue classes (mod 259200)>
  <union of 72 residue classes (mod 259200)>
  <union of 60 residue classes (mod 259200)>
  <union of 48 residue classes (mod 259200)>
  <union of 24 residue classes (mod 259200)>
  <union of 12 residue classes (mod 259200)>
  <union of 24 residue classes (mod 777600)>
  <union of 12 residue classes (mod 777600)>
  111604(194400) U 14404(777600) U 208804(777600)
  [  ]
  
\end{Verbatim}
 Similar as above, it remains to check that the ``small'' integers all lie in the orbit containing{\nobreakspace}2. Obviously, it is
sufficient to check that any integer greater than{\nobreakspace}2 is mapped to
a smaller one by some suitably chosen element of the stabilizer under
consideration: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Maximum(List(stabelm{[1..maxind]},
  >                 f->Maximum(List(Coefficients(f),c->c[2]))));
  6581
  gap> Filtered([3..6581],n->Minimum(List(stabelm,elm->n^elm))>=n);
  [ 4 ]
  
\end{Verbatim}
 We have to treat 4 separately: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> 1^(u*a*u^2*a^-1*u);
  1
  gap> 4^(u*a*u^2*a^-1*u);
  3
  
\end{Verbatim}
 Now we know that any positive integer greater than{\nobreakspace}1 lies in the
same orbit under the action of the stabilizer of{\nobreakspace}1
in{\nobreakspace}$G$ as{\nobreakspace}2, thus that this stabilizer acts transitively on $\N \setminus \{1\}$. But this means that we have established the 2-transitivity of the action of $G$ on{\nobreakspace}$\N$. 

 In the following, we essentially repeat the above steps to show that this
action is indeed 3-transitive: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> tups := Concatenation(List([1..6],k->Tuples([1..4],k)));;
  gap> tups := Filtered(tups,tup->ForAll([[1,3],[3,1],[2,4],[4,2]],
  >                                      l->PositionSublist(tup,l)=fail));;
  gap> stab := [];;
  gap> for tup in tups do
  >      l := [1,2];
  >      for i in tup do l := List(l,n->n^gens[i]); od;
  >      if l = [1,2] then Add(stab,tup); fi;
  >    od;
  gap> Length(stab);
  212
  
\end{Verbatim}
 \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> stabelm := List(stab,tup->Product(List(tup,i->gens[i])));;
  gap> decs := List(stabelm,DecreasingOn);;
  gap> SortParallel(decs,stabelm,
  >      function(S1,S2) return First([1..100],k->Factorial(k) mod Modulus(S1) = 0)
  >                           < First([1..100],k->Factorial(k) mod Modulus(S2) = 0);
  >      end);
  gap> S := Integers;;
  gap> for i in [1..Length(decs)] do
  >      S_old := S; S := Difference(S,decs[i]);
  >      if S <> S_old then ViewObj(S); Print("\n"); fi;
  >      if S = [] then break; fi;
  >    od;
  Z \ 1(8) U 7(8)
  <union of 151 residue classes (mod 240)>
  <union of 208 residue classes (mod 720)>
  <union of 51 residue classes (mod 720)>
  <union of 45 residue classes (mod 720)>
  <union of 39 residue classes (mod 720)>
  <union of 33 residue classes (mod 720)>
  <union of 23 residue classes (mod 720)>
  <union of 19 residue classes (mod 720)>
  <union of 17 residue classes (mod 720)>
  <union of 16 residue classes (mod 720)>
  <union of 14 residue classes (mod 720)>
  <union of 8 residue classes (mod 720)>
  <union of 7 residue classes (mod 720)>
  238(360) U 4(720) U 148(720) U 454(720)
  <union of 38 residue classes (mod 5760)>
  <union of 37 residue classes (mod 5760)>
  <union of 25 residue classes (mod 5760)>
  <union of 21 residue classes (mod 5760)>
  <union of 17 residue classes (mod 5760)>
  <union of 16 residue classes (mod 5760)>
  <union of 138 residue classes (mod 51840)>
  <union of 48 residue classes (mod 51840)>
  <union of 32 residue classes (mod 51840)>
  <union of 20 residue classes (mod 51840)>
  <union of 16 residue classes (mod 51840)>
  <union of 68 residue classes (mod 259200)>
  <union of 42 residue classes (mod 259200)>
  <union of 32 residue classes (mod 259200)>
  <union of 26 residue classes (mod 259200)>
  <union of 25 residue classes (mod 259200)>
  <union of 11 residue classes (mod 259200)>
  <union of 10 residue classes (mod 259200)>
  <union of 7 residue classes (mod 259200)>
  13414(129600) U 2164(259200) U 66964(259200) U 228964(259200)
  2164(259200) U 66964(259200) U 228964(259200)
  [  ]
  
\end{Verbatim}
 \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Maximum(List(stabelm,f->Maximum(List(Coefficients(f),c->c[2]))));
  515816
  gap> smallnum := [4..515816];;
  gap> for i in [1..Length(stabelm)] do
  >      smallnum := Filtered(smallnum,n->n^stabelm[i]>=n);
  >    od;
  gap> smallnum;
  [  ]
  
\end{Verbatim}
 The same for 4-transitivity: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> tups := Concatenation(List([1..8],k->Tuples([1..4],k)));;
  gap> tups := Filtered(tups,tup->ForAll([[1,3],[3,1],[2,4],[4,2]],
  >                                      l->PositionSublist(tup,l)=fail));;
  gap> stab := [];;
  gap> for tup in tups do
  >      l := [1,2,3];
  >      for i in tup do l := List(l,n->n^gens[i]); od;
  >      if l = [1,2,3] then Add(stab,tup); fi;
  >    od;
  gap> Length(stab);
  528
  gap> stabelm := [];;
  gap> for i in [1..Length(stab)] do
  >      elm := One(G);
  >      for j in stab[i] do
  >        if Modulus(elm) > 10000 then elm := fail; break; fi;
  >        elm := elm * gens[j];
  >      od;
  >      if elm <> fail then Add(stabelm,elm); fi;
  >    od;
  gap> Length(stabelm);
  334
  gap> decs := List(stabelm,DecreasingOn);;
  gap> SortParallel(decs,stabelm,
  >                 function(S1,S2)
  >                   return First([1..100],k->Factorial(k) mod Modulus(S1) = 0)
  >                        < First([1..100],k->Factorial(k) mod Modulus(S2) = 0);
  >                 end);
  
\end{Verbatim}
 \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> S := Integers;;
  gap> for i in [1..Length(decs)] do
  >      S_old := S; S := Difference(S,decs[i]);
  >      if S <> S_old then ViewObj(S); Print("\n"); fi;
  >      if S = [] then maxind := i; break; fi;
  >    od;
  Z \ 1(8) U 7(8)
  <union of 46 residue classes (mod 72)>
  <union of 20 residue classes (mod 72)>
  4(18)
  <union of 28 residue classes (mod 576)>
  <union of 22 residue classes (mod 576)>
  <union of 21 residue classes (mod 576)>
  40(72) U 4(144) U 94(144) U 346(576) U 418(576)
  <union of 16 residue classes (mod 576)>
  <union of 15 residue classes (mod 576)>
  4(144) U 94(144) U 346(576) U 418(576)
  <union of 30 residue classes (mod 5184)>
  <union of 26 residue classes (mod 5184)>
  <union of 6 residue classes (mod 1296)>
  <union of 504 residue classes (mod 129600)>
  <union of 324 residue classes (mod 129600)>
  <union of 282 residue classes (mod 129600)>
  <union of 239 residue classes (mod 129600)>
  <union of 218 residue classes (mod 129600)>
  <union of 194 residue classes (mod 129600)>
  <union of 154 residue classes (mod 129600)>
  <union of 97 residue classes (mod 129600)>
  <union of 85 residue classes (mod 129600)>
  <union of 77 residue classes (mod 129600)>
  <union of 67 residue classes (mod 129600)>
  <union of 125 residue classes (mod 259200)>
  <union of 108 residue classes (mod 259200)>
  <union of 107 residue classes (mod 259200)>
  <union of 101 residue classes (mod 259200)>
  <union of 100 residue classes (mod 259200)>
  <union of 84 residue classes (mod 259200)>
  <union of 80 residue classes (mod 259200)>
  <union of 76 residue classes (mod 259200)>
  <union of 70 residue classes (mod 259200)>
  <union of 66 residue classes (mod 259200)>
  <union of 54 residue classes (mod 259200)>
  <union of 53 residue classes (mod 259200)>
  <union of 47 residue classes (mod 259200)>
  <union of 43 residue classes (mod 259200)>
  <union of 31 residue classes (mod 259200)>
  <union of 24 residue classes (mod 259200)>
  <union of 23 residue classes (mod 259200)>
  <union of 13 residue classes (mod 259200)>
  57406(129600) U 115006(129600) U 192676(259200) U 250276(259200)
  57406(129600) U 192676(259200) U 250276(259200) U 374206(388800)
  57406(129600) U 192676(259200) U 250276(259200)
  250276(259200) U 57406(388800) U 316606(388800) U 451876(777600)
  316606(388800) U 451876(777600) U 509476(777600) U 768676(777600)
  <union of 18 residue classes (mod 3110400)>
  451876(777600) U 509476(777600) U 705406(777600) U 768676(777600) U 2649406(
  3110400)
  451876(777600) U 705406(777600) U 768676(777600) U 2649406(3110400)
  451876(777600) U 705406(777600) U 2649406(3110400)
  705406(777600) U 2007076(3110400) U 2649406(3110400) U 2784676(3110400)
  <union of 14 residue classes (mod 9331200)>
  2260606(2332800) U 5759806(9331200) U 5895076(9331200) U 8227876(9331200)
  4593406(6998400) U 15091006(27993600) U 17559076(27993600) U 24557476(
  27993600)
  <union of 14 residue classes (mod 83980800)>
  18590206(20995200) U 24557476(83980800) U 45552676(83980800) U 71078206(
  83980800)
  [  ]
  gap> Maximum(List(stabelm{[1..maxind]},
  >                 f->Maximum(List(Coefficients(f),c->c[2]))));
  58975
  gap> smallnum := [5..58975];;
  gap> for i in [1..maxind] do
  >      smallnum := Filtered(smallnum,n->n^stabelm[i]>=n);
  >    od;
  gap> smallnum;
  [  ]
  
\end{Verbatim}
 There is even some evidence that the degree of transitivity of the action of $G$ on the positive integers is higher than{\nobreakspace}4: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> phi := EpimorphismFromFreeGroup(G);
  [ a, u ] -> [ a, u ]
  gap> F := Source(phi);
  <free group on the generators [ a, u ]>
  gap> words := List([5..20],
  >                  n->RepresentativeActionPreImage(G,[1,2,3,4,5],
  >                                                    [1,2,3,4,n],OnTuples,F));
  [ <identity ...>, a^-3*u^4*a*u^-2*a^2, a^-2*u*a^-1*u*a^-1*u*a^-1*u*a^-1*u^-1*a
      , a^4*u^-2*a^-4, a^-1*u^-4*a, u^2*a^-1*u^2*a^-1*u^-2, u^-2*a^-2*u^4, 
    a^-1*u^2*a, a^-1*u^-6*a, a^2*u^4*a^2*u^2, u^-4*a*u^-2*a^-3, 
    a^-1*u^-2*a^-3*u^4*a^2, a^3*u^2*a*u^2, a*u^-4*a*u^-4*a^-2, 
    u^-2*a*u^2*a*u^-2, u^-4*a^2*u^2 ]
  
\end{Verbatim}
 \pagebreak[4] }

  
\section{\textcolor{Chapter }{ A group which acts 3-transitively, but not 4-transitively on Z }}\label{sec:ThreeButNotFourTransitiveGroup}
\logpage{[ 5, 15, 0 ]}
\hyperdef{L}{X87E7FCE27EACDA38}{}
{
  In this section, we would like to show that the wild group $G$ generated by the two tame mappings $n \mapsto n + 1$ and $\tau_{1(2),0(4)}$ acts 3-transitively, but not 4-transitively on the set of integers. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(ClassShift(0,1),ClassTransposition(1,2,0,4));
  <rcwa group over Z with 2 generators>
  gap> IsTame(G);
  false
  gap> (G.1^-2*G.2)^3*(G.1^2*G.2)^3; # G is not the free product C_infty * C_2. 
  IdentityMapping( Integers )
  gap> Display(G);
  
  Wild rcwa group over Z, generated by
  
  [
  Tame bijective rcwa mapping of Z: n -> n + 1
  
  Bijective rcwa mapping of Z with modulus 4, of order 2
  
                  n mod 4                |    n^ClassTransposition(1,2,0,4)
  ---------------------------------------+--------------------------------------
    0                                    | (n + 2)/2
    1 3                                  | 2n - 2
    2                                    | n
  
  ]
  
  
\end{Verbatim}
 This group acts transitively on $\Z$, since already the cyclic group generated by the first of the two generators
does so. Next we have to show that it acts 2-transitively. We essentially
proceed as in the example in the previous section, by checking that the
stabilizer of{\nobreakspace}0 acts transitively on $\Z \setminus \{0\}$. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> gens := [ClassShift(0,1)^-1,ClassTransposition(1,2,0,4),ClassShift(0,1)];;
  gap> tups := Concatenation(List([1..6],k->Tuples([-1,0,1],k)));;
  gap> tups := Filtered(tups,tup->ForAll([[0,0],[-1,1],[1,-1]],
  >                                      l->PositionSublist(tup,l)=fail));;
  gap> Length(tups);
  189
  gap> stab := [];;
  gap> for tup in tups do
  >      n := 0;
  >      for i in tup do n := n^gens[i+2]; od;
  >      if n = 0 then Add(stab,tup); fi;
  >    od;
  gap> stabelm := List(stab,tup->Product(List(tup,i->gens[i+2])));;
  gap> Collected(List(stabelm,Modulus));
  [ [ 4, 6 ], [ 8, 4 ], [ 16, 3 ] ]
  
\end{Verbatim}
 \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> decs := List(stabelm,DecreasingOn);
  [ 0(4), 3(4), 0(4), 3(4), 2(4), 0(4), 4(8), 2(4), 2(4), 0(4), 1(4), 0(8), 
    3(8) ]
  gap> Union(decs);
  Integers
  
\end{Verbatim}
 Similar as in the previous section, it remains to check that the integers with ``small'' absolute value all lie in the orbit containing{\nobreakspace}1 under the
action of the stabilizer of{\nobreakspace}0: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Maximum(List(stabelm,f->Maximum(List(Coefficients(f),c->AbsInt(c[2])))));
  21
  gap> S := [1];;
  gap> for elm in stabelm do S := Union(S,S^elm,S^(elm^-1)); od;
  gap> IsSubset(S,Difference([-21..21],[0])); # Not yet ..
  false
  gap> for elm in stabelm do S := Union(S,S^elm,S^(elm^-1)); od;
  gap> IsSubset(S,Difference([-21..21],[0])); # ... but now!
  true
  
\end{Verbatim}
 Now we have to check for 3-transitivity. Since we cannot find for every
residue class an element of the pointwise stabilizer of $\{0,1\}$ which properly divides its elements, we also have to take additions and
subtractions into consideration. Since the moduli of all of our stabilizer
elements are quite small, simply looking at sets of representatives is cheap: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> tups := Concatenation(List([1..10],k->Tuples([-1,0,1],k)));;
  gap> tups := Filtered(tups,tup->ForAll([[0,0],[-1,1],[1,-1]],
  >                                      l->PositionSublist(tup,l)=fail));;
  gap> Length(tups);
  3069
  gap> stab := [];
  [  ]
  gap> for tup in tups do
  >      l := [0,1];
  >      for i in tup do l := List(l,n->n^gens[i+2]); od;
  >      if l = [0,1] then Add(stab,tup); fi;
  >    od;
  gap> Length(stab);
  10
  gap> stabelm := List(stab,tup->Product(List(tup,i->gens[i+2])));;
  gap> Maximum(List(stabelm,Modulus));
  8
  gap> Maximum(List(stabelm,f->Maximum(List(Coefficients(f),c->AbsInt(c[2])))));
  8
  
\end{Verbatim}
 \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> decsp := List(stabelm,elm->Filtered([9..16],n->n^elm<n));
  [ [ 9, 13 ], [ 10, 12, 14, 16 ], [ 12, 16 ], [ 9, 13 ], [ 12, 16 ], 
    [ 9, 11, 13, 15 ], [ 9, 11, 13, 15 ], [ 12, 16 ], [ 12, 16 ], 
    [ 9, 11, 13, 15 ] ]
  gap> Union(decsp);
  [ 9, 10, 11, 12, 13, 14, 15, 16 ]
  gap> decsm := List(stabelm,elm->Filtered([-16..-9],n->n^elm>n));
  [ [ -15, -13, -11, -9 ], [ -16, -12 ], [ -16, -12 ], [ -15, -11 ], 
    [ -16, -14, -12, -10 ], [ -15, -11 ], [ -15, -11 ], [ -16, -14, -12, -10 ], 
    [ -16, -14, -12, -10 ], [ -15, -11 ] ]
  gap> Union(decsm);
  [ -16, -15, -14, -13, -12, -11, -10, -9 ]
  gap> S := [2];;
  gap> for elm in stabelm do S := Union(S,S^elm,S^(elm^-1)); od;
  gap> IsSubset(S,Difference([-8..8],[0,1]));
  true
  
\end{Verbatim}
 At this point we have established 3-transitivity. It remains to check that the
group $G$ does not act 4-transitively. We do this by checking that it is not transitive
on 4-tuples (mod{\nobreakspace}4). Since $n${\nobreakspace}mod{\nobreakspace}8 determines the image of $n$ under a generator of $G$ (mod{\nobreakspace}4), it suffices to compute (mod{\nobreakspace}8): 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> orb := [[0,1,2,3]];;
  gap> extend := function ()
  >      local gen;
  >      for gen in gens do
  >        orb := Union(orb,List(orb,l->List(l,n->n^gen) mod 8));
  >      od;
  >    end;;
  gap> repeat
  >      old := ShallowCopy(orb);
  >      extend(); Print(Length(orb),"\n");
  >    until orb = old;
  7
  27
  97
  279
  573
  916
  1185
  1313
  1341
  1344
  1344
  gap> Length(Set(List(orb,l->l mod 4)));
  120
  gap> last < 4^4;
  true
  
\end{Verbatim}
 This shows that $G$ is not 4-transitive on $\Z$. The corresponding calculation for 3-tuples looks as follows: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> orb := [[0,1,2]];;
  gap> repeat
  >      old := ShallowCopy(orb);
  >      extend(); Print(Length(orb),"\n");
  >    until orb = old;
  7
  27
  84
  207
  363
  459
  503
  512
  512
  gap> Length(Set(List(orb,l->l mod 4)));
  64
  gap> last = 4^3;
  true
  
\end{Verbatim}
 Needless to say that the latter kind of argumentation is not suitable for
proving, but only for disproving $k$-transitivity. }

  
\section{\textcolor{Chapter }{ Grigorchuk groups }}\label{sec:GrigorchukGroups}
\logpage{[ 5, 16, 0 ]}
\hyperdef{L}{X85DD5E9C7878CAE3}{}
{
  In this section, we show how to construct finite quotients of the two infinite
periodic groups introduced by Rostislav Grigorchuk in{\nobreakspace}\cite{Grigorchuk80} with the help of \textsf{RCWA}. The first of these, nowadays known as ``Grigorchuk group'', is investigated in an example given on the \textsf{GAP} website -- see \href{http://www.gap-system.org/Doc/Examples/grigorchuk.html} {\texttt{http://www.gap-system.org/Doc/Examples/grigorchuk.html}}. The \textsf{RCWA} package permits a simpler and more elegant construction of the finite
quotients of this group: The function \texttt{TopElement} given on the mentioned webpage gets unnecessary, and the function \texttt{SequenceElement} can be simplified as follows: 
\begin{Verbatim}[fontsize=\small,frame=single,label=]
  
  SequenceElement := function ( r, level )
  
    return Permutation(Product(Filtered([1..level-1],k->k mod 3 <> r),
                               k->ClassTransposition(    2^(k-1)-1, 2^(k+1),
                                                     2^k+2^(k-1)-1, 2^(k+1))),
                       [0..2^level-1]);
  end;
  
\end{Verbatim}
 \pagebreak[4] The actual constructors for the generators are modified as follows: 
\begin{Verbatim}[fontsize=\small,frame=single,label=]
  
  a := level -> Permutation(ClassTransposition(0,2,1,2),[0..2^level-1]);
  b := level -> SequenceElement(0,level);
  c := level -> SequenceElement(2,level);
  d := level -> SequenceElement(1,level);
  
\end{Verbatim}
 All computations given on the webpage can now be done just as with the ``original'' construction of the quotients of the Grigorchuk group. In the sequel, we
construct finite quotients of the second group introduced in{\nobreakspace}\cite{Grigorchuk80}: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> FourCycle := RcwaMapping((4,5,6,7),[4..7]);
  <bijective rcwa mapping of Z with modulus 4, of order 4>
  gap> GrigorchukGroup2Generator := function ( level )
  >      if level = 1 then return FourCycle; else
  >        return   Restriction(FourCycle, RcwaMapping([[4,1,1]]))
  >               * Restriction(FourCycle, RcwaMapping([[4,3,1]]))
  >               * Restriction(GrigorchukGroup2Generator(level-1),
  >                             RcwaMapping([[4,0,1]]));
  >      fi;
  >    end;;
  gap> GrigorchukGroup2 := level -> Group(FourCycle,
  >                                       GrigorchukGroup2Generator(level));;
  
\end{Verbatim}
 We can do similar things as shown in the example on the \textsf{GAP} webpage for the ``first'' Grigorchuk group: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := List([1..4],lev->GrigorchukGroup2(lev)); # The first 4 quotients.
  [ <rcwa group over Z with 2 generators>, <rcwa group over Z with 2 generators>
      , <rcwa group over Z with 2 generators>, 
    <rcwa group over Z with 2 generators> ]
  gap> H := List([1..4],lev->Action(G[lev],[0..4^lev-1])); # Isomorphic perm.-gps.
  [ Group([ (1,2,3,4), (1,2,3,4) ]), 
    Group([ (1,2,3,4)(5,6,7,8)(9,10,11,12)(13,14,15,16), 
        (1,5,9,13)(2,6,10,14)(4,8,12,16) ]), 
    <permutation group with 2 generators>, 
    <permutation group with 2 generators> ]
  gap> List(H,Size);
  [ 4, 1024, 4294967296, 1329227995784915872903807060280344576 ]
  gap> List(last,n->Collected(Factors(n)));
  [ [ [ 2, 2 ] ], [ [ 2, 10 ] ], [ [ 2, 32 ] ], [ [ 2, 120 ] ] ]
  gap> List(H,NilpotencyClassOfGroup);      
  [ 1, 6, 14, 40 ]
  
\end{Verbatim}
 }

  
\section{\textcolor{Chapter }{ Forward orbits of a monoid with 2 generators }}\label{sec:ForwardOrbit}
\logpage{[ 5, 17, 0 ]}
\hyperdef{L}{X7DD9502F80364631}{}
{
  The $3n+1$ Conjecture asserts that the forward orbit of any positive integer under the
Collatz mapping $T$ contains{\nobreakspace}1. In contrast, it seems likely that ``most'' trajectories of the two mappings  
\[ T_5^\pm: \ \Z \longrightarrow \Z, \ \ \ \ n \ \longmapsto \ \begin{cases}
\frac{n}{2} & \text{if} \ n \ \text{even}, \\ \frac{5n \pm 1}{2} & \text{if} \
n \ \text{odd} \end{cases} \]
    diverge. However we can show by means of computation that the forward orbit of
any positive integer under the action of the monoid generated by the two
mappings $T_5^-$ and{\nobreakspace}$T_5^+$ indeed contains{\nobreakspace}1. First of all, we enter the generators: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> T5m := RcwaMapping([[1,0,2],[5,-1,2]]);;
  gap> T5p := RcwaMapping([[1,0,2],[5, 1,2]]);;
  
\end{Verbatim}
 We look for a number $k$ such that for any residue class $r(2^k)$ there is a product{\nobreakspace}$f$ of $k${\nobreakspace}mappings $T_5^\pm$ whose restriction to $r(2^k)$ is given by $n \mapsto (an+b)/c$ where $c>a$: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> k := 1;;
  gap> repeat
  >      maps := List(Tuples([T5m,T5p],k),Product);
  >      decr := List(maps,DecreasingOn);
  >      decreasable := Union(decr);
  >      Print(k,": "); View(decreasable); Print("\n");
  >      k := k + 1;
  >    until decreasable = Integers;
  1: 0(2)
  2: 0(4)
  3: Z \ 1(8) U 7(8)
  4: 0(4) U 3(16) U 6(16) U 10(16) U 13(16)
  5: Z \ 7(32) U 25(32)
  6: <union of 48 residue classes (mod 64)>
  7: Integers
  
\end{Verbatim}
 Thus $k=7$ serves our purposes. To be sure that for any positive integer $n$ our monoid contains a mapping $f$ such that $n^f<n$, we still need to check this condition for ``small''{\nobreakspace}$n$. Since in case $c>a$ we have $(an+b)/c \geq n$ if only if $n \leq b/(c-a)$, we only need to check those $n$ which are not larger than the largest coefficient $b_{r(m)}$ occuring in any of the products under consideration: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> maxb := Maximum(List(maps,f->Maximum(List(Coefficients(f),t->t[2]))));
  25999
  gap> small := Filtered([1..maxb],n->ForAll(maps,f->n^f>=n));
  [ 1, 7, 9, 11 ]
  
\end{Verbatim}
 This means that except of{\nobreakspace}1, only for $n \in \{{7,9,11\}}$ there is no product of 7 mappings $T_5^\pm$ which maps $n$ to a smaller integer. We check that also the forward orbits of these three
integers contain{\nobreakspace}1 by successively computing preimages
of{\nobreakspace}1: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> S := [1];; k := 0;;
  gap> repeat
  >      S := Union(S,PreImage(T5m,S),PreImage(T5p,S));
  >      k := k+1;
  >    until IsSubset(S,small);
  gap> k;
  17
  
\end{Verbatim}
 }

  
\section{\textcolor{Chapter }{ Representations of the free group of rank 2 }}\label{sec:FreeGroup}
\logpage{[ 5, 18, 0 ]}
\hyperdef{L}{X81407BD58648D206}{}
{
  The free group of rank{\nobreakspace}2 embeds in RCWA($\Z$) -- in fact it embeds even in the subgroup which is generated by all class
transpositions. An explicit embedding can be constructed by transferring the
construction of the so-called ``Schottky groups'' (cp.{\nobreakspace}\cite{LaHarpe00}, page{\nobreakspace}27) from PSL(2,$\C$) to RCWA($\Z$) (we use the notation from the cited book): 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> D := AllResidueClassesModulo(4);
  [ 0(4), 1(4), 2(4), 3(4) ]
  gap> gamma1 := RepresentativeAction(RCWA(Integers),Difference(Integers,D[1]),D[2]);;
  gap> gamma2 := RepresentativeAction(RCWA(Integers),Difference(Integers,D[3]),D[4]);;
  gap> F2 := Group(gamma1,gamma2);
  <rcwa group over Z with 2 generators>
  
\end{Verbatim}
 We can do some checks: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> X1 := Union(D{[1,2]});; X2 := Union(D{[3,4]});;
  gap>     IsSubset(X1,X2^gamma1) and IsSubset(X1,X2^(gamma1^-1))
  >    and IsSubset(X2,X1^gamma2) and IsSubset(X2,X1^(gamma2^-1));
  true
  
\end{Verbatim}
 The generators are products of 3 class transpositions, each: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Factorization(gamma1);
  [ ClassTransposition(0,2,1,2), ClassTransposition(3,4,5,8),
    ClassTransposition(0,2,1,8) ]
  gap> Factorization(gamma2);
  [ ClassTransposition(0,2,1,2), ClassTransposition(1,4,7,8),
    ClassTransposition(0,2,3,8) ]
  
\end{Verbatim}
 The above construction is used by \texttt{IsomorphismRcwaGroup} (\ref{IsomorphismRcwaGroup:for a group}) to embed free groups of any rank{\nobreakspace}$\geq 2$. 

 We give another only slightly different representation of the free group of
rank{\nobreakspace}2. We verify that it really is one by applying the
so-called \emph{Table-Tennis Lemma} (see e.g.{\nobreakspace}\cite{LaHarpe00}, Section{\nobreakspace}II.B.) to the infinite cyclic groups generated by the
two generators and to the same two sets \texttt{X1} and \texttt{X2} as above: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> r1 := ClassTransposition(0,2,1,2)*ClassTransposition(0,2,1,4);;
  gap> r2 := ClassTransposition(0,2,1,2)*ClassTransposition(0,2,3,4);;
  gap> F2 := Group(r1^2,r2^2);; SetName(F2,"F_2");
  gap> List(GeneratorsOfGroup(F2),IsTame);
  [ false, false ]
  gap>     IsSubset(X1,X2^F2.1) and IsSubset(X1,X2^(F2.1^-1))
  >    and IsSubset(X2,X1^F2.2) and IsSubset(X2,X1^(F2.2^-1));
  true
  gap> [Sources(r1),Sinks(r1),Loops(r1)]; # compare with X1
  [ [ 0(4) ], [ 1(4) ], [ 0(4), 1(4) ] ]
  gap> [Sources(r2),Sinks(r2),Loops(r2)]; # compare with X2
  [ [ 2(4) ], [ 3(4) ], [ 2(4), 3(4) ] ]
  gap>     IsSubset(X1,Union(Sinks(r1))) and IsSubset(X1,Union(Sinks(r1^-1)))
  >    and IsSubset(X2,Union(Sinks(r2))) and IsSubset(X2,Union(Sinks(r2^-1)));
  true
  gap> IsSubset(Union(Sinks(r1)),X2^F2.1) and
  >    IsSubset(Union(Sinks(r1^-1)),X2^(F2.1^-1));
  true
  gap> IsSubset(Union(Sinks(r2)),X1^F2.2) and
  >    IsSubset(Union(Sinks(r2^-1)),X1^(F2.2^-1));
  true
  
\end{Verbatim}
 Drawing the transition graphs of \texttt{r1} and \texttt{r2} for modulus{\nobreakspace}4 may help understanding what is actually done in
this calculation. It is easy to see that the group generated by \texttt{r1} and{\nobreakspace}\texttt{r2} is \emph{not} free: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Order(r1/r2);
  3
  
\end{Verbatim}
 }

  
\section{\textcolor{Chapter }{ Representations of the modular group PSL(2,Z) }}\label{sec:ModularGroup}
\logpage{[ 5, 19, 0 ]}
\hyperdef{L}{X85B4B4DA83B09E81}{}
{
  The modular group PSL(2,$\Z$) embeds in the group generated by all class transpositions as well. We give
an embedding, and check that it really is one by applying the Table Tennis
Lemma as in the previous section: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> PSL2Z := Group(ClassTransposition(0,3,1,3) * ClassTransposition(0,3,2,3),
  >                   ClassTransposition(1,3,0,6) * ClassTransposition(2,3,3,6));;
  gap> List(GeneratorsOfGroup(PSL2Z),Order);
  [ 3, 2 ]
  
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> X1 := Difference(Integers,ResidueClass(0,3));
  Z \ 0(3)
  gap> X2 := ResidueClass(0,3);
  0(3)
  gap> IsSubset(X1,X2^PSL2Z.1) and IsSubset(X1,X2^(PSL2Z.1^2));
  true
  gap> IsSubset(X2,X1^PSL2Z.2);
  true
  
\end{Verbatim}
 A slightly different representation of PSL(2,$\Z$) can be obtained by using \textsf{RCWA}'s general method for \texttt{IsomorphismRcwaGroup} for free products of finite groups: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Display(Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(3),
  >                                                   CyclicGroup(2)))));
  
  Wild rcwa group over Z, generated by
  
  [
  
  Bijective rcwa mapping of Z with modulus 4
  
                  n mod 4                |                 n^f
  ---------------------------------------+--------------------------------------
    0                                    | n + 2
    1 3                                  | 2n - 2
    2                                    | n/2
  
  
  Bijective rcwa mapping of Z with modulus 2
  
                  n mod 2                |                 n^f
  ---------------------------------------+--------------------------------------
    0                                    | n + 1
    1                                    | n - 1
  
  ]
  
  
\end{Verbatim}
  }

  }

         
\chapter{\textcolor{Chapter }{The Algorithms Implemented in RCWA}}\label{ch:algorithms}
\logpage{[ 6, 0, 0 ]}
\hyperdef{L}{X79EA0B717B045756}{}
{
  This chapter lists brief descriptions of many of the algorithms and methods
implemented in this package. These descriptions are kept very informal and
short, and some of them provide only rudimentary information. They are listed
in alphabetical order. The word ``trivial'' as a description means that essentially nothing is done except of storing or
recalling one or several values, and ``straightforward'' means that no sophisticated algorithm is used. Note that ``trivial'' and ``straightforward'' are to be read as \emph{mathematically} trivial respectively straightforward, and that the code of a function or
method attributed in this way can still be reasonably long and complicated.
Longer and better descriptions of many of the algorithms and methods can be
found in{\nobreakspace}\cite{Kohl07a}. 
\begin{description}
\item[{ \texttt{ActionOnRespectedPartition(\mbox{\texttt{\slshape G}})} }]  ``Straightforward'' after having computed a respected partition by \texttt{RespectedPartition}. One only needs to know how to compute images of residue classes under affine
mappings. 
\item[{ \texttt{Ball(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape g}},\mbox{\texttt{\slshape r}})} }]  ``Straightforward''. 
\item[{ \texttt{Ball(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape p}},\mbox{\texttt{\slshape r}},\mbox{\texttt{\slshape act}})} }]  ``Straightforward''. 
\item[{ \texttt{ClassPairs} }]  Run over all 4-tuples, and filter by divisibility criteria, size comparisons,
ordering of the entries etc. 
\item[{ \texttt{ClassReflection(\mbox{\texttt{\slshape r}},\mbox{\texttt{\slshape m}})} }]  ``Trivial''. 
\item[{ \texttt{ClassRotation(\mbox{\texttt{\slshape r}},\mbox{\texttt{\slshape m}},\mbox{\texttt{\slshape u}})} }]  ``Trivial''. 
\item[{ \texttt{ClassShift(\mbox{\texttt{\slshape r}},\mbox{\texttt{\slshape m}})} }]  ``Trivial''. 
\item[{ \texttt{ClassTransposition(\mbox{\texttt{\slshape r1}},\mbox{\texttt{\slshape m1}},\mbox{\texttt{\slshape r2}},\mbox{\texttt{\slshape m2}})} }]  ``Trivial''. 
\item[{ \texttt{ClassWiseOrderPreservingOn(\mbox{\texttt{\slshape f}})}, etc. }]  Forms the union of the residue classes modulo the modulus of{\nobreakspace}\mbox{\texttt{\slshape f}} in whose corresponding coefficient triple the first entry is positive, zero or
negative, respectively. 
\item[{ \texttt{Coefficients(\mbox{\texttt{\slshape f}})} }]  ``Trivial''. 
\item[{ \texttt{CommonRightInverse(\mbox{\texttt{\slshape l}},\mbox{\texttt{\slshape r}})} }]  (See \texttt{RightInverse}.) 
\item[{ \texttt{CT(\mbox{\texttt{\slshape R}})} }]  Attributes and properties are set according to{\nobreakspace}\cite{Kohl06b}. 
\item[{ \texttt{DecreasingOn(\mbox{\texttt{\slshape f}})} }]  Forms the union of the residue classes which are determined by the
coefficients as indicated. 
\item[{ \texttt{DerivedSubgroup(\mbox{\texttt{\slshape G}})} }]  No genuine method -- \textsf{GAP} Library methods already work for tame groups. 
\item[{ \texttt{Determinant(\mbox{\texttt{\slshape g}})} }]  Evaluation of the given expression. For the mathematical meaning
(epimorphism!), see Theorem{\nobreakspace}2.11.9 in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{DirectProduct(\mbox{\texttt{\slshape G1}},\mbox{\texttt{\slshape G2}}, ... )} }]  Restricts the groups \mbox{\texttt{\slshape G1}}, \mbox{\texttt{\slshape G2}}, ... to disjoint residue classes. See \texttt{Restriction} and Corollary{\nobreakspace}2.3.3 in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{Display(\mbox{\texttt{\slshape f}})} }]  ``Trivial''. 
\item[{ \texttt{Divisor(\mbox{\texttt{\slshape f}})} }]  Lcm of coefficients, as indicated. 
\item[{ \texttt{DrawOrbitPicture} }]  Compute spheres of radius $1, \dots, r$ around the given point(s). Choose the origin either in the lower left corner
of the picture (if all points lie in the first quadrant) or in the middle of
the picture (if they don't). Mark points of the ball with black pixels in case
of a monochrome picture. Choose colors from the given palette depending on the
distance from the starting points in case of a colored picture. 
\item[{ \texttt{EpimorphismFromFpGroup(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape r}})} }]  If the package \textsf{FR}{\nobreakspace}\cite{FR} is loaded, then use its function \texttt{FindGroupRelations} to find relations. Otherwise proceed as follows: First compute the ball of
radius{\nobreakspace}\mbox{\texttt{\slshape r}} around{\nobreakspace}1 in the free group whose rank is the number of stored
generators of{\nobreakspace}\mbox{\texttt{\slshape G}}. Then compute the images of the elements of that ball under the natural
projection onto the group{\nobreakspace}\mbox{\texttt{\slshape G}}. Take pairs of elements of the ball whose images coincide, and add their
quotients to the set of known relations. For images which have finite order,
add the corresponding power relations. Finally, regardless of whether \textsf{FR} is present or not, simplify the finitely presented group with the determined
relations by the operation \texttt{IsomorphismSimplifiedFpGroup} from the \textsf{GAP} Library, and return the natural epimorphism from it to{\nobreakspace}\mbox{\texttt{\slshape G}}. 
\item[{ \texttt{Exponent(\mbox{\texttt{\slshape G}})} }]  Check whether \mbox{\texttt{\slshape G}} is finite. If it is, then use the \textsf{GAP} Library method, applied to \texttt{Image(IsomorphismPermGroup(\mbox{\texttt{\slshape G}}))}. Check whether \mbox{\texttt{\slshape G}} is tame. If yes, return \texttt{infinity}. If not, run a loop over \mbox{\texttt{\slshape G}} until finding an element of infinite order. Once one is found, return \texttt{infinity}. 

 The final loop to find a non-torsion element can be left away under the
assumption that any finitely generated wild rcwa group has a wild element. It
looks likely that this holds, but currently the author does not know a proof. 
\item[{ \texttt{FactorizationIntoCSCRCT(\mbox{\texttt{\slshape g}})} }]  This uses a rather sophisticated method which will likely some time be
published elsewhere. At the moment termination is not guaranteed, but in case
of termination the result is certain. The strategy is roughly first to make
the mapping class-wise order-preserving and balanced, and then to remove all
prime factors from multiplier and divisor one after the other in decreasing
order by dividing by appropriate class transpositions. The remaining integral
mapping can be factored almost similarly easily as a permutation of a finite
set can be factored into transpositions. 
\item[{ \texttt{FactorizationOnConnectedComponents(\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape m}})} }]  Calls \textsf{GRAPE} to get the connected components of the transition graph, and then computes a
partition of the suitably ``blown up'' coefficient list corresponding to the connected components. 
\item[{ \texttt{FixedPointsOfAffinePartialMappings(\mbox{\texttt{\slshape f}})} }]  ``Straightforward''. 
\item[{ \texttt{GluckTaylorInvariant(\mbox{\texttt{\slshape a}}(} }]  Evaluation of the given expression. 
\item[{ \texttt{GuessedDivergence(\mbox{\texttt{\slshape f}})} }]  Numerical computation of the limit of some series, which seems to converge ``often''. Caution!!! 
\item[{ \texttt{Image(\mbox{\texttt{\slshape f}})}, \texttt{Image(\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape S}})} }]  ``Straightforward'' if one can compute images of residue classes under affine mappings and unite
and intersect residue classes (Chinese Remainder Theorem). See
Lemma{\nobreakspace}1.2.1 in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{ImageDensity(\mbox{\texttt{\slshape f}})} }]  Evaluation of the given expression. 
\item[{ \texttt{\mbox{\texttt{\slshape g}} in \mbox{\texttt{\slshape G}}} (membership test for rcwa groups) }]  Test whether the mapping \mbox{\texttt{\slshape g}} or its inverse is in the list of generators of{\nobreakspace}\mbox{\texttt{\slshape G}}. If it is, return \texttt{true}. Test whether its prime set is a subset of the prime set of{\nobreakspace}\mbox{\texttt{\slshape G}}. If not, return \texttt{false}. Test whether the multiplier or the divisor of{\nobreakspace}\mbox{\texttt{\slshape g}} has a prime factor which does not divide the multiplier of{\nobreakspace}\mbox{\texttt{\slshape G}}. If yes, return \texttt{false}. Test if \mbox{\texttt{\slshape G}} is class-wise order-preserving, and \mbox{\texttt{\slshape g}} is not. If so, return \texttt{false}. Test if the sign of \mbox{\texttt{\slshape g}} is{\nobreakspace}-1 and all generators of{\nobreakspace}\mbox{\texttt{\slshape G}} have sign{\nobreakspace}1. If yes, return \texttt{false}. Test if \mbox{\texttt{\slshape G}} is class-wise order-preserving, all generators of{\nobreakspace}\mbox{\texttt{\slshape G}} have determinant{\nobreakspace}0 and \mbox{\texttt{\slshape g}} has determinant{\nobreakspace}$\neq 0$. If yes, return \texttt{false}. Test whether the support of{\nobreakspace}\mbox{\texttt{\slshape g}} is a subset of the support of{\nobreakspace}\mbox{\texttt{\slshape G}}. If not, return \texttt{false}. Test whether \mbox{\texttt{\slshape G}} fixes the nonnegative integers setwise, but{\nobreakspace}\mbox{\texttt{\slshape g}} does not. If yes, return \texttt{false}. 

 If \mbox{\texttt{\slshape G}} is tame, proceed as follows: Test whether the modulus of \mbox{\texttt{\slshape g}} divides the modulus of \mbox{\texttt{\slshape G}}. If not, return \texttt{false}. Test whether \mbox{\texttt{\slshape G}} is finite and \mbox{\texttt{\slshape g}} has infinite order. If so, return \texttt{false}. Test whether \mbox{\texttt{\slshape g}} is tame. If not, return \texttt{false}. Compute a respected partition \texttt{P} of \mbox{\texttt{\slshape G}} and the finite permutation group \texttt{H} induced by \mbox{\texttt{\slshape G}} on it (see \texttt{RespectedPartition}). Check whether \mbox{\texttt{\slshape g}} permutes \texttt{P}. If not, return \texttt{false}. Let \texttt{h} be the permutation induced by \mbox{\texttt{\slshape g}} on \texttt{P}. Check whether \texttt{h} lies in \texttt{H}. If not, return \texttt{false}. Compute an element \texttt{g1} of \mbox{\texttt{\slshape G}} which acts on{\nobreakspace}\texttt{P} like{\nobreakspace}\mbox{\texttt{\slshape g}}. For this purpose, factor \mbox{\texttt{\slshape h}} into generators of{\nobreakspace}\texttt{H} using \texttt{PreImagesRepresentative}, and compute the corresponding product of generators of{\nobreakspace}\mbox{\texttt{\slshape G}}. Let \texttt{k := g/g1}. The mapping \texttt{k} is always integral. Compute the kernel{\nobreakspace}\texttt{K} of the action of \mbox{\texttt{\slshape G}} on{\nobreakspace}\texttt{P} using \texttt{KernelOfActionOnRespectedPartition}. Check whether \texttt{k} lies in{\nobreakspace}\texttt{K}. This is done using the package \textsf{Polycyclic}{\nobreakspace}\cite{Polycyclic}, and uses an isomorphism from a supergroup of {\nobreakspace}\texttt{K} which is isomorphic to the \texttt{|P|}-fold direct product of the infinite dihedral group and which always
contains{\nobreakspace}\texttt{k} to a polycyclically presented group. If{\nobreakspace}\texttt{k} lies in{\nobreakspace}\texttt{K}, return \texttt{true}, otherwise return \texttt{false}. 

 If \mbox{\texttt{\slshape G}} is not tame, proceed as follows: Look for finite orbits of{\nobreakspace}\mbox{\texttt{\slshape G}}. If some are found, test whether \mbox{\texttt{\slshape g}} acts on them, and whether the induced permutations lie in the permutation
groups induced by{\nobreakspace}\mbox{\texttt{\slshape G}}. If for one of the examined orbits one of the latter two questions has a
negative answer, then return \texttt{false}. Look for a positive integer{\nobreakspace}$m$ such that \mbox{\texttt{\slshape g}} does not leave a partition of{\nobreakspace}$\Z$ into unions of residue classes (mod{\nobreakspace}$m$) invariant which is fixed by{\nobreakspace}\mbox{\texttt{\slshape G}}. If successful, return \texttt{false}. If not, try to factor \mbox{\texttt{\slshape g}} into generators of{\nobreakspace}\mbox{\texttt{\slshape G}} using \texttt{PreImagesRepresentative}. If successful, return \texttt{true}. If \mbox{\texttt{\slshape g}} is in \mbox{\texttt{\slshape G}}, this terminates after a finite number of steps. Both runtime and memory
requirements are exponential in the word length. If \mbox{\texttt{\slshape g}} is not in \mbox{\texttt{\slshape G}} at this stage, the method runs into an infinite loop. 
\item[{ \texttt{\mbox{\texttt{\slshape f}} in \mbox{\texttt{\slshape M}}} (membership test for rcwa monoids) }]  Test whether the mapping \mbox{\texttt{\slshape f}} is in the list of generators of{\nobreakspace}\mbox{\texttt{\slshape G}}. If it is, return \texttt{true}. Test whether the multiplier of \mbox{\texttt{\slshape f}} is zero, but all generators of{\nobreakspace}\mbox{\texttt{\slshape M}} have nonzero multiplier. If yes, return \texttt{false}. Test if neither{\nobreakspace}\mbox{\texttt{\slshape f}} nor any generator of{\nobreakspace}\mbox{\texttt{\slshape M}} has multiplier zero. If so, check whether the prime set of{\nobreakspace}\mbox{\texttt{\slshape f}} is a subset of the prime set of{\nobreakspace}\mbox{\texttt{\slshape M}}, and whether the set of prime factors of the multiplier of{\nobreakspace}\mbox{\texttt{\slshape f}} is a subset of the union of the sets of prime factors of the multipliers of
the generators of{\nobreakspace}\mbox{\texttt{\slshape M}}. If one of these is not the case, return \texttt{false}. Check whether the set of prime factors of the divisor of{\nobreakspace}\mbox{\texttt{\slshape f}} is a subset of the union of the sets of prime factors of the divisors of the
generators of{\nobreakspace}\mbox{\texttt{\slshape M}}. If not, return \texttt{false}. If the underlying ring is $\Z$ or a semilocalization thereof, then check whether \mbox{\texttt{\slshape f}} is not class-wise order-preserving, but \mbox{\texttt{\slshape M}}{\nobreakspace}is. If so, return \texttt{false}. 

 If \mbox{\texttt{\slshape f}} is not injective, but all generators of{\nobreakspace}\mbox{\texttt{\slshape M}} are, then return \texttt{false}. If \mbox{\texttt{\slshape f}} is not surjective, but all generators of{\nobreakspace}\mbox{\texttt{\slshape M}} are, then return \texttt{false}. If the support of{\nobreakspace}\mbox{\texttt{\slshape f}} is not a subset of the support of{\nobreakspace}\mbox{\texttt{\slshape M}}, then return \texttt{false}. If \mbox{\texttt{\slshape f}} is not sign-preserving, but \mbox{\texttt{\slshape M}} is, then return \texttt{false}. Check whether \mbox{\texttt{\slshape M}} is tame. If so, then return \texttt{false} provided that one of the following three conditions hold: 1.{\nobreakspace}The
modulus of{\nobreakspace}\mbox{\texttt{\slshape f}} does not divide the modulus of{\nobreakspace}\mbox{\texttt{\slshape M}}. 2.{\nobreakspace}\mbox{\texttt{\slshape f}} is not tame. 3.{\nobreakspace}\mbox{\texttt{\slshape M}} is finite, and \mbox{\texttt{\slshape f}} is bijective and has infinite order. If membership has still not been decided,
use \texttt{ShortOrbits} to look for finite orbits of{\nobreakspace}\mbox{\texttt{\slshape M}}, and check whether \mbox{\texttt{\slshape f}} fixes all of them setwise. If a finite orbit is found which \mbox{\texttt{\slshape f}} does not map to itself, then return \texttt{false}. 

 Finally compute balls of increasing radius around{\nobreakspace}1 until \mbox{\texttt{\slshape f}} is found to lie in one of them. If that happens, return \texttt{true}. If \mbox{\texttt{\slshape f}} is an element of{\nobreakspace}\mbox{\texttt{\slshape M}}, this will eventually terminate, but if at this stage \mbox{\texttt{\slshape f}} is not an element of{\nobreakspace}\mbox{\texttt{\slshape M}}, this will run into an infinite loop. 
\item[{ \texttt{\mbox{\texttt{\slshape point}} in \mbox{\texttt{\slshape orbit}}} (membership test for orbits) }]  Uses the equality test for orbits: The orbit equality test computes balls of
increasing radius around the orbit representatives until they intersect
nontrivially. Once they do so, it returns \texttt{true}. If it finds that one or both of the orbits are finite, it makes use of that
information, and returns \texttt{false} if appropriate. In between, i.e. after having computed balls to a certain
extent depending on the properties of the group, it chooses a suitable
modulus{\nobreakspace}$m$ and computes orbits (modulo{\nobreakspace}$m$). If the representatives of the orbits to be compared belong to different
orbits (mod{\nobreakspace}$m$), it returns \texttt{false}. If this is not the case although the orbits are different, the equality test
runs into an infinite loop. 
\item[{ \texttt{IncreasingOn(\mbox{\texttt{\slshape f}})} }]  Forms the union of the residue classes which are determined by the
coefficients as indicated. 
\item[{ \texttt{Index(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape H}})} }]  In general, i.e. if the underlying ring is not{\nobreakspace}$\Z$, proceed as follows: If both groups \mbox{\texttt{\slshape G}} and{\nobreakspace}\mbox{\texttt{\slshape H}} are finite, return the quotient of their orders. If \mbox{\texttt{\slshape G}} is infinite, but \mbox{\texttt{\slshape H}} is finite, return \texttt{infinity}. Otherwise return the number of right cosets of \mbox{\texttt{\slshape H}} in{\nobreakspace}\mbox{\texttt{\slshape G}}, computed by the \textsf{GAP} Library function \texttt{RightCosets}. 

 If the underlying ring is{\nobreakspace}$\Z$, do additionally the following before attempting to compute the list of right
cosets: If the group \mbox{\texttt{\slshape G}} is class-wise order-preserving, check whether one of its generators has
nonzero determinant, and whether all generators of{\nobreakspace}\mbox{\texttt{\slshape H}} have determinant{\nobreakspace}zero. If so, then return \texttt{infinity}. Check whether \mbox{\texttt{\slshape H}} is tame, but \mbox{\texttt{\slshape G}} is not. If so, then return \texttt{infinity}. If \mbox{\texttt{\slshape G}} is tame, then check whether the rank of the largest free abelian subgroup of
the kernel of the action of \mbox{\texttt{\slshape G}} on a respected partition is higher than the corresponding rank
for{\nobreakspace}\mbox{\texttt{\slshape H}}. For this check, use \texttt{RankOfKernelOfActionOnRespectedPartition}. If it is, then return \texttt{infinity}. 
\item[{ \texttt{Induction(\mbox{\texttt{\slshape g}},\mbox{\texttt{\slshape f}})} }]  Computes \texttt{f * g * RightInverse(\mbox{\texttt{\slshape f}})}. 
\item[{ \texttt{Induction(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape f}})} }]  Gets a set of generators by applying \texttt{Induction(\mbox{\texttt{\slshape g}},\mbox{\texttt{\slshape f}})} to the generators \mbox{\texttt{\slshape g}} of{\nobreakspace}\mbox{\texttt{\slshape G}}. 
\item[{ \texttt{InjectiveAsMappingFrom(\mbox{\texttt{\slshape f}})} }]  The function starts with the entire source of \mbox{\texttt{\slshape f}} as ``preimage'' \texttt{pre} and the empty set as ``image''{\nobreakspace}\texttt{im}. It loops over the residue classes (mod{\nobreakspace}\texttt{Mod(\mbox{\texttt{\slshape f}})}). For any such residue class \texttt{cl} the following is done: Firstly, the image of \texttt{cl} under{\nobreakspace}\mbox{\texttt{\slshape f}} is added to{\nobreakspace}\texttt{im}. Secondly, the intersection of the preimage of the intersection of the image
of \texttt{cl} under \mbox{\texttt{\slshape f}} and \texttt{im} under \mbox{\texttt{\slshape f}} and \texttt{cl} is subtracted from{\nobreakspace}\texttt{pre}. 
\item[{ \texttt{IntegralConjugate(\mbox{\texttt{\slshape f}})}, \texttt{IntegralConjugate(\mbox{\texttt{\slshape G}})} }]  Uses the algorithm described in the proof of Theorem{\nobreakspace}2.5.14
in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{IntegralizingConjugator(\mbox{\texttt{\slshape f}})}, \texttt{IntegralizingConjugator(\mbox{\texttt{\slshape G}})} }]  Uses the algorithm described in the proof of Theorem{\nobreakspace}2.5.14
in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{Inverse(\mbox{\texttt{\slshape f}})} }]  Essentially inversion of affine mappings. See Lemma{\nobreakspace}1.3.1,
Part{\nobreakspace}(b) in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{IsBalanced(\mbox{\texttt{\slshape f}})} }]  Checks whether the sets of prime factors of the multiplier and the divisor
of{\nobreakspace}\mbox{\texttt{\slshape f}} are the same. 
\item[{ \texttt{IsClassReflection(\mbox{\texttt{\slshape g}})} }]  Computes the support of{\nobreakspace}\mbox{\texttt{\slshape g}}, and compares{\nobreakspace}\mbox{\texttt{\slshape g}} with the corresponding class reflection. 
\item[{ \texttt{IsClassRotation(\mbox{\texttt{\slshape g}})} }]  Computes the support of{\nobreakspace}\mbox{\texttt{\slshape g}}, extracts the possible rotation factor from the coefficients and
compares{\nobreakspace}\mbox{\texttt{\slshape g}} with the corresponding class rotation. 
\item[{ \texttt{IsClassShift(\mbox{\texttt{\slshape g}})} }]  Computes the support of{\nobreakspace}\mbox{\texttt{\slshape g}}, and compares{\nobreakspace}\mbox{\texttt{\slshape g}} with the corresponding class shift. 
\item[{ \texttt{IsClassTransposition(\mbox{\texttt{\slshape g}})} }]  Computes the support of{\nobreakspace}\mbox{\texttt{\slshape g}}, writes it as a disjoint union of two residue classes and
compares{\nobreakspace}\mbox{\texttt{\slshape g}} with the class transposition which interchanges them. 
\item[{ \texttt{IsClassWiseOrderPreserving(\mbox{\texttt{\slshape f}})} }]  Tests whether the first entry of all coefficient triples is positive. 
\item[{ \texttt{IsConjugate(RCWA(Integers),\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape g}})} }]  Test whether \mbox{\texttt{\slshape f}} and \mbox{\texttt{\slshape g}} have the same order, and whether either both or none of them is tame. If not,
return \texttt{false}. 

 If the mappings are wild, use \texttt{ShortCycles} to search for finite cycles not belonging to an infinite series, until their
numbers for a particular length differ. This may run into an infinite loop. If
it terminates, return \texttt{false}. 

 If the mappings are tame, use the method described in the proof of
Theorem{\nobreakspace}2.5.14 in{\nobreakspace}\cite{Kohl05} to construct integral conjugates of \mbox{\texttt{\slshape f}} and \mbox{\texttt{\slshape g}}. Then essentially use the algorithm described in the proof of
Theorem{\nobreakspace}2.6.7 in{\nobreakspace}\cite{Kohl05} to compute ``standard representatives'' of the conjugacy classes which the integral conjugates of \mbox{\texttt{\slshape f}} and \mbox{\texttt{\slshape g}} belong to. Finally compare these standard representatives, and return \texttt{true} if they are equal and \texttt{false} if not. 
\item[{ \texttt{IsInjective(\mbox{\texttt{\slshape f}})} }]  See \texttt{Image}. 
\item[{ \texttt{IsIntegral(\mbox{\texttt{\slshape f}})} }]  ``Trivial''. 
\item[{ \texttt{IsomorphismMatrixGroup(\mbox{\texttt{\slshape G}})} }]  Uses the algorithm described in the proof of Theorem{\nobreakspace}2.6.3
in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{IsomorphismPermGroup(\mbox{\texttt{\slshape G}})} }]  If the group \mbox{\texttt{\slshape G}} is finite and class-wise order-preserving, use \texttt{ActionOnRespectedPartition}. If \mbox{\texttt{\slshape G}} is finite, but not class-wise order-preserving, compute the action on the
respected partition which is obtained by splitting any residue class $r(m)$ in \texttt{RespectedPartition(\mbox{\texttt{\slshape G}}} into three residue classes $r(3m), r+m(3m), r+2m(3m)$. If \mbox{\texttt{\slshape G}} is infinite, there is no isomorphism to a finite permutation group, thus
return \texttt{fail}. 
\item[{ \texttt{IsomorphismRcwaGroup(\mbox{\texttt{\slshape G}})} }]  The method for finite groups uses \texttt{RcwaMapping}, Part{\nobreakspace}(d). 

 The method for free products of finite groups uses the Table-Tennis Lemma
(which is also known as \emph{Ping-Pong Lemma}, cp. e.g. Section{\nobreakspace}II.B. in{\nobreakspace}\cite{LaHarpe00}). It uses regular permutation representations of the factors $G_r$ ($r = 0, \dots ,m-1$) of the free product on residue classes modulo $n_r := |G_r|$. The basic idea is that since point stabilizers in regular permutation groups
are trivial, all non-identity elements map any of the permuted residue classes
into their complements. To get into a situation where the Table-Tennis Lemma
is applicable, the method computes conjugates of the images of the mentioned
permutation representations under bijective rcwa mappings $\sigma_r$ which satisfy $0(n_r)^{\sigma_r} = \Z \setminus r(m)$. 

 The method for free groups uses an adaptation of the construction given on
page{\nobreakspace}27 in{\nobreakspace}\cite{LaHarpe00} from PSL(2,$\mathbb{C}$) to RCWA($\Z$). As an equivalent for the closed discs used there, the method takes the
residue classes modulo two times the rank of the free group. 
\item[{ \texttt{IsPerfect(\mbox{\texttt{\slshape G}})} }]  If the group \mbox{\texttt{\slshape G}} is trivial, then return \texttt{true}. Otherwise if it is abelian, then return \texttt{false}. 

 If the underlying ring is{\nobreakspace}$\Z$, then do the following: If one of the generators of{\nobreakspace}\mbox{\texttt{\slshape G}} has sign{\nobreakspace}-1, then return \texttt{false}. If{\nobreakspace}\mbox{\texttt{\slshape G}} is class-wise order-preserving and one of the generators has nonzero
determinant, then return \texttt{false}. 

 If \mbox{\texttt{\slshape G}} is wild, and perfectness has not been decided so far, then give up. If \mbox{\texttt{\slshape G}} is finite, then check the image of \texttt{IsomorphismPermGroup(\mbox{\texttt{\slshape G}})} for perfectness, and return \texttt{true} or \texttt{false} accordingly. 

 If the group{\nobreakspace}\mbox{\texttt{\slshape G}} is tame and if it acts transitively on its stored respected partition, then
return \texttt{true} or \texttt{false} depending on whether the finite permutation group \texttt{ActionOnRespectedPartition(\mbox{\texttt{\slshape G}})} is perfect or not. If{\nobreakspace}\mbox{\texttt{\slshape G}} does not act transitively on its stored respected partition, then give up. 
\item[{ \texttt{IsPrimeSwitch(\mbox{\texttt{\slshape g}})} }]  Checks whether the multiplier of{\nobreakspace}\mbox{\texttt{\slshape g}} is an odd prime, and compares \mbox{\texttt{\slshape g}} with the corresponding prime switch. 
\item[{ \texttt{IsSignPreserving(\mbox{\texttt{\slshape f}})} }]  If \mbox{\texttt{\slshape f}} is not class-wise order-preserving, then return \texttt{false}. Otherwise let $c \geq 1$ be greater than or equal to the maximum of the absolute values of the
coefficients $b_{r(m)}$ of the affine partial mappings of{\nobreakspace}\mbox{\texttt{\slshape f}}, and check whether the minimum of the image of $\{0, \dots, c\}$ under{\nobreakspace}\mbox{\texttt{\slshape f}} is nonnegative and whether the maximum of the image of $\{-c, \dots, -1\}$ under{\nobreakspace}\mbox{\texttt{\slshape f}} is negative. If both is the case, then return \texttt{true}, otherwise return \texttt{false}. 
\item[{ \texttt{IsSolvable(\mbox{\texttt{\slshape G}})} }]  If \mbox{\texttt{\slshape G}} is abelian, then return \texttt{true}. If \mbox{\texttt{\slshape G}} is tame, then return \texttt{true} or \texttt{false} depending on whether \texttt{ActionOnRespectedPartition(\mbox{\texttt{\slshape G}})} is solvable or not. If \mbox{\texttt{\slshape G}} is wild, then give up. 
\item[{ \texttt{IsSubset(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape H}})} (checking for a subgroup relation) }]  Check whether the set of stored generators of{\nobreakspace}\mbox{\texttt{\slshape H}} is a subset of the set of stored generators of{\nobreakspace}\mbox{\texttt{\slshape G}}. If so, return \texttt{true}. Check whether the prime set of{\nobreakspace}\mbox{\texttt{\slshape H}} is a subset of the prime set of{\nobreakspace}\mbox{\texttt{\slshape G}}. If not, return \texttt{false}. Check whether the support of{\nobreakspace}\mbox{\texttt{\slshape H}} is a subset of the support of{\nobreakspace}\mbox{\texttt{\slshape G}}. If not, return \texttt{false}. Check whether \mbox{\texttt{\slshape G}} is tame, but \mbox{\texttt{\slshape H}} is wild. If so, return \texttt{false}. 

 If \mbox{\texttt{\slshape G}} and \mbox{\texttt{\slshape H}} are both tame, then proceed as follows: If the multiplier of \mbox{\texttt{\slshape H}} does not divide the multiplier of{\nobreakspace}\mbox{\texttt{\slshape G}}, then return \texttt{false}. If \mbox{\texttt{\slshape H}} does not respect the stored respected partition of{\nobreakspace}\mbox{\texttt{\slshape G}}, then return \texttt{false}. Check whether the finite permutation group induced by \mbox{\texttt{\slshape H}} on \texttt{RespectedPartition(\mbox{\texttt{\slshape G}})} is a subgroup of \texttt{ActionOnRespectedPartition(\mbox{\texttt{\slshape G}})}. If yes, return \texttt{true}. Check whether the order of{\nobreakspace}\mbox{\texttt{\slshape H}} is greater than the order of{\nobreakspace}\mbox{\texttt{\slshape G}}. If so, return \texttt{false}. 

 Finally use the membership test to check whether all generators
of{\nobreakspace}\mbox{\texttt{\slshape H}} lie in{\nobreakspace}\mbox{\texttt{\slshape G}}, and return \texttt{true} or \texttt{false} accordingly. 
\item[{ \texttt{IsSurjective(\mbox{\texttt{\slshape f}})} }]  See \texttt{Image}. 
\item[{ \texttt{IsTame(\mbox{\texttt{\slshape G}})} }]  Checks whether the modulus of the group is nonzero. 
\item[{ \texttt{IsTame(\mbox{\texttt{\slshape f}})} }]  Application of the criteria given in Corollary{\nobreakspace}2.5.10
and{\nobreakspace}2.5.12 and Theorem{\nobreakspace}A.8 and{\nobreakspace}A.11
in{\nobreakspace}\cite{Kohl05}, as well as of the criteria given in{\nobreakspace}\cite{Kohl07b}. The criterion ``surjective, but not injective means wild'' (Theorem{\nobreakspace}A.8 in{\nobreakspace}\cite{Kohl05}) is the subject of{\nobreakspace}\cite{Kohl06a}. The package \textsf{GRAPE} is needed for the application of the criterion which says that an rcwa
permutation is wild if a transition graph has a weakly-connected component
which is not strongly-connected (cp. Theorem{\nobreakspace}A.11
in{\nobreakspace}\cite{Kohl05}). 
\item[{ \texttt{IsTransitive(\mbox{\texttt{\slshape G}},Integers)} }]  Look for finite orbits, using \texttt{ShortOrbits} on a couple of intervals. If a finite orbit is found, return \texttt{false}. Test if \mbox{\texttt{\slshape G}} is finite. If yes, return \texttt{false}. 

 Search for an element \texttt{g} and a residue class $r(m)$ such that the restriction of \texttt{g} to $r(m)$ is given by $n \mapsto n + m$. Then the cyclic group generated by \texttt{g} acts transitively on $r(m)$. The element \texttt{g} is searched among the generators of \mbox{\texttt{\slshape G}}, its powers, its commutators, powers of its commutators and products of few
different generators. The search for such an element may run into an infinite
loop, as there is no guarantee that the group has a suitable element. 

 If suitable \texttt{g} and $r(m)$ are found, proceed as follows: 

 Put $S := r(m)$. Put $S := S \cup S^g$ for all generators $g$ of \mbox{\texttt{\slshape G}}, and repeat this until $S$ remains constant. This may run into an infinite loop. 

 If it terminates: If $S = \Z$, return \texttt{true}, otherwise return \texttt{false}. 
\item[{ \texttt{KernelOfActionOnRespectedPartition(\mbox{\texttt{\slshape G}})} }]  First determine the abelian invariants of the kernel{\nobreakspace}\texttt{K}. For this, compute sufficiently many quotients of orders of permutation
groups induced by{\nobreakspace}\mbox{\texttt{\slshape G}} on refinements of the stored respected partition{\nobreakspace}\texttt{P} by the order of the permutation group induced by{\nobreakspace}\mbox{\texttt{\slshape G}} on{\nobreakspace}\texttt{P} itself. Then use a random walk through the group \mbox{\texttt{\slshape G}}. Compute powers of elements encountered along the way which
fix{\nobreakspace}\texttt{P}. Translate these kernel elements into elements of a polycyclically presented
group isomorphic to the \texttt{|P|}-fold direct product of the infinite dihedral group (\texttt{K} certainly embeds into this group). Use \textsf{Polycyclic}{\nobreakspace}\cite{Polycyclic} to collect independent ``nice'' generators of{\nobreakspace}\texttt{K}. Proceed until the permutation groups induced by{\nobreakspace}\texttt{K} on the refined respected partitions all equal the initially stored quotients. 
\item[{ \texttt{LargestSourcesOfAffineMappings(\mbox{\texttt{\slshape f}})} }]  Forms unions of residue classes modulo the modulus of the mapping, whose
corresponding coefficient triples are equal. 
\item[{ \texttt{LaTeXObj(\mbox{\texttt{\slshape f}})} }]  Collects residue classes those corresponding coefficient triples are equal. 
\item[{ \texttt{LikelyContractionCentre(\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape maxn}},\mbox{\texttt{\slshape bound}})} }]  Computes trajectories with starting values from a given interval, until a
cycle is reached. Aborts if the trajectory exceeds the prescribed bound. Form
the union of the detected cycles. 
\item[{ \texttt{LocalizedRcwaMapping(\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape p}})} }]  ``Trivial''. 
\item[{ \texttt{Loops(\mbox{\texttt{\slshape f}})} }]  Runs over the residue classes modulo the modulus of{\nobreakspace}\mbox{\texttt{\slshape f}}, and selects those of them which \mbox{\texttt{\slshape f}} does not map to themselves, but which intersect nontrivially with their images
under{\nobreakspace}\mbox{\texttt{\slshape f}}. 
\item[{ \texttt{mKnot(\mbox{\texttt{\slshape m}})} }]  ``Straightforward'', following the definition given in \cite{Keller99}. 
\item[{ \texttt{Modulus(\mbox{\texttt{\slshape G}})} }]  Searches for a wild element in the group. If unsuccessful, tries to construct
a respected partition (see \texttt{RespectedPartition}). 
\item[{ \texttt{Modulus(\mbox{\texttt{\slshape f}})} }]  ``Trivial''. 
\item[{ \texttt{MovedPoints(\mbox{\texttt{\slshape G}})} }]  Needs only forming unions of residue classes and determining fixed points of
affine mappings. 
\item[{ \texttt{Multiplier(\mbox{\texttt{\slshape f}})} }]  Lcm of coefficients, as indicated. 
\item[{ \texttt{Multpk(\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape p}},\mbox{\texttt{\slshape k}})} }]  Forms the union of the residue classes modulo the modulus of the mapping,
which are determined by the given divisibility criteria for the coefficients
of the corresponding affine mapping. 
\item[{ \texttt{NrConjugacyClassesOfRCWAZOfOrder(\mbox{\texttt{\slshape ord}})} }]  The class numbers are taken from Corollary{\nobreakspace}2.7.1
in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{Orbit(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape pnt}},\mbox{\texttt{\slshape gens}},\mbox{\texttt{\slshape acts}},\mbox{\texttt{\slshape act}})} }]  Check if the orbit has length less than a certain bound. If so, then return it
as a list. Otherwise test whether the group \mbox{\texttt{\slshape G}} is tame or wild. 

 If \mbox{\texttt{\slshape G}} is tame, then test whether \mbox{\texttt{\slshape G}} is finite. If yes, then compute the orbit by the \textsf{GAP} Library method. Otherwise proceed as follows: Compute a respected
partition{\nobreakspace}$\mathcal{P}$ of{\nobreakspace}\mbox{\texttt{\slshape G}}. Use{\nobreakspace}$\mathcal{P}$ to find a residue class{\nobreakspace}$r(m)$ which is a subset of the orbit to be computed. In general, $r(m)$ will not be one of the residue classes in{\nobreakspace}$\mathcal{P}$, but a subset of one of them. Put $\Omega := r(m)$. Unite the set{\nobreakspace}$\Omega$ with its images under all the generators of{\nobreakspace}\mbox{\texttt{\slshape G}} and their inverses. Repeat that until $\Omega$ does not change any more. Return{\nobreakspace}$\Omega$. 

 If \mbox{\texttt{\slshape G}} is wild, then return an orbit object which stores the group{\nobreakspace}\mbox{\texttt{\slshape G}}, the representative{\nobreakspace}\mbox{\texttt{\slshape rep}} and the action{\nobreakspace}\mbox{\texttt{\slshape act}}. 
\item[{ \texttt{OrbitsModulo(\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape m}})} }]  Uses \textsf{GRAPE} to compute the connected components of the transition graph. 
\item[{ \texttt{OrbitsModulo(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape m}})} }]  ``Straightforward''. 
\item[{ \texttt{Order(\mbox{\texttt{\slshape f}})} }]  Test for \texttt{IsTame}. If the mapping is not tame, then return \texttt{infinity}. Otherwise use Corollary{\nobreakspace}2.5.10 in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{PreImage(\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape S}})} }]  See \texttt{Image}. 
\item[{ \texttt{PreImagesRepresentative(\mbox{\texttt{\slshape phi}},\mbox{\texttt{\slshape g}})}, \texttt{PreImagesRepresentatives(\mbox{\texttt{\slshape phi}},\mbox{\texttt{\slshape g}})} }]  As indicated in the documentation of these methods. The underlying idea to
successively compute two balls around{\nobreakspace}1 and{\nobreakspace}\mbox{\texttt{\slshape g}} until they intersect non-trivially is standard in computational group theory.
For rcwa groups it would mean wasting both memory and runtime to actually
compute group elements. Thus only images of tuples of points are computed and
stored. 
\item[{ \texttt{PrimeSet(\mbox{\texttt{\slshape f}})}, \texttt{PrimeSet(\mbox{\texttt{\slshape G}})} }]  ``Straightforward''. 
\item[{ \texttt{PrimeSwitch(\mbox{\texttt{\slshape p}})} }]  Multiplication of rcwa mappings as indicated. 
\item[{ \texttt{Print(\mbox{\texttt{\slshape f}})} }]  ``Trivial''. 
\item[{ \texttt{\mbox{\texttt{\slshape f}}*\mbox{\texttt{\slshape g}}} }]  Essentially composition of affine mappings. See Lemma{\nobreakspace}1.3.1,
Part{\nobreakspace}(a) in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{Projections(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape m}})} }]  Use \texttt{OrbitsModulo} to determine the supports of the images of the epimorphisms to be determined,
and use \texttt{RestrictedPerm} to compute the images of the generators of{\nobreakspace}\mbox{\texttt{\slshape G}} under these epimorphisms. 
\item[{ \texttt{Random(RCWA(Integers))} }]  Computes a product of ``randomly'' chosen class shifts, class reflections and class transpositions. This seems to
be suitable for generating reasonably good examples. 
\item[{ \texttt{RankOfKernelOfActionOnRespectedPartition(\mbox{\texttt{\slshape G}})} }]  This performs basically the first part of the computations done by \texttt{KernelOfActionOnRespectedPartition}. 
\item[{ \texttt{RCWA(\mbox{\texttt{\slshape R}})} }]  Attributes and properties are set according to Theorem{\nobreakspace}2.1.1,
Theorem{\nobreakspace}2.1.2, Corollary{\nobreakspace}2.1.6 and
Theorem{\nobreakspace}2.12.8 in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{RcwaGroupByPermGroup(\mbox{\texttt{\slshape G}})} }]  Uses \texttt{RcwaMapping}, Part{\nobreakspace}(d). 
\item[{ \texttt{RcwaMapping} }]  (a)-(c): ``trivial'', (d): \texttt{n\texttt{\symbol{94}}perm - n} for determining the coefficients, (e): ``affine mappings by values at two given points'', (f) and (g): ``trivial'', (h) and (i): correspond to Lemma{\nobreakspace}2.1.4 in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{RepresentativeAction(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape src}},\mbox{\texttt{\slshape dest}},\mbox{\texttt{\slshape act}})}, \texttt{RepresentativeActionPreImage} }]  As indicated in the documentation of these methods. The underlying idea to
successively compute two balls around \mbox{\texttt{\slshape src}} and \mbox{\texttt{\slshape dest}} until they intersect non-trivially is standard in computational group theory.
Words standing for products of generators of \mbox{\texttt{\slshape G}} are stored for any image of \mbox{\texttt{\slshape src}} or \mbox{\texttt{\slshape dest}}. 
\item[{ \texttt{RepresentativeAction(RCWA(Integers),\mbox{\texttt{\slshape P1}},\mbox{\texttt{\slshape P2}})} }]  Arbitrary mapping: see Lemma{\nobreakspace}2.1.4 in{\nobreakspace}\cite{Kohl05}. Tame mapping: see proof of Theorem{\nobreakspace}2.8.9 in{\nobreakspace}\cite{Kohl05}. The former is almost trivial, while the latter is a bit complicated and
takes usually also much more time. 
\item[{ \texttt{RepresentativeAction(RCWA(Integers),\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape g}})} }]  The algorithm used by \texttt{IsConjugate} constructs actually also an element \texttt{x} such that \texttt{\mbox{\texttt{\slshape f}}\texttt{\symbol{94}}x = \mbox{\texttt{\slshape g}}}. 
\item[{ \texttt{RespectedPartition(\mbox{\texttt{\slshape f}})}, \texttt{RespectedPartition(\mbox{\texttt{\slshape G}})} }]  Uses the algorithm described in the proof of Theorem{\nobreakspace}2.5.8
in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{RespectsPartition(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape P}})} }]  ``Straightforward''. 
\item[{ \texttt{RestrictedPerm(\mbox{\texttt{\slshape g}},\mbox{\texttt{\slshape S}}} }]  ``Straightforward''. 
\item[{ \texttt{Restriction(\mbox{\texttt{\slshape g}},\mbox{\texttt{\slshape f}})} }]  Computes the action of \texttt{RightInverse(\mbox{\texttt{\slshape f}}) * g * f} on the image of{\nobreakspace}\mbox{\texttt{\slshape f}}. 
\item[{ \texttt{Restriction(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape f}})} }]  Gets a set of generators by applying \texttt{Restriction(\mbox{\texttt{\slshape g}},\mbox{\texttt{\slshape f}})} to the generators \mbox{\texttt{\slshape g}} of{\nobreakspace}\mbox{\texttt{\slshape G}}. 
\item[{ \texttt{RightInverse(\mbox{\texttt{\slshape f}})} }]  ``Straightforward'' if one knows how to compute images of residue classes under affine mappings,
and how to compute inverses of affine mappings. 
\item[{ \texttt{Root(\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape k}})} }]  If \mbox{\texttt{\slshape f}} is bijective, class-wise order-preserving and has finite order: 

 Find a conjugate of \mbox{\texttt{\slshape f}} which is a product of class transpositions. Slice cycles $\prod_{i=2}^l \tau_{r_1(m_1),r_i(m_i)}$ of{\nobreakspace}\mbox{\texttt{\slshape f}} a respected partition $\mathcal{P}$ into cycles $\prod_{i=1}^l \prod_{j=0}^{k-1} \tau_{r_1(km_1),r_i+jm_i(km_i)}$ of the \mbox{\texttt{\slshape k}}-fold length on the refined partition which one gets from $\mathcal{P}$ by decomposing any $r_i(m_i) \in \mathcal{P}$ into residue classes (mod{\nobreakspace}$km_i$). Finally conjugate the resulting permutation back. 

 Other cases seem to be more difficult and are currently not covered. 
\item[{ \texttt{RotationFactor(\mbox{\texttt{\slshape g}})} }]  ``Trivial''. 
\item[{ \texttt{SemilocalizedRcwaMapping(\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape pi}})} }]  ``Trivial''. 
\item[{ \texttt{ShortCycles(\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape maxlng}})} }]  Looks for fixed points of affine partial mappings of powers of{\nobreakspace}\mbox{\texttt{\slshape f}}. 
\item[{ \texttt{ShortOrbits(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape S}},\mbox{\texttt{\slshape maxlng}})} }]  ``Straightforward''. 
\item[{ \texttt{Sign(\mbox{\texttt{\slshape g}})} }]  Evaluation of the given expression. For the mathematical meaning
(epimorphism!), see Theorem{\nobreakspace}2.12.8 in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{Sinks(\mbox{\texttt{\slshape f}})} }]  Computes the strongly connected components of the transition graph by the
function \texttt{STRONGLY{\textunderscore}CONNECTED{\textunderscore}COMPONENTS{\textunderscore}DIGRAPH}, and selects those which are proper subsets of their preimages and proper
supersets of their images under{\nobreakspace}\mbox{\texttt{\slshape f}}. 
\item[{ \texttt{Size(\mbox{\texttt{\slshape G}})} (order of an rcwa group) }]  Test whether one of the generators of the group{\nobreakspace}\mbox{\texttt{\slshape G}} has infinite order. If so, return \texttt{infinity}. Test whether the group \mbox{\texttt{\slshape G}} is tame. If not, return \texttt{infinity}. Test whether \texttt{RankOfKernelOfActionOnRespectedPartition(\mbox{\texttt{\slshape G}})} is nonzero. If so, return \texttt{infinity}. Otherwise if \mbox{\texttt{\slshape G}} is class-wise order-preserving, return the size of the permutation group
induced on the stored respected partition. If \mbox{\texttt{\slshape G}} is not class-wise order-preserving, return the size of the permutation group
induced on the refinement of the stored respected partition which is obtained
by splitting each residue class into three residue classes with equal moduli. 
\item[{ \texttt{Size(\mbox{\texttt{\slshape M}})} (order of an rcwa monoid) }]  Check whether \mbox{\texttt{\slshape M}} is in fact an rcwa group. If so, use the method for rcwa groups instead. Check
whether one of the generators of{\nobreakspace}\mbox{\texttt{\slshape M}} is surjective, but not injective. If so, return \texttt{infinity}. Check whether for all generators{\nobreakspace}$f$ of{\nobreakspace}\mbox{\texttt{\slshape M}}, the image of the union of the loops of{\nobreakspace}$f$ under{\nobreakspace}$f$ is finite. If not, return \texttt{infinity}. Check whether one of the generators of{\nobreakspace}\mbox{\texttt{\slshape M}} is bijective and has infinite order. If so, return \texttt{infinity}. Check whether one of the generators of{\nobreakspace}\mbox{\texttt{\slshape M}} is wild. If so, return \texttt{infinity}. Apply the above criteria to the elements of the ball of
radius{\nobreakspace}2 around{\nobreakspace}1, and return \texttt{infinity} if appropriate. Finally attempt to compute the list of elements
of{\nobreakspace}\mbox{\texttt{\slshape M}}. If this is successful, return the length of the resulting list. 
\item[{ \texttt{Sources(\mbox{\texttt{\slshape f}})} }]  Computes the strongly connected components of the transition graph by the
function \texttt{STRONGLY{\textunderscore}CONNECTED{\textunderscore}COMPONENTS{\textunderscore}DIGRAPH}, and selects those which are proper supersets of their preimages and proper
subsets of their images under{\nobreakspace}\mbox{\texttt{\slshape f}}. 
\item[{ \texttt{SplittedClassTransposition(\mbox{\texttt{\slshape ct}},\mbox{\texttt{\slshape k}})} }]  ``Straightforward''. 
\item[{ \texttt{StructureDescription(\mbox{\texttt{\slshape G}})} }]  This method uses a combination of techniques to obtain some basic information
on the structure of an rcwa group. The returned description reflects the way
the group has been built (\texttt{DirectProduct}, \texttt{WreathProduct}, etc.). 
\item[{ \texttt{\mbox{\texttt{\slshape f}}+\mbox{\texttt{\slshape g}}} }]  Pointwise addition of affine mappings. 
\item[{ \texttt{Support(\mbox{\texttt{\slshape G}})} }]  ``Straightforward''. 
\item[{ \texttt{Trajectory(\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape n}},...)} }]  Iterated application of an rcwa mapping. In the methods computing ``accumulated coefficients'', additionally composition of affine mappings. 
\item[{ \texttt{TransitionGraph(\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape m}})} }]  ``Straightforward'' -- just check a sufficiently long interval. 
\item[{ \texttt{TransitionMatrix(\mbox{\texttt{\slshape f}},\mbox{\texttt{\slshape m}})} }]  Evaluation of the given expression. 
\item[{ \texttt{TransposedClasses(\mbox{\texttt{\slshape g}})} }]  ``Trivial''. 
\item[{ \texttt{View(\mbox{\texttt{\slshape f}})} }]  ``Trivial''. 
\item[{ \texttt{WreathProduct(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape P}})} }]  Uses \texttt{DirectProduct} to embed the \texttt{DegreeAction(\mbox{\texttt{\slshape P}})}th direct power of{\nobreakspace}\mbox{\texttt{\slshape G}}, and \texttt{RcwaMapping}, Part{\nobreakspace}(d) to embed the finite permutation group{\nobreakspace}\mbox{\texttt{\slshape P}}. 
\item[{ \texttt{WreathProduct(\mbox{\texttt{\slshape G}},\mbox{\texttt{\slshape Z}})} }]  Restricts \mbox{\texttt{\slshape G}} to the residue class{\nobreakspace}3(4), and encodes the generator
of{\nobreakspace}\mbox{\texttt{\slshape Z}} as $\tau_{0(2),1(2)} \cdot \tau_{0(2),1(4)}$. It is used that the images of{\nobreakspace}3(4) under powers of this
mapping are pairwise disjoint residue classes. 
\end{description}
 }

         
\chapter{\textcolor{Chapter }{Installation and auxiliary functions}}\label{ch:InstallationAndAuxiliaryFunctions}
\logpage{[ 7, 0, 0 ]}
\hyperdef{L}{X859F6BF88754E5CC}{}
{
   
\section{\textcolor{Chapter }{Requirements}}\label{sec:Requirements}
\logpage{[ 7, 1, 0 ]}
\hyperdef{L}{X85A08CF187A6D986}{}
{
  The \textsf{RCWA} package needs at least \textsf{GAP}{\nobreakspace}4.4.7, \textsf{ResClasses}{\nobreakspace}2.5.1, \textsf{GRAPE}{\nobreakspace}4.0{\nobreakspace}\cite{GRAPE}, \textsf{Polycyclic}{\nobreakspace}2.1{\nobreakspace}\cite{Polycyclic} and \textsf{GAPDoc}{\nobreakspace}1.0{\nobreakspace}\cite{GAPDoc}. With possible exception of the most recent version of \textsf{ResClasses}, all needed packages are already present in an up-to-date standard \textsf{GAP} installation. The \textsf{RCWA} package can be used under UNIX, under Windows and on the MacIntosh. It is
completely written in the \textsf{GAP} language and does neither contain nor require external binaries. In
particular, warnings concerning missing binaries issued by \textsf{GRAPE} or other packages can savely be ignored. }

  
\section{\textcolor{Chapter }{Installation}}\label{sec:Installation}
\logpage{[ 7, 2, 0 ]}
\hyperdef{L}{X8360C04082558A12}{}
{
  Like any other \textsf{GAP} package, \textsf{RCWA} must be installed in the \texttt{pkg} subdirectory of the \textsf{GAP} distribution. This is accomplished by extracting the distribution file in this
directory. If you have done this, you can load the package as usual via \texttt{LoadPackage( "rcwa" );}. }

  
\section{\textcolor{Chapter }{The Info class of the package}}\label{sec:TheInfoClass}
\logpage{[ 7, 3, 0 ]}
\hyperdef{L}{X7A31FA44791E93C5}{}
{
  

\subsection{\textcolor{Chapter }{InfoRCWA}}
\logpage{[ 7, 3, 1 ]}\nobreak
\hyperdef{L}{X7BAF5F4986288983}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{InfoRCWA\index{InfoRCWA@\texttt{InfoRCWA}}
\label{InfoRCWA}
}\hfill{\scriptsize (info class)}}\\


 This is the Info class of the \textsf{RCWA} package. See section \emph{Info Functions} in the \textsf{GAP} Reference Manual for a description of the Info mechanism. For convenience: \texttt{RCWAInfo(}\mbox{\texttt{\slshape n}}\texttt{)} is a shorthand for \texttt{SetInfoLevel(InfoRCWA},\mbox{\texttt{\slshape n}}\texttt{)}. \index{RCWAInfo@\texttt{RCWAInfo}} }

 }

  
\section{\textcolor{Chapter }{The testing routine}}\label{sec:TheTestingRoutine}
\logpage{[ 7, 4, 0 ]}
\hyperdef{L}{X8667D5027AC3DE8E}{}
{
  

\subsection{\textcolor{Chapter }{RCWATest}}
\logpage{[ 7, 4, 1 ]}\nobreak
\hyperdef{L}{X7A51ED5F839759C0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RCWATest({\slshape })\index{RCWATest@\texttt{RCWATest}}
\label{RCWATest}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 Nothing. 



 Performs tests of the \textsf{RCWA} package. Errors, i.e. differences to the correct results of the test
computations, are reported. The processed test files are in the directory \texttt{pkg/rcwa/tst}. }

 }

 }

  
\section{\textcolor{Chapter }{Building the manual}}\label{sec:BuildingTheManual}
\logpage{[ 7, 5, 0 ]}
\hyperdef{L}{X854E65D281B80D3B}{}
{
  The following routine is a development tool. As all files it generates are
included in the distribution file anyway, users will not need it. 

\subsection{\textcolor{Chapter }{RCWABuildManual}}
\logpage{[ 7, 5, 1 ]}\nobreak
\hyperdef{L}{X7AA556D17F61A44C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RCWABuildManual({\slshape })\index{RCWABuildManual@\texttt{RCWABuildManual}}
\label{RCWABuildManual}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 Nothing. 



 This function builds the manual of the \textsf{RCWA} package in the file formats {\LaTeX}, PDF, HTML and ASCII text. This is accomplished using the \textsf{GAPDoc} package by Frank L{\"u}beck and Max Neunh{\"o}ffer. Building the manual is
possible only on UNIX systems and requires PDF{\LaTeX}. }

 }

  \def\bibname{References\logpage{[ "Bib", 0, 0 ]}
\hyperdef{L}{X7A6F98FD85F02BFE}{}
}

\bibliographystyle{alpha}
\bibliography{rcwabib.xml}

\def\indexname{Index\logpage{[ "Ind", 0, 0 ]}
\hyperdef{L}{X83A0356F839C696F}{}
}


\printindex

\newpage
\immediate\write\pagenrlog{["End"], \arabic{page}];}
\immediate\closeout\pagenrlog
\end{document}
