% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[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[
        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}}

% don't use this because they don't recognize size or color changes
\newsavebox{\xgdttbs}
\sbox{\xgdttbs}{\texttt{\symbol{92}}}
\newcommand{\gdttbs}{\usebox{\xgdttbs}}

\newsavebox{\xgdttob}
\sbox{\xgdttob}{\texttt{\symbol{123}}}
\newcommand{\gdttob}{\usebox{\xgdttob}}

\newsavebox{\xgdttcb}
\sbox{\xgdttcb}{\texttt{\symbol{125}}}
\newcommand{\gdttcb}{\usebox{\xgdttcb}}

\newsavebox{\xgdttti}
\sbox{\xgdttti}{\texttt{\symbol{126}}}
\newcommand{\gdttti}{\usebox{\xgdttti}}

\newsavebox{\xgdttht}
\sbox{\xgdttht}{\texttt{\symbol{94}}}
\newcommand{\gdttht}{\usebox{\xgdttht}}

\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\begin{center}{\Huge \textbf{\textsf{RCWA}}}\\[1cm]
\hypersetup{pdftitle=\textsf{RCWA}}
\markright{\scriptsize \mbox{}\hfill \textsf{RCWA} \hfill\mbox{}}
{\Large \textbf{Residue Class-Wise Affine Groups}}\\[1cm]
{ Version 2.2.1 }\\[1cm]
{September 29, 2006}\\[1cm]
\mbox{}\\[2cm]
{\large \textbf{ Stefan Kohl    }}\\
\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/~kohlsn/}{\texttt{http://www.cip.mathematik.uni-stuttgart.de/~kohlsn/}}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 Institut für Geometrie und Topologie \\
 Pfaffenwaldring 57 \\
 Universitä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, which provides methods for computing with \emph{R}esidue \emph{C}lass-\emph{W}ise \emph{A}ffine groups. 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~$(\Z,+)$. 
\end{itemize}
 With substancial help of this package, the author has found a countable simple
group which is generated by involutions interchanging residue classes of the
integers and into which all the above groups embed. This simple group has an
uncountable series of simple subgroups, which is parametrized by the sets of
odd primes. 

 }\\[1cm]
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
 {\copyright} 2003 - 2006 by Stefan Kohl. This package is distributed under the GNU General
Public License. \vspace{-1cm} }\\[1cm]
{\small 
\section*{Acknowledgements}
\logpage{[ 0, 0, 3 ]}
 I am very grateful to Bettina~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 inviting me to give a talk on the subject in
Lausanne in April 2006, and for his hint on how to construct wreath products
of residue class-wise affine groups with~$(\Z,+)$. I would like to thank Otto H. Kegel, Katrin Tent and Oliver Röndigs for
their related invitations to Freiburg resp. Bielefeld in February and March
2006. }\\[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 ]}
{
  
\section{\textcolor{Chapter }{Motivation}}\label{sec:motivation}
\logpage{[ 1, 1, 0 ]}
{
  \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~1 (cp.~\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 }{Groups which can be dealt with}}\label{sec:GroupsWhichEmbed}
\logpage{[ 1, 2, 0 ]}
{
  The following groups are known to be faithfully representable as residue
class-wise affine groups: 
\begin{itemize}
\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 residue class-wise affine groups. 
\item  Wreath products of residue class-wise affine groups with finite groups and
with~$(\Z,+)$. 
\end{itemize}
 Further every finite group embeds into some divisible residue class-wise
affine torsion group. There are also finitely generated residue class-wise
affine groups which are not finitely presented, and such with unsolvable
membership problem. In principle this package permits to construct and
investigate groups of all mentioned -- and most likely many more not yet known
-- types. 

 The group which is generated by all \emph{class transpositions} -- these are involutions which interchange two disjoint residue classes, see \texttt{ClassTransposition} (\ref{ClassTransposition:r1, m1, r2, m2}) -- is a simple group which contains all the above groups. 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 above have not yet appeared in print.
However they can be found in the preprint~\cite{Kohl06b}, which is available on the author's homepage. }

  
\section{\textcolor{Chapter }{Purpose of this package}}\label{sec:Purpose}
\logpage{[ 1, 3, 0 ]}
{
  So far, compared to classes of groups like for example finite groups, matrix
groups, finitely presented groups or polycyclic groups, not very much is known
about residue class-wise affine groups. This package is intended to serve as a
tool for obtaining a better understanding of their rich and interesting group
theoretical and combinatorial structure. }

  
\section{\textcolor{Chapter }{Scope of this package}}\label{sec:Scope}
\logpage{[ 1, 4, 0 ]}
{
  This package can be applied in various ways to various different problems, and
it is just impossible 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~\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~\texttt{FactorizationIntoCSCRCT} (\ref{FactorizationIntoCSCRCT:g})) 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 ]}
{
  This chapter gives the basic definitions, describes how to enter residue
class-wise affine mappings and how to compute with them. The functionality of
this package which is dedicated to 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 ]}
{
  \index{rcwa mapping@rcwa mapping!definition} \index{rcwa group@rcwa group!definition} Residue class-wise affine groups, or for short \emph{rcwa} groups, 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~$m$ such that the restrictions of~$f$ to the residue classes $r(m) \in \Z/m\Z$ are all affine, i.e. given~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$. \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~$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~$f$, and the lcm of the coefficients $c_{r(m)}$ is called the \emph{divisor} of~$f$. 

 It is easy to see that the residue class-wise affine mappings form a monoid
under composition, and that the residue class-wise affine permutations form a
countable subgroup of Sym($\Z$). We denote the latter group 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~$\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~$\Z$. In fact, this package provides at least rudimentary support for residue
class-wise affine groups over semilocalizations of~$\Z$ and over univariate polynomial rings over finite fields. }

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

 This can be done easiest by \texttt{RcwaMapping( \mbox{\texttt{coeffs}} )}, where \mbox{\texttt{coeffs}} is a list of $m$ coefficient triples \texttt{coeffs[}$r+1$\texttt{]~= [}$a_{r(m)}$, $b_{r(m)}$, $c_{r(m)}$\texttt{]}, with $r$ running from 0 to~$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$~mod~$m$ are divisible by~3. 

 For the general constructor for rcwa mappings, see \texttt{RcwaMapping} (\ref{RcwaMapping:coeffs}). 
\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~$\Z$ can be factored into members of the following three series of rcwa mappings of
particularly simple structure (cp. \texttt{FactorizationIntoCSCRCT} (\ref{FactorizationIntoCSCRCT:g})): 

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



 The \emph{class shift} $\nu_{r(m)}$ is the rcwa mapping of~$\Z$ which maps $n \in r(m)$ to $n + m$ and which fixes $\Z~\setminus r(m)$ pointwise. 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
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ClassReflection( r, m )\index{ClassReflection@\texttt{ClassReflection}!r, m}
\label{ClassReflection:r, m}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ClassReflection( ResidueClass(r, m) )\index{ClassReflection@\texttt{ClassReflection}!r(m)}
\label{ClassReflection:r(m)}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The class reflection $\varsigma_{r(m)}$. 



 The \emph{class reflection} $\varsigma_{r(m)}$ is the rcwa mapping of~$\Z$ which maps $n \in r(m)$ to $-n + 2r$ and which fixes $\Z~\setminus~r(m)$ pointwise. 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
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ClassTransposition( 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( ResidueClass(r1, m1), ResidueClass(r2, m2) )\index{ClassTransposition@\texttt{ClassTransposition}!r1(m1), r2(m2)}
\label{ClassTransposition:r1(m1), r2(m2)}
}\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 by  
\[ \tau_{r_1(m_1),r_2(m_2)}: \ \ \ n \ \longmapsto \ \begin{cases} (m_2 n + m_1
r_2 - m_2 r_1)/m_1 & \text{if} \ n \in r_1(m_1), \\ (m_1 n + m_2 r_1 - m_1
r_2)/m_2 & \text{if} \ n \in r_2(m_2), \\ n & \text{otherwise}, \end{cases} \]
   where it is understood that $0 \leq r_1 < m_1$ and that $0 \leq r_2 < m_2$. The class transposition $\tau_{r_1(m_1),r_2(m_2)}$ is an involution which interchanges the residue classes $r_1(m_1)$ and $r_2(m_2)$ and which fixes the complement of their union pointwise. 

 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}. 
\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 generates the simple group mentioned in
the preface. 

 The permutations of the following kind play an important role in factoring
bijective rcwa mappings into class shifts, class reflections and class
transpositions (cp. \texttt{FactorizationIntoCSCRCT} (\ref{FactorizationIntoCSCRCT:g})): 

\subsection{\textcolor{Chapter }{PrimeSwitch (p)}}
\logpage{[ 2, 2, 4 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PrimeSwitch( p )\index{PrimeSwitch@\texttt{PrimeSwitch}!p}
\label{PrimeSwitch:p}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PrimeSwitch( 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 \emph{prime switch} $\sigma_p$ is a bijective rcwa mapping of $\Z$ with modulus~$4p$, multiplier~$p$ and divisor~2. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  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}
 }

 There are properties \texttt{IsClassShift}, \texttt{IsClassReflection}, \texttt{IsClassTransposition} and \texttt{IsPrimeSwitch} which indicate whether a given rcwa mapping belongs to the corresponding
series. 

 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 (R, m, coeffs)}}
\logpage{[ 2, 2, 5 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping( R, m, coeffs )\index{RcwaMapping@\texttt{RcwaMapping}!R, m, coeffs}
\label{RcwaMapping:R, m, coeffs}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping( R, coeffs )\index{RcwaMapping@\texttt{RcwaMapping}!R, coeffs}
\label{RcwaMapping:R, coeffs}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping( coeffs )\index{RcwaMapping@\texttt{RcwaMapping}!coeffs}
\label{RcwaMapping:coeffs}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping( perm, range )\index{RcwaMapping@\texttt{RcwaMapping}!perm, range}
\label{RcwaMapping:perm, range}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping( m, values )\index{RcwaMapping@\texttt{RcwaMapping}!m, values}
\label{RcwaMapping:m, values}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping( pi, coeffs )\index{RcwaMapping@\texttt{RcwaMapping}!pi, coeffs}
\label{RcwaMapping:pi, coeffs}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping( q, m, coeffs )\index{RcwaMapping@\texttt{RcwaMapping}!q, m, coeffs}
\label{RcwaMapping:q, m, coeffs}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping( P1, P2 )\index{RcwaMapping@\texttt{RcwaMapping}!P1, P2}
\label{RcwaMapping:P1, P2}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RcwaMapping( cycles )\index{RcwaMapping@\texttt{RcwaMapping}!cycles}
\label{RcwaMapping:cycles}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 An rcwa mapping. 



 In all cases the argument~\mbox{\texttt{R}} is the underlying ring, \mbox{\texttt{m}} is the modulus and \mbox{\texttt{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~$m$) in the sorted list returned by \texttt{AllResidues(\mbox{\texttt{R}}, \mbox{\texttt{m}})}. In case $R = \mathbb{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{R}}, \mbox{\texttt{m}} and \mbox{\texttt{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{R}} with modulus \mbox{\texttt{modulus}} and coefficients \mbox{\texttt{coeffs}}, resp. 
\item[{(b)}]  of \mbox{\texttt{R}} = $\mathbb{Z}$ or \mbox{\texttt{R}} = $\mathbb{Z}_{(\pi)}$ with modulus \texttt{Length(\mbox{\texttt{coeffs}})} and coefficients \mbox{\texttt{coeffs}}, resp. 
\item[{(c)}]  of \mbox{\texttt{R}} = $\mathbb{Z}$ with modulus \texttt{Length(\mbox{\texttt{coeffs}})} and coefficients \mbox{\texttt{coeffs}}, resp. 
\item[{(d)}]  of \mbox{\texttt{R}} = $\mathbb{Z}$, acting on any set \texttt{\mbox{\texttt{range}}+k*Length(\mbox{\texttt{range}})} like the permutation \mbox{\texttt{perm}} on \mbox{\texttt{range}}, resp. 
\item[{(e)}]  of \mbox{\texttt{R}} = $\mathbb{Z}$ with modulus \mbox{\texttt{modulus}} and values prescribed by the list \mbox{\texttt{val}}, which consists of 2$\cdot$\mbox{\texttt{modulus}} pairs giving preimage and image for 2 points per residue class (mod \mbox{\texttt{modulus}}), resp. 
\item[{(f)}]  of \mbox{\texttt{R}} = $\Z_{(\pi)}$ with modulus \texttt{Length(\mbox{\texttt{coeffs}})} and coefficients \mbox{\texttt{coeffs}} (the set of primes $\pi$ denoting the underlying ring is passed as argument \mbox{\texttt{pi}}), resp. 
\item[{(g)}]  of \mbox{\texttt{R}} = GF(\mbox{\texttt{q}})[\mbox{\texttt{x}}] with modulus \mbox{\texttt{modulus}} and coefficients \mbox{\texttt{coeffs}}, resp. 
\item[{(h)}]  a bijective rcwa mapping which induces a bijection between the partitions \mbox{\texttt{P1}} and \mbox{\texttt{P2}} of~\mbox{\texttt{R}} into residue classes and which is affine on the elements of \mbox{\texttt{P1}}, resp. 
\item[{(i)}]  a bijective rcwa mapping with ``residue class cycles'' as given by \mbox{\texttt{cycles}}. The latter is a list of lists of pairwise disjoint residue classes which the
mapping should permute cyclically, each. 
\end{description}
 The methods for the operation \texttt{RcwaMapping} perform a number of argument checks, which can be skipped by using \texttt{RcwaMappingNC} instead. \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> x := Indeterminate(GF(2),1);; SetName(x,"x");
  gap> R := PolynomialRing(GF(2),1);
  GF(2)[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}
 }

 \index{View@\texttt{View}!f} \index{Display@\texttt{Display}!f} \index{Print@\texttt{Print}!f} \index{String@\texttt{String}!f} \noindent In most cases the output of the \texttt{View} method does not describe an rcwa mapping completely. In these cases the output
is enclosed in brackets. There are methods installed for \texttt{Display}, \texttt{Print} and \texttt{String}. 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. There is also
a method for \texttt{LaTeX}: 

\subsection{\textcolor{Chapter }{LaTeXObj (f)}}
\logpage{[ 2, 2, 6 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LaTeXObj( f )\index{LaTeXObj@\texttt{LaTeXObj}!f}
\label{LaTeXObj:f}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LaTeX( f )\index{LaTeX@\texttt{LaTeX}!f}
\label{LaTeX:f}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 A {\LaTeX} representation of the rcwa mapping~\mbox{\texttt{f}}. 



 The output makes use of the {\LaTeX} macro package \textsf{amsmath}. If the option \mbox{\texttt{Factorization}} is set, a factorization of \mbox{\texttt{f}} into class shifts, class reflections, class transpositions and prime switches
is printed (cp. \texttt{FactorizationIntoCSCRCT} (\ref{FactorizationIntoCSCRCT:g})). For rcwa mappings with modulus greater than~1, an indentation by \mbox{\texttt{Indentation}} characters can be specified by setting this option value accordingly. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Print(LaTeXObj(T));
  n \ \longmapsto \
  \begin{cases}
    \frac{n}{2}      & \text{if} \ n \in 0(2), \\
    \frac{3n + 1}{2} & \text{if} \ n \in 1(2).
  \end{cases}
  
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Print(LaTeXObj(Comm(a,ClassShift(0,4)):Factorization));
        &\nu_{4(8)} \cdot \nu_{0(8)}^{-1}
   \cdot \tau_{0(8),4(8)} \cdot \tau_{5(16),11(16)}
   \cdot \tau_{4(8),11(16)}
  
\end{Verbatim}
 }

 \index{LaTeXAndXDVI@\texttt{LaTeXAndXDVI}!f} 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{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 functionality for rcwa mappings}}\label{sec:BasicFunctionalityForRcwaMappings}
\logpage{[ 2, 3, 0 ]}
{
  \index{rcwa mapping@rcwa mapping!arithmetic operations} \index{Order@\texttt{Order}!g} \index{IsTame@\texttt{IsTame}!f} 

 Checking whether two rcwa mappings are equal 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 some 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 are methods for \texttt{Order}, which can not only compute a finite order, but 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}!f} \index{IsSurjective@\texttt{IsSurjective}!f} \index{IsBijective@\texttt{IsBijective}!f} \index{Image@\texttt{Image}!f} 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}!f} \index{PreImagesElm@\texttt{PreImagesElm}!f} \index{PreImage@\texttt{PreImage}!f} 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 using \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}!g} \index{MovedPoints@\texttt{MovedPoints}!g} \index{RestrictedPerm@\texttt{RestrictedPerm}!g} There is a method for the operation \texttt{Support} for computing the support of a bijective 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 setwisely. 
\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}!f} \index{Mod@\texttt{Mod}!f} \index{Coefficients@\texttt{Coefficients}!f} There are operations \texttt{Modulus} (abbreviated \texttt{Mod}) and \texttt{Coefficients} for extracting the modulus resp. the coefficient list of a given rcwa mapping.
The meaning of the return values is as described in the previous section.
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 $\mathbb{Z}$, not for all operations applicable methods are available. 

 }

  
\section{\textcolor{Chapter }{Factoring rcwa mappings}}\label{sec:FactoringRcwaMappings}
\logpage{[ 2, 4, 0 ]}
{
  Factoring group elements into elements of some ``nice'' set of generators is often helpful. The following can be seen as an attempt
towards getting a satisfactory solution of this problem for the group RCWA($\Z$): 

\subsection{\textcolor{Chapter }{FactorizationIntoCSCRCT (g)}}
\logpage{[ 2, 4, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FactorizationIntoCSCRCT( g )\index{FactorizationIntoCSCRCT@\texttt{FactorizationIntoCSCRCT}!g}
\label{FactorizationIntoCSCRCT:g}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Factorization( g )\index{Factorization@\texttt{Factorization}!g}
\label{Factorization:g}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 A factorization of the bijective rcwa mapping~\mbox{\texttt{g}} 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. 

 By default, prime switches are taken as one factor. If the option \mbox{\texttt{ExpandPrimeSwitches}} is set, they are each decomposed into the 6 class transpositions given in the
definition (see \texttt{PrimeSwitch} (\ref{PrimeSwitch:p})). By default, the factoring process begins with splitting off factors from
the right. This can be changed by setting the option \mbox{\texttt{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{ShortenPartition}} equal to \texttt{false}. By default, at the end it is checked whether the product of the determined
factors indeed equals \mbox{\texttt{g}}. This check can be suppressed by setting the option \mbox{\texttt{NC}}.

 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~2. 
\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~\ref{sec:FactoringTheCollatzPermutation} Collatz' permutation is factored. Lothar Collatz has investigated this
permutation in~1932. Its cycle structure is unknown so far. 

 Class transpositions can be written as products of any given number $k$ of class transpositions, as long as the underlying ring has a residue class
ring of cardinality~$k$. Such a decomposition can be obtained by \texttt{SplittedClassTransposition(\mbox{\texttt{ct}},\mbox{\texttt{k}})}. 

 \index{SplittedClassTransposition@\texttt{SplittedClassTransposition}!G} 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~\cite{Keller99}: 

\subsection{\textcolor{Chapter }{mKnot (m)}}
\logpage{[ 2, 4, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{mKnot( m )\index{mKnot@\texttt{mKnot}!m}
\label{mKnot:m}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The permutation $g_m$ as introduced in~\cite{Keller99}. 



 The argument \mbox{\texttt{m}} must be an odd integer~$\geq~3$. 
\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 }{Determinant and sign}}\label{sec:DeterminantAndSign}
\logpage{[ 2, 5, 0 ]}
{
  

\subsection{\textcolor{Chapter }{Determinant (g)}}
\logpage{[ 2, 5, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Determinant( g )\index{Determinant@\texttt{Determinant}!g}
\label{Determinant:g}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Determinant( g, S )\index{Determinant@\texttt{Determinant}!g, S}
\label{Determinant:g, S}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 The determinant of the bijective rcwa mapping~\mbox{\texttt{g}}. 



 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 and
their restrictions to unions of residue classes. 

 Using the notation from the definition of an rcwa mapping, the \emph{determinant} det($\sigma$) of an rcwa mapping $\sigma$ is given by   
\[ \frac{1}{m} \left( \sum_{r(m) \in R/mR} \frac{b_{r(m)}}{|a_{r(m)}|} \right). \]
  The determinant mapping is an epimorphism from the group of all class-wise
order-preserving bijective rcwa mappings of $\Z$ to $(\Z,+)$, see~\cite{Kohl05}, Theorem~2.11.9. 

 If a residue class union~\mbox{\texttt{S}} is given as an additional argument, the method returns the determinant of the
restriction of \mbox{\texttt{g}} to~\mbox{\texttt{S}}. 
\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 (g)}}
\logpage{[ 2, 5, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Sign( g )\index{Sign@\texttt{Sign}!g}
\label{Sign:g}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 The sign of the bijective rcwa mapping~\mbox{\texttt{g}}. 



 Using the notation from the definition of an rcwa mapping, the \emph{sign} of a bijective rcwa mapping~$\sigma$ of~$\Z$ is defined by   
\[ (-1)^{\displaystyle{{\rm det}(\sigma) + \frac{1}{m} \left( \sum_{r(m): \
a_{r(m)} < 0} (m - 2r) \right)}}. \]
  The sign mapping is an epimorphism from RCWA($\Z$) to the group $\Z^\times$ of units of~$\Z$, see~\cite{Kohl05}, Theorem~2.12.8. Therefore the kernel of the sign mapping is a normal subgroup of RCWA($\Z$) of index~2. 
\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 }{Attributes and properties derived from the coefficients}}\label{sec:PropertiesDerivedFromCoefficients}
\logpage{[ 2, 6, 0 ]}
{
  \index{Multiplier@\texttt{Multiplier}!f} \index{Mult@\texttt{Mult}!f} \index{Divisor@\texttt{Divisor}!f} \index{Div@\texttt{Div}!f} \index{PrimeSet@\texttt{PrimeSet}!f} \index{integral@integral!definition} \index{rcwa mapping@rcwa mapping!integral} \index{IsIntegral@\texttt{IsIntegral}!f} \index{balanced@\texttt{balanced}!definition} \index{rcwa mapping@rcwa mapping!balanced} \index{IsBalanced@\texttt{IsBalanced}!f} \index{rcwa mapping@rcwa mapping!class-wise order-preserving} \index{IsClassWiseOrderPreserving@\texttt{IsClassWiseOrderPreserving}!f} 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 in short \texttt{Mult} resp. \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~1. An rcwa mapping is called \emph{balanced} if its multiplier and 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)}$ in the numerators of the affine partial mappings are positive. The
corresponding property is \texttt{IsClassWiseOrderPreserving}. \pagebreak[4] 
\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);
  true
  
\end{Verbatim}
 }

  
\section{\textcolor{Chapter }{Functionality related to the affine partial mappings}}\label{sec:AffinePartialMappings}
\logpage{[ 2, 7, 0 ]}
{
  

\subsection{\textcolor{Chapter }{LargestSourcesOfAffineMappings (f)}}
\logpage{[ 2, 7, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LargestSourcesOfAffineMappings( f )\index{LargestSourcesOfAffineMappings@\texttt{LargestSourcesOfAffineMappings}!f}
\label{LargestSourcesOfAffineMappings:f}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 The coarsest partition of \texttt{Source(\mbox{\texttt{f}})} on whose elements the rcwa mapping~\mbox{\texttt{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);; SetName(kappa,"kappa");
  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 }{Multpk (f, p, k)}}
\logpage{[ 2, 7, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Multpk( f, p, k )\index{Multpk@\texttt{Multpk}!f, p, k}
\label{Multpk:f, p, k}
}\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 and $a_{r(m)}$ and $c_{r(m)}$ denote the coefficients of~\mbox{\texttt{f}} as introduced in the definition of an rcwa mapping. 



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

 

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



 The returned list contains entries for the restrictions of~\mbox{\texttt{f}} to all residue classes modulo \texttt{Mod(\mbox{\texttt{f}})}. A list entry can either be an empty set, the source of~\mbox{\texttt{f}} or a set of cardinality~1. The ordering of the entries corresponds to the ordering of the residues in \texttt{AllResidues(Source(\mbox{\texttt{f}}),\mbox{\texttt{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}
 }

 \index{SetOnWhichMappingIsClassWise@\texttt{SetOnWhichMappingIsClassWise}!OrderPreserving} \index{SetOnWhichMappingIsClassWise@\texttt{SetOnWhichMappingIsClassWise}!Constant} \index{SetOnWhichMappingIsClassWise@\texttt{SetOnWhichMappingIsClassWise}!OrderReversing} There are attributes \texttt{SetOnWhichMappingIsClassWise} (\texttt{-OrderPreserving}, \texttt{-Constant}, \texttt{-OrderReversing}) which store the union of the residue classes (mod~\texttt{Mod(\mbox{\texttt{f}})}) on which an rcwa mapping~\mbox{\texttt{f}} of~$\Z$ or of a semilocalization thereof is class-wise order-preserving, class-wise
constant resp. class-wise order-reversing. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List([ClassTransposition(1,2,0,4),ClassShift(2,3),ClassReflection(2,5)],
  >          SetOnWhichMappingIsClassWiseOrderPreserving );
  [ Integers, Integers, Z \ 2(5) ]
  gap> SetOnWhichMappingIsClassWiseConstant(RcwaMapping([[2,0,1],[0,4,1]]));
  1(2)
  gap> SetOnWhichMappingIsClassWiseOrderReversing(ClassReflection(13,17));
  13(17)
  
\end{Verbatim}
 }

  
\section{\textcolor{Chapter }{Transition graphs and transition matrices}}\label{sec:TransGraphMat}
\logpage{[ 2, 8, 0 ]}
{
  

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



 \index{rcwa mapping@rcwa mapping!transition graph} \noindent The \emph{transition graph} $\Gamma_{f,m}$ of~$f$ for modulus~$m$ is defined as follows: 
\begin{enumerate}
\item  The vertices are the residue classes (mod~$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~$m$) to the vertices of the graph corresponds to the ordering of the residues in \texttt{AllResidues(Source(\mbox{\texttt{f}}),\mbox{\texttt{m}})}. The result is returned in the format used by the package \textsf{GRAPE}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> TransitionGraph(ClassShift(0,1),6);
  rec( isGraph := true, order := 6, group := Group(()), 
    schreierVector := [ -1, -2, -3, -4, -5, -6 ], 
    adjacencies := [ [ 2 ], [ 3 ], [ 4 ], [ 5 ], [ 6 ], [ 1 ] ], 
    representatives := [ 1, 2, 3, 4, 5, 6 ], names := [ 1, 2, 3, 4, 5, 6 ] )
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{OrbitsModulo (f, m)}}
\logpage{[ 2, 8, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{OrbitsModulo( f, m )\index{OrbitsModulo@\texttt{OrbitsModulo}!f, m}
\label{OrbitsModulo:f, m}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The partition of \texttt{AllResidues(Source(\mbox{\texttt{f}}),\mbox{\texttt{m}})} corresponding to the weakly connected components of the transition graph of
the rcwa mapping~\mbox{\texttt{f}} for modulus~\mbox{\texttt{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 (f, m)}}
\logpage{[ 2, 8, 3 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FactorizationOnConnectedComponents( f, m )\index{FactorizationOnConnectedComponents@\texttt{FactorizationOnConnectedComponents}!f, m}
\label{FactorizationOnConnectedComponents:f, m}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The set of restrictions of the rcwa mapping~\mbox{\texttt{f}} to the weakly connected components of its transition graph $\Gamma_{f,m}$. 



 The product of the returned mappings is~\mbox{\texttt{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 (f, m)}}
\logpage{[ 2, 8, 4 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TransitionMatrix( f, m )\index{TransitionMatrix@\texttt{TransitionMatrix}!f, m}
\label{TransitionMatrix:f, m}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The transition matrix of the rcwa mapping~\mbox{\texttt{f}} for modulus~\mbox{\texttt{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{m}} and the square of the modulus of~\mbox{\texttt{f}}.   The assignment of the residue classes (mod~\mbox{\texttt{m}}) to the rows and columns of the matrix corresponds to the ordering of the
residues in \texttt{AllResidues(Source(\mbox{\texttt{f}}),\mbox{\texttt{m}})}. 

 The transition matrix is a weighted adjacency matrix of the corresponding
transition graph \texttt{TransitionGraph(\mbox{\texttt{f}},\mbox{\texttt{m}})}. The sums of the rows of a transition matrix are always equal to~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 (f)}}
\logpage{[ 2, 8, 5 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Sources( f )\index{Sources@\texttt{Sources}!f}
\label{Sources:f}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 A list of unions of residue classes modulo the modulus~$m$ of the rcwa mapping~\mbox{\texttt{f}}, as described below. 



 The returned list contains an entry for any strongly connected component of
the transition graph of~\mbox{\texttt{f}} for modulus~\texttt{Mod(\mbox{\texttt{f}})} which has only outgoing edges. 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> Sources(ClassTransposition(0,2,1,2)*ClassTransposition(0,2,1,4));
  [ 0(4) ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Sinks (f)}}
\logpage{[ 2, 8, 6 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Sinks( f )\index{Sinks@\texttt{Sinks}!f}
\label{Sinks:f}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 (See \texttt{Sources} (\ref{Sources:f}), with ``outgoing'' replaced by ``ingoing''.) 



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

 

\subsection{\textcolor{Chapter }{Loops (f)}}
\logpage{[ 2, 8, 7 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Loops( f )\index{Loops@\texttt{Loops}!f}
\label{Loops:f}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 The list of non-isolated vertices of the transition graph of the rcwa mapping~\mbox{\texttt{f}} for modulus \texttt{Mod(\mbox{\texttt{f}})} which carry a loop. 



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

 }

  
\section{\textcolor{Chapter }{Trajectories}}\label{sec:Trajectories}
\logpage{[ 2, 9, 0 ]}
{
  

\subsection{\textcolor{Chapter }{Trajectory (f, n, length)}}
\logpage{[ 2, 9, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Trajectory( f, n, length )\index{Trajectory@\texttt{Trajectory}!f, n, length}
\label{Trajectory:f, n, length}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Trajectory( f, n, length, m )\index{Trajectory@\texttt{Trajectory}!f, n, length, m}
\label{Trajectory:f, n, length, m}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Trajectory( f, n, terminal )\index{Trajectory@\texttt{Trajectory}!f, n, terminal}
\label{Trajectory:f, n, terminal}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Trajectory( f, n, terminal, m )\index{Trajectory@\texttt{Trajectory}!f, n, terminal, m}
\label{Trajectory:f, n, terminal, m}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 The first \mbox{\texttt{length}} iterates in the trajectory of the rcwa mapping~\mbox{\texttt{f}} starting at~\mbox{\texttt{n}}, resp. the initial part of the trajectory of the rcwa mapping~\mbox{\texttt{f}} starting at~\mbox{\texttt{n}} which ends at the first occurence of an iterate in the set \mbox{\texttt{terminal}}. If the argument \mbox{\texttt{m}} is given, the iterates are reduced (mod~\mbox{\texttt{m}}). 



 To save memory when computing long trajectories containing huge iterates, the
reduction (mod~\mbox{\texttt{m}}) is done each time before storing an iterate. In place of the ring element~\mbox{\texttt{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 (f, n, length, whichcoeffs)}}
\logpage{[ 2, 9, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Trajectory( f, n, length, whichcoeffs )\index{Trajectory@\texttt{Trajectory}!f, n, length, whichcoeffs}
\label{Trajectory:f, n, length, whichcoeffs}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Trajectory( f, n, terminal, whichcoeffs )\index{Trajectory@\texttt{Trajectory}!f, n, terminal, whichcoeffs}
\label{Trajectory:f, n, terminal, whichcoeffs}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 Either the list \texttt{c} of triples of coprime coefficients such that for any~\texttt{k} it holds that \texttt{\mbox{\texttt{n}}\texttt{\symbol{94}}(\mbox{\texttt{f}}\texttt{\symbol{94}}(k-1)) = (c[k][1]*\mbox{\texttt{n}} + c[k][2])/c[k][3]} or the last entry of that list, depending on whether \mbox{\texttt{whichcoeffs}} is \texttt{"AllCoeffs"} or \texttt{"LastCoeffs"}. 



 The meanings of the arguments \mbox{\texttt{length}} and \mbox{\texttt{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{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}
 }

 

\subsection{\textcolor{Chapter }{IncreasingOn (f)}}
\logpage{[ 2, 9, 3 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IncreasingOn( f )\index{IncreasingOn@\texttt{IncreasingOn}!f}
\label{IncreasingOn:f}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DecreasingOn( f )\index{DecreasingOn@\texttt{DecreasingOn}!f}
\label{DecreasingOn:f}
}\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|$ resp. $|R/a_{r(m)}R| < |R/c_{r(m)}R|$, where $R$ denotes the source, $m$ the modulus and $a_{r(m)}$, $b_{r(m)}$ and $c_{r(m)}$ the coefficients of~\mbox{\texttt{f}} as introduced in the definition of an rcwa mapping. 



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

 

\subsection{\textcolor{Chapter }{GluckTaylorInvariant (a)}}
\logpage{[ 2, 9, 4 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GluckTaylorInvariant( a )\index{GluckTaylorInvariant@\texttt{GluckTaylorInvariant}!a}
\label{GluckTaylorInvariant:a}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The invariant introduced in~\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~\mbox{\texttt{a}}. 



 The argument \mbox{\texttt{a}} must be a list of integers. In~\cite{GluckTaylor02} it is shown that if \mbox{\texttt{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~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}
 }

 }

  
\section{\textcolor{Chapter }{ Localizations of rcwa mappings of the integers }}\label{sec:Localizations}
\logpage{[ 2, 10, 0 ]}
{
  

\subsection{\textcolor{Chapter }{LocalizedRcwaMapping (f, p)}}
\logpage{[ 2, 10, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LocalizedRcwaMapping( f, p )\index{LocalizedRcwaMapping@\texttt{LocalizedRcwaMapping}!f, p}
\label{LocalizedRcwaMapping:f, p}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SemilocalizedRcwaMapping( f, pi )\index{SemilocalizedRcwaMapping@\texttt{SemilocalizedRcwaMapping}!f, pi}
\label{SemilocalizedRcwaMapping:f, pi}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The rcwa mapping of $\Z_{(p)}$ resp. $\Z_{(\pi)}$ with the same coefficients as the rcwa mapping \mbox{\texttt{f}} of~$\Z$. 



 The argument \mbox{\texttt{p}} resp. \mbox{\texttt{pi}} must be a prime resp. a set of primes, and the argument~\mbox{\texttt{f}} must be an rcwa mapping of~$\Z$ whose modulus is a power of~\mbox{\texttt{p}}, resp. whose modulus has only prime divisors which lie in~\mbox{\texttt{pi}}. 
\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}
 }

 }

  
\section{\textcolor{Chapter }{ Extracting roots of rcwa mappings }}\label{sec:ExtractingRoots}
\logpage{[ 2, 11, 0 ]}
{
  

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



 
\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> last^100 = ClassTransposition(0,2,1,2);
  true
  
\end{Verbatim}
 }

 }

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

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



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

 

\subsection{\textcolor{Chapter }{CommonRightInverse (l, r)}}
\logpage{[ 2, 12, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CommonRightInverse( l, r )\index{CommonRightInverse@\texttt{CommonRightInverse}!l, r}
\label{CommonRightInverse:l, r}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 A mapping $d$ such that \mbox{\texttt{l}}$d$ = \mbox{\texttt{r}}$d$ = 1. 



 The mappings \mbox{\texttt{l}} and \mbox{\texttt{r}} must be injective, and their images must form a partition of their source. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> twice := RcwaMapping([[2,0,1]]); twiceplus1 := RcwaMapping([[2,1,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 (f)}}
\logpage{[ 2, 12, 3 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ImageDensity( f )\index{ImageDensity@\texttt{ImageDensity}!f}
\label{ImageDensity:f}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 The \emph{image density} of the rcwa mapping~\mbox{\texttt{f}}. 



 In the notation introduced in the definition of an rcwa mapping, the \emph{image density} of an rcwa mapping~$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~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}!f} Given an rcwa mapping \texttt{f}, the function \texttt{InjectiveAsMappingFrom} returns a set \texttt{S} such that the restriction of \texttt{f} to~\texttt{S} is injective, and such that the image of \texttt{S} under~\texttt{f} is the entire image of~\texttt{f}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> InjectiveAsMappingFrom(T);
  0(2)
  
\end{Verbatim}
 }

 \pagebreak[4]  
\section{\textcolor{Chapter }{ Probabilistic guesses on the behaviour of trajectories }}\label{sec:ProbabilisticGuesses}
\logpage{[ 2, 13, 0 ]}
{
  This section describes some functionality for getting ``educated guesses'' on the overall behaviour of the trajectories of a given rcwa mapping. Its
contents have deliberately been separated from the documentation of the
non-probabilistic functionality related to trajectories of rcwa mappings. 

\subsection{\textcolor{Chapter }{LikelyContractionCentre (f, maxn, bound)}}
\logpage{[ 2, 13, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LikelyContractionCentre( f, maxn, bound )\index{LikelyContractionCentre@\texttt{LikelyContractionCentre}!f, maxn, bound}
\label{LikelyContractionCentre:f, maxn, bound}
}\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{f}}. Assuming its existence this is the unique finite subset $S_0$ of the source of~\mbox{\texttt{f}} on which \mbox{\texttt{f}} induces a permutation and which intersects nontrivially with any trajectory of~\mbox{\texttt{f}}. The mapping~\mbox{\texttt{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{maxn}} is a bound on the starting value and \mbox{\texttt{bound}} is a bound on the elements of the trajectories to be searched. If the limit \mbox{\texttt{bound}} is exceeded, an Info message on Info level~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 (f)}}
\logpage{[ 2, 13, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GuessedDivergence( f )\index{GuessedDivergence@\texttt{GuessedDivergence}!f}
\label{GuessedDivergence:f}
}\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~\mbox{\texttt{f}} diverge (return value greater than~1) or converge (return value smaller than~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, 14, 0 ]}
{
  

\subsection{\textcolor{Chapter }{IsRcwaMapping (f)}}
\logpage{[ 2, 14, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaMapping( f )\index{IsRcwaMapping@\texttt{IsRcwaMapping}!f}
\label{IsRcwaMapping:f}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaMappingOfZ( f )\index{IsRcwaMappingOfZ@\texttt{IsRcwaMappingOfZ}!f}
\label{IsRcwaMappingOfZ:f}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaMappingOfZ\_pi( f )\index{IsRcwaMappingOfZpi@\texttt{IsRcwaMappingOfZ\_pi}!f}
\label{IsRcwaMappingOfZpi:f}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaMappingOfGFqx( f )\index{IsRcwaMappingOfGFqx@\texttt{IsRcwaMappingOfGFqx}!f}
\label{IsRcwaMappingOfGFqx:f}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} if \mbox{\texttt{f}} is an rcwa mapping resp. an rcwa mapping of the ring of integers resp. an rcwa
mapping of a semilocalization of the ring of integers resp. an rcwa mapping of
a polynomial ring in one variable over a finite field, 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}!f} The internal representation of rcwa mappings is called \texttt{IsRcwaMappingStandardRep}. \index{IsRcwaMappingStandardRep@\texttt{IsRcwaMappingStandardRep}} }

 

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

}

 }

  }

         
\chapter{\textcolor{Chapter }{Residue Class-Wise Affine Groups}}\label{ch:RcwaGroups}
\logpage{[ 3, 0, 0 ]}
{
  This chapter describes the functionality provided by this package for
computing with residue class-wise affine groups.  
\section{\textcolor{Chapter }{Constructing residue class-wise affine groups}}\label{sec:ContructingRcwaGroups}
\logpage{[ 3, 1, 0 ]}
{
  \index{Group@\texttt{Group}} \index{GroupByGenerators@\texttt{GroupByGenerators}} \index{GroupWithGenerators@\texttt{GroupWithGenerators}} Residue class-wise affine groups can be constructed using either \texttt{Group}, \texttt{GroupByGenerators} or \texttt{GroupWithGenerators} as usual, cp. the \textsf{GAP} reference manual. 
\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}!G} \index{Display@\texttt{Display}!G} \index{Print@\texttt{Print}!G} \index{String@\texttt{String}!G} 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 in the way
described above. It is handled as a special case: 

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



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> RCWA_Z := RCWA(Integers);
  RCWA(Z)
  
\end{Verbatim}
 \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> One(RCWA_Z); Size(RCWA_Z); IsFinitelyGeneratedGroup(RCWA_Z);
  IdentityMapping( Integers )
  infinity
  false
  gap> IsSolvable(RCWA_Z) or IsPerfect(RCWA_Z);
  false
  gap> Centre(RCWA_Z);
  Trivial rcwa group over Z
  gap> IsSubgroup(RCWA_Z,G);
  true
  
\end{Verbatim}
 }

 There is a method for the operation \texttt{Random} which generates pseudo-random elements of RCWA($\Z$) -- see Section~\ref{sec:Random}. 

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

\subsection{\textcolor{Chapter }{IsomorphismRcwaGroupOverZ (G)}}
\logpage{[ 3, 1, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismRcwaGroupOverZ( G )\index{IsomorphismRcwaGroupOverZ@\texttt{IsomorphismRcwaGroupOverZ}!G}
\label{IsomorphismRcwaGroupOverZ:G}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismRcwaGroup( G )\index{IsomorphismRcwaGroup@\texttt{IsomorphismRcwaGroup}!G}
\label{IsomorphismRcwaGroup:G}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 A monomorphism from the group \mbox{\texttt{G}} to~RCWA($\Z$). 



 Currently there are methods available for finite groups, for free products of
finite groups and for free groups. The method for free products of finite
groups uses the Table-Tennis Lemma (cp. e.g. Section~II.B. in~\cite{LaHarpe00}), and the method for free groups uses an adaptation of the construction given
on page~27 in~\cite{LaHarpe00} from PSL(2,$\mathbb{C}$) to RCWA($\mathbb{Z}$). 

 In case \mbox{\texttt{G}} is a finite-degree permutation group, the image under a specific embedding can
be obtained by \texttt{RcwaGroupByPermGroup(\mbox{\texttt{G}})}. \index{RcwaGroupByPermGroup@\texttt{RcwaGroupByPermGroup}!G} The resulting group~\texttt{H} satisfies the relation \texttt{Action(H\texttt{\symbol{94}}ClassShift(0,1),[1..LargestMovedPoint(\mbox{\texttt{G}})]) =~G}. 
\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}
 }

 \pagebreak[4] 

\subsection{\textcolor{Chapter }{StructureDescription (G)}}
\logpage{[ 3, 1, 3 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StructureDescription( G )\index{StructureDescription@\texttt{StructureDescription}!G}
\label{StructureDescription:G}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 A string which describes the structure of the rcwa group~\mbox{\texttt{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~\texttt{wr}, and free products are denoted by~\texttt{*}. The infinite cyclic group $(\Z,+)$ is denoted by~\texttt{Z}, the infinite dihedral group is denoted by~\texttt{D0} and free groups of rank $2,3,4,\dots$ are denoted by~\texttt{F2}, \texttt{F3}, \texttt{F4},~$\dots$. While for finite groups the symbol~\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{<unknown>}. In general, the structure of a section denoted by \texttt{<unknown>} can be very complicate and very difficult to exhibit. While for isomorphic
finite groups always the same structure description is computed, this cannot
be guaranteed for isomorphic rcwa groups. 
\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}
 }

 }

  
\section{\textcolor{Chapter }{Direct products and wreath products}}\label{sec:DirectProductsAndWreathProducts}
\logpage{[ 3, 2, 0 ]}
{
  The class of groups which can faithfully be represented as rcwa groups is
closed under forming direct products, wreath products with finite groups and
wreath products with the infinite cyclic group $(\Z,+)$. For information on how direct products and wreath products of subgroups of
RCWA($\Z$) are embedded in RCWA($\Z$), see Section~\ref{sec:RestrictionAndInduction} below. \pagebreak[4] 

\subsection{\textcolor{Chapter }{DirectProduct (G1, G2, ...)}}
\logpage{[ 3, 2, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DirectProduct( G1, G2, ... )\index{DirectProduct@\texttt{DirectProduct}!G1, G2, ...}
\label{DirectProduct:G1, G2, ...}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 An rcwa group isomorphic to the direct product of the rcwa groups over~$\Z$ given as arguments. 



 There is certainly no unique or canonical way to embed a direct product of
rcwa groups into RCWA($\Z$). This method chooses to embed the groups \mbox{\texttt{G1}}, \mbox{\texttt{G2}}, \mbox{\texttt{G3}}~... via restrictions by $n \mapsto mn$, $n \mapsto mn+1$, $n \mapsto mn+2$~... ($\rightarrow$~\texttt{Restriction} (\ref{Restriction:G, f})), 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 (G, P)}}
\logpage{[ 3, 2, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WreathProduct( G, P )\index{WreathProduct@\texttt{WreathProduct}!G, P}
\label{WreathProduct:G, P}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WreathProduct( G, Z )\index{WreathProduct@\texttt{WreathProduct}!G, Z}
\label{WreathProduct:G, Z}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 An rcwa group isomorphic to the wreath product of the rcwa group~\mbox{\texttt{G}} over~$\mathbb{Z}$ with the finite permutation group~\mbox{\texttt{P}}, resp. with the infinite cyclic group~\mbox{\texttt{Z}}. 



 The first-mentioned method embeds the \texttt{DegreeAction(\mbox{\texttt{P}})}th direct power of~\mbox{\texttt{G}} using the method for \texttt{DirectProduct}, and lets the permutation group~\mbox{\texttt{P}} act naturally on the set of residue classes modulo \texttt{DegreeAction(\mbox{\texttt{P}})}. The second-mentioned method restricts ($\rightarrow$~\texttt{Restriction} (\ref{Restriction:G, f})) the group~\mbox{\texttt{G}} to the residue class~3(4), and maps the generator of the infinite cyclic group~\mbox{\texttt{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}
 }

 }

  
\section{\textcolor{Chapter }{ The membership test }}\label{sec:MembershipTest}
\logpage{[ 3, 3, 0 ]}
{
  \index{rcwa group@rcwa group!membership test} There is a method for the operation \texttt{in}. Given an rcwa group~\texttt{G} and an rcwa mapping~\texttt{g}, this method tries to decide whether \texttt{g} is an element of~\texttt{G} or not. It can always decide this question if \texttt{G} is tame. For wild groups this is sometimes not the case. On Info level~2 of \texttt{InfoRCWA} the method gives information on reasons why \texttt{g} is an element of~\texttt{G} or~not. 

 The direct product of two free groups of rank~2 can faithfully be represented as an rcwa group. According to~\cite{Mihailova58} this implies that in general the membership problem for rcwa groups is
algorithmically undecidable. 
\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}
 }

  
\section{\textcolor{Chapter }{Basic attributes and properties of rcwa groups}}\label{sec:AttributesAndProperties}
\logpage{[ 3, 4, 0 ]}
{
  \index{Size@\texttt{Size}!G} There is a method available for 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~\texttt{RespectedPartition} (\ref{RespectedPartition:G})) is faithful. Hence the problem of computing the order of an rcwa group
reduces to the problem of deciding whether it is tame, the problem of deciding
whether it acts faithfully on a respected partition and the problem of
computing the order of the finite permutation group induced on the respected
partition. \index{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{Modulus@\texttt{Modulus}!G} \index{Mod@\texttt{Mod}!G} \index{ModulusOfRcwaGroup@\texttt{ModulusOfRcwaGroup}!G} \index{Multiplier@\texttt{Multiplier}!G} \index{Mult@\texttt{Mult}!G} \index{Divisor@\texttt{Divisor}!G} \index{Div@\texttt{Div}!G} \index{PrimeSet@\texttt{PrimeSet}!G} Basic attributes derived from the affine partial mappings of the elements of
an rcwa group and their coefficients 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 in case such an lcm
exists and 0 otherwise. The \emph{multiplier} resp. \emph{divisor} of an rcwa group is the lcm of the multipliers resp. 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} resp. \texttt{Divisor}. Technically, the modulus of an rcwa group is stored as an attribute \texttt{ModulusOfRcwaGroup}. 

 \index{rcwa group@rcwa group!integral} \index{rcwa group@rcwa group!class-wise order-preserving} \index{IsTame@\texttt{IsTame}!G} \index{IsIntegral@\texttt{IsIntegral}!G} \index{IsClassWiseOrderPreserving@\texttt{IsClassWiseOrderPreserving}!G} A tame rcwa group, i.e. one with modulus~0, has the property \texttt{IsTame}. An rcwa group is called \emph{integral} resp. \emph{class-wise order-preserving} if all of its elements are so. There are corresponding methods available for \texttt{IsIntegral} and \texttt{IsClassWiseOrderPreserving}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> g1 := RcwaMapping((1,2),[1..2]);;
  gap> g2 := RcwaMapping((1,2,3),[1..3]);;
  gap> g3 := RcwaMapping((1,2,3,4,5),[1..5]);;
  gap> List([g1,g2,g3],Modulus);
  [ 2, 3, 5 ]
  gap> G := Group(g1,g2,g3);;
  gap> Size(G);
  265252859812191058636308480000000
  gap> List([Modulus,Multiplier,Divisor,PrimeSet,
  >          IsIntegral,IsClassWiseOrderPreserving],f->f(G));
  [ 30, 1, 1, [ 2, 3, 5 ], true, true ]
  
\end{Verbatim}
 }

 \pagebreak[4]  
\section{\textcolor{Chapter }{ Permutation- and matrix representations }}\label{sec:PermutationAndMatrixReps}
\logpage{[ 3, 5, 0 ]}
{
  

\subsection{\textcolor{Chapter }{IsomorphismPermGroup (G)}}
\logpage{[ 3, 5, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismPermGroup( G )\index{IsomorphismPermGroup@\texttt{IsomorphismPermGroup}!G}
\label{IsomorphismPermGroup:G}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 An isomorphism from the finite rcwa group~\mbox{\texttt{G}} to a finite-degree permutation group. 



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

 

\subsection{\textcolor{Chapter }{IsomorphismMatrixGroup (G)}}
\logpage{[ 3, 5, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismMatrixGroup( G )\index{IsomorphismMatrixGroup@\texttt{IsomorphismMatrixGroup}!G}
\label{IsomorphismMatrixGroup:G}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 An isomorphism from the rcwa group~\mbox{\texttt{G}} to a matrix group, provided that \mbox{\texttt{G}} embeds into a matrix group and that there is a suitable method available. Both
conditions are fulfilled if \mbox{\texttt{G}} is tame. 



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> G := Group(ClassTransposition(0,2,1,4),ClassShift(2,4));
  <rcwa group over Z with 2 generators>
  gap> phi := IsomorphismMatrixGroup(G);;
  gap> FieldOfMatrixGroup(Image(phi));
  Rationals
  gap> DegreeOfMatrixGroup(Image(phi));
  10
  gap> Display(GeneratorsOfGroup(Image(phi))[1]*One(GF(5)));
   . . . . . . 3 2 . .
   . . . . . . . 1 . .
   . . . . . . . . 3 2
   . . . . . . . . . 1
   . . . . 1 . . . . .
   . . . . . 1 . . . .
   2 1 . . . . . . . .
   . 1 . . . . . . . .
   . . 2 1 . . . . . .
   . . . 1 . . . . . .
  gap> Display(GeneratorsOfGroup(Image(phi))[2]*One(GF(5)));
   1 . . . . . . . . .
   . 1 . . . . . . . .
   . . 1 4 . . . . . .
   . . . 1 . . . . . .
   . . . . 1 . . . . .
   . . . . . 1 . . . .
   . . . . . . 1 . . .
   . . . . . . . 1 . .
   . . . . . . . . 1 .
   . . . . . . . . . 1
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{ Factoring elements into generators }}\label{sec:ElementFactorization}
\logpage{[ 3, 6, 0 ]}
{
  

\subsection{\textcolor{Chapter }{PreImagesRepresentative (phi, g)}}
\logpage{[ 3, 6, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PreImagesRepresentative( phi, g )\index{PreImagesRepresentative@\texttt{PreImagesRepresentative}!phi, g}
\label{PreImagesRepresentative:phi, g}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 A representative of the set of preimages of~\mbox{\texttt{g}} under the homomorphism~\mbox{\texttt{phi}} from a free group to an rcwa group over~$\mathbb{Z}$. 



 This method can be used for factoring elements of rcwa groups over $\mathbb{Z}$ into generators. It can also be used for finding nontrivial relations among
the generators if the respective group is not free and the method returns a
factorization which does not happen to be equal to one which is already known.
The homomorphism \mbox{\texttt{phi}} must map the generators of the free group to the generators of the rcwa group
one-by-one. This method is also suitable for wild groups. The implementation
is based on \texttt{RepresentativeActionPreImage} (\ref{RepresentativeActionPreImage:G, src, dest, act, F}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> a  := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; # Collatz' permutation.
  gap> nu := RcwaMapping([[1,1,1]]);;                  # n -> n + 1.
  gap> SetName(nu,"nu"); SetName(a,"a"); # For displaying purposes.
  gap> G  := Group(a,nu);
  <rcwa group over Z with 2 generators>
  gap> phi := EpimorphismFromFreeGroup(G);
  [ a, nu ] -> [ a, nu ]
  gap> F := Source(phi);
  <free group on the generators [ a, nu ]>
  gap> w := Comm(F.1^2*F.2^4,F.1*F.2^3);
  nu^-4*a^-2*nu^-3*a*nu^4*a*nu^3
  gap> g := w^phi;
  <bijective rcwa mapping of Z with modulus 8>
  gap> pre := PreImagesRepresentative(phi,g);
  nu^-4*a^-1*nu^-1*a^-1*nu^3*a*nu^-1*a*nu^3
  gap> rel := w/pre; # pre <> w --> We have a nontrivial relation!
  nu^-4*a^-2*nu^-3*a*nu^5*a^-1*nu^-3*a*nu*a*nu^4
  gap> rel := rel^(F.2^-4*F.1^-1); # Cyclically reduced form.
  a^-1*nu^-3*a*nu^5*a^-1*nu^-3*a*nu
  gap> rel^phi;
  IdentityMapping( Integers )
  
\end{Verbatim}
 }

 \pagebreak[4] 

\subsection{\textcolor{Chapter }{PreImagesRepresentatives (phi, g)}}
\logpage{[ 3, 6, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PreImagesRepresentatives( phi, g )\index{PreImagesRepresentatives@\texttt{PreImagesRepresentatives}!phi, g}
\label{PreImagesRepresentatives:phi, g}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 A list of representatives of the set of preimages of~\mbox{\texttt{g}} under the homomorphism~\mbox{\texttt{phi}} from a free group to an rcwa group over~$\mathbb{Z}$. 



 Quite frequently, computing several preimages is not harder than computing
just one, i.e. often several preimages are found simultaneously. This
operation is called by \texttt{PreImagesRepresentative} (\ref{PreImagesRepresentative:phi, g}), which simply chooses the shortest representative. For a slightly more
concise description see there. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> w := Comm(F.1*F.2,Comm(F.1,F.2^2)); # We continue the example above.
  nu^-1*a^-1*nu^-2*a^-1*nu^2*a^2*nu*a^-1*nu^-2*a*nu^2
  gap> g := w^phi;
  <bijective rcwa mapping of Z with modulus 16>
  gap> pre := PreImagesRepresentatives(phi,g);
  [ nu^-1*a^-2*nu^-2*a*nu^2*a*nu^-1*a^-1*nu^2*a,
    nu^-1*a^-1*nu^-2*a^-1*nu^2*a^2*nu^-1*a^-1*nu^2*a ]
  gap> rel := pre[1]/pre[2];
  nu^-1*a^-2*nu^-2*a*nu^2*a^-1*nu^-2*a*nu^2*a*nu
  gap> rel := (rel^(F.2^-1*F.1^-1))^-1; # Cyclically reduced form.
  nu^-2*a^-1*nu^2*a*nu^-2*a^-1*nu^2*a
  gap> rel^phi;
  IdentityMapping( Integers )
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{The action of an rcwa group on the underlying ring}}\label{sec:ActionOnR}
\logpage{[ 3, 7, 0 ]}
{
  \index{Support@\texttt{Support}!G} \index{MovedPoints@\texttt{MovedPoints}!G} The support, i.e. set of moved points, of an rcwa group can be determined by \texttt{Support} or \texttt{MovedPoints} (these are synonyms). Sometimes testing for transitivity on the underlying
ring is feasible. This is e.g. the case for tame groups over~$\Z$. Further it is often possible to determine group elements which map a given
tuple of elements of the underlying ring to a given other tuple, if such
elements exist. 

\subsection{\textcolor{Chapter }{IsTransitive (G, Integers)}}
\logpage{[ 3, 7, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsTransitive( G, Integers )\index{IsTransitive@\texttt{IsTransitive}!G, Integers}
\label{IsTransitive:G, Integers}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} if the rcwa group~\mbox{\texttt{G}} acts transitively on~$\Z$ and \texttt{false} otherwise. 



 If \mbox{\texttt{G}} is wild, this may fail or run into an infinite loop. 
\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}
 }

 \pagebreak[4] 

\subsection{\textcolor{Chapter }{RepresentativeAction (G, src, dest, act)}}
\logpage{[ 3, 7, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RepresentativeAction( G, src, dest, act )\index{RepresentativeAction@\texttt{RepresentativeAction}!G, src, dest, act}
\label{RepresentativeAction:G, src, dest, act}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 An element of \mbox{\texttt{G}} which maps \mbox{\texttt{src}} to~\mbox{\texttt{dest}} under the action given by~\mbox{\texttt{act}}. 



 If an element satisfying this condition does not exist, this method either
returns \texttt{fail} or runs into an infinite loop. The problem to decide whether \mbox{\texttt{src}} and \mbox{\texttt{dest}} lie in the same orbit under the action of \mbox{\texttt{G}} in general seems to be hard. The method is based on \texttt{RepresentativeActionPreImage} (\ref{RepresentativeActionPreImage:G, src, dest, act, F}), and it basically just computes an image under an epimorphism. As this
involves multiplications of rcwa mappings, this can be quite expensive if the
group \mbox{\texttt{G}} is wild, the preimage is a rather long word and coefficient explosion happens
to occur. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; # Collatz' permutation.
  gap> G := Group(a,ClassShift(1,4));
  <rcwa group over Z with 2 generators>
  gap> elm := RepresentativeAction(G,[7,4,9],[4,5,13],OnTuples);
  <bijective rcwa mapping of Z with modulus 12>
  gap> Display(elm);
  
  Bijective rcwa mapping of Z with modulus 12
  
                 n mod 12                |                 n^f
  ---------------------------------------+--------------------------------------
     0  2  3  6  8 11                    | n
     1  7 10                             | n - 3
     4                                   | n + 1
     5  9                                | n + 4
  
  gap> List([7,4,9],n->n^elm);
  [ 4, 5, 13 ]
  gap> elm := RepresentativeAction(G,[5,4,9],[13,5,4],OnTuples);
  <bijective rcwa mapping of Z with modulus 9>
  gap> Display(elm);
  
  Bijective rcwa mapping of Z with modulus 9
  
                  n mod 9                |                 n^f
  ---------------------------------------+--------------------------------------
    0                                    | 4n/9
    1                                    | (8n - 26)/9
    2                                    | (8n + 2)/9
    3                                    | (8n + 3)/9
    4                                    | (16n - 19)/9
    5                                    | (16n + 37)/9
    6                                    | (8n + 33)/9
    7                                    | (16n - 49)/9
    8                                    | (16n + 7)/9
  
  gap> RepresentativeAction(G,[7,4,9],[4,5,8],OnTuples);
  <bijective rcwa mapping of Z with modulus 256>
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{RepresentativeActionPreImage (G, src, dest, act, F)}}
\logpage{[ 3, 7, 3 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RepresentativeActionPreImage( G, src, dest, act, F )\index{RepresentativeActionPreImage@\texttt{RepresentativeActionPreImage}!G, src, dest, act, F}
\label{RepresentativeActionPreImage:G, src, dest, act, F}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The result of \texttt{RepresentativeAction(\mbox{\texttt{G}},\mbox{\texttt{src}},\mbox{\texttt{dest}},\mbox{\texttt{act}})} as word in generators. 



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

 

\subsection{\textcolor{Chapter }{RepresentativeAction (RCWA( Integers ), P1, P2)}}
\logpage{[ 3, 7, 4 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RepresentativeAction( RCWA\_Z, P1, P2 )\index{RepresentativeAction@\texttt{RepresentativeAction}!RCWA( Integers ), P1, P2}
\label{RepresentativeAction:RCWA( Integers ), P1, P2}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 An element of RCWA($\Z$) which maps the partition~\mbox{\texttt{P1}} to~\mbox{\texttt{P2}}. 



 The arguments \mbox{\texttt{P1}} and \mbox{\texttt{P2}} must be partitions of the underlying ring $R$ into the same number of disjoint unions of residue classes. The method
recognizes the option \texttt{IsTame}. If this option is set, the returned mapping is tame provided that there is a
tame mapping which satisfies the given condition. If the option \texttt{IsTame} is not set and the partitions \mbox{\texttt{P1}} and \mbox{\texttt{P2}} both consist entirely of single residue classes, then the returned mapping is
affine on any residue class in~\mbox{\texttt{P1}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> P1 := List([[0,3],[1,3],[2,9],[5,9],[8,9]],ResidueClass);
  [ 0(3), 1(3), 2(9), 5(9), 8(9) ]
  gap> P2 := List([[0,2],[1,8],[5,16],[3,4],[13,16]],ResidueClass);
  [ 0(2), 1(8), 5(16), 3(4), 13(16) ]
  gap> elm := RepresentativeAction(RCWA(Integers),P1,P2);
  <bijective rcwa mapping of Z with modulus 9>
  
\end{Verbatim}
 \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> P1^elm = P2;
  true
  gap> Display(elm);
  
  Bijective rcwa mapping of Z with modulus 9
  
                  n mod 9                |                 n^f
  ---------------------------------------+--------------------------------------
    0 3 6                                | 2n/3
    1 4 7                                | (8n - 5)/3
    2                                    | (16n + 13)/9
    5                                    | (4n + 7)/9
    8                                    | (16n - 11)/9
  
  gap> elm := RepresentativeAction(RCWA(Integers),P1,P2:IsTame);
  <tame bijective rcwa mapping of Z with modulus 1152>
  gap> P := RespectedPartition(elm);;
  gap> Length(P);
  313
  gap> elm := RepresentativeAction(RCWA(Integers),
  >             [ResidueClass(1,3),Union(ResidueClass(0,3),ResidueClass(2,3))],
  >             [Union(ResidueClass(2,5),ResidueClass(4,5)),
  >              Union(ResidueClass(0,5),ResidueClass(1,5),ResidueClass(3,5))]);
  <bijective rcwa mapping of Z with modulus 6>
  gap> [ResidueClass(1,3),Union(ResidueClass(0,3),ResidueClass(2,3))]^elm;
  [ 2(5) U 4(5), Z \ 2(5) U 4(5) ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ShortOrbits (G, S, maxlng)}}
\logpage{[ 3, 7, 5 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ShortOrbits( G, S, maxlng )\index{ShortOrbits@\texttt{ShortOrbits}!G, S, maxlng}
\label{ShortOrbits:G, S, maxlng}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ShortCycles( g, S, maxlng )\index{ShortCycles@\texttt{ShortCycles}!G, S, maxlng}
\label{ShortCycles:G, S, maxlng}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 A list of all finite orbits of the rcwa group~\mbox{\texttt{G}} resp. of all finite cycles of the bijective rcwa mapping \mbox{\texttt{g}} of length at most~\mbox{\texttt{maxlng}} which intersect nontrivially with the set~\mbox{\texttt{S}}. 



 
\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(5),[1..100],20);
  [ [ 1 ], [ 2 ], [ 3 ], [ 4 ], [ 5, 6 ], [ 7, 8 ], 
    [ 9, 10, 12, 14, 16, 13, 11 ], [ 15, 18 ], 
    [ 17, 20, 24, 28, 23, 19, 22, 26, 21 ], 
    [ 45, 54, 64, 76, 61, 49, 58, 47, 56 ], 
    [ 59, 70, 84, 100, 120, 144, 172, 206, 165, 198, 159, 190, 228, 183, 147, 
        176, 141, 113, 91, 73 ] ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Projections (G, m)}}
\logpage{[ 3, 7, 6 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Projections( G, m )\index{Projections@\texttt{Projections}!G, m}
\label{Projections:G, m}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The projections of the rcwa group~\mbox{\texttt{G}} to the unions of residue classes (mod~\mbox{\texttt{m}}) which it fixes setwisely. 



 The corresponding partition of a set of representatives for the residue
classes (mod~\mbox{\texttt{m}}) can be obtained by the operation \texttt{OrbitsModulo(\mbox{\texttt{G}},\mbox{\texttt{m}})}. \index{OrbitsModulo@\texttt{OrbitsModulo}!G, m} 
\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}
 }

 

\subsection{\textcolor{Chapter }{Ball (G, p, d, act)}}
\logpage{[ 3, 7, 7 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Ball( G, p, d, act )\index{Ball@\texttt{Ball}!G, p, d, act}
\label{Ball:G, p, d, act}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Ball( G, g, d )\index{Ball@\texttt{Ball}!G, g, d}
\label{Ball:G, g, d}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 The ball of radius~\mbox{\texttt{d}} around the point~\mbox{\texttt{p}} under the action~\mbox{\texttt{act}} of the group~\mbox{\texttt{G}}, resp. the ball of radius~\mbox{\texttt{d}} around the element~\mbox{\texttt{g}} in the group~\mbox{\texttt{G}}. 



 All balls are understood w.r.t. \texttt{GeneratorsOfGroup(\mbox{\texttt{G}})}. As element tests can be expensive, the latter method does not check whether \mbox{\texttt{g}} is indeed an element of~\mbox{\texttt{G}}. The methods require that point comparisons resp. element comparisons are
cheap. They are not only applicable to rcwa groups. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> PSL2Z := Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(3),
  >                                                    CyclicGroup(2))));
  <wild rcwa group over Z with 2 generators>
  gap> List([1..10],k->Length(Ball(PSL2Z,0,k,OnPoints)));
  [ 3, 4, 6, 8, 12, 16, 24, 32, 48, 64 ]
  gap> List([1..10],k->Length(Ball(PSL2Z,[0,1],k,OnTuples)));
  [ 4, 8, 14, 22, 34, 50, 74, 106, 154, 218 ]
  gap> Ball(Group((1,2),(2,3),(3,4)),(),2);
  [ (), (3,4), (2,3), (2,3,4), (2,4,3), (1,2), (1,2)(3,4), (1,2,3), (1,3,2) ]
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{Conjugacy in RCWA(Z)}}\label{sec:ConjugacyInRCWA_Z}
\logpage{[ 3, 8, 0 ]}
{
  

\subsection{\textcolor{Chapter }{IsConjugate (RCWA(Integers), f, g)}}
\logpage{[ 3, 8, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsConjugate( RCWA(Integers), f, g )\index{IsConjugate@\texttt{IsConjugate}!RCWA(Integers), f, g}
\label{IsConjugate:RCWA(Integers), f, g}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} if the bijective rcwa mappings \mbox{\texttt{f}} and~\mbox{\texttt{g}} are conjugate in RCWA($\Z$), and \texttt{false} otherwise. 



 The author does not know a general way to solve the conjugacy problem for
elements of RCWA($\Z$), thus the method may fail or run into an infinite loop. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> IsConjugate(RCWA(Integers),ClassTransposition(0,2,1,4),
  >                               ClassTransposition(1,2,0,4));
  true
  gap> IsConjugate(RCWA(Integers),ClassTransposition(0,2,1,4),ClassShift(0,1));
  false
  
\end{Verbatim}
 }

 \index{ShortCycles@\texttt{ShortCycles}!f, maxlng} In its 2-argument form, \texttt{ShortCycles(\mbox{\texttt{f}},\mbox{\texttt{maxlng}})} returns a list of all cycles of \mbox{\texttt{f}} of length at most \mbox{\texttt{maxlng}} which do not correspond to cycles consisting of residue classes. The cycles
are sorted by increasing length. If for some value of \mbox{\texttt{maxlng}} the lists \texttt{List(ShortCycles(\mbox{\texttt{f}},\mbox{\texttt{maxlng}}),Length)} and \texttt{List(ShortCycles(\mbox{\texttt{g}},\mbox{\texttt{maxlng}}),Length)} differ, then \mbox{\texttt{f}} and \mbox{\texttt{g}} are clearly not conjugate. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; # Collatz' permutation.
  gap> ShortCycles(a,5);
  [ [ 0 ], [ 1 ], [ -1 ], [ 2, 3 ], [ -3, -2 ], [ 4, 5, 7, 9, 6 ],
    [ -9, -6, -4, -5, -7 ] ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{RepresentativeAction (RCWA(Integers), f, g)}}
\logpage{[ 3, 8, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RepresentativeAction( RCWA(Integers), f, g )\index{RepresentativeAction@\texttt{RepresentativeAction}!RCWA(Integers), f, g}
\label{RepresentativeAction:RCWA(Integers), f, g}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 An rcwa mapping~\texttt{x} such that \texttt{\mbox{\texttt{f}}\texttt{\symbol{94}}x = \mbox{\texttt{g}}}, if such an \texttt{x} exists and \texttt{fail} otherwise. 



 This method may fail for the same reasons as \texttt{IsConjugate} (\ref{IsConjugate:RCWA(Integers), f, g}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> rep := RepresentativeAction(RCWA(Integers),ClassTransposition(0,2,1,4),
  >                                               ClassTransposition(1,2,0,4));
  <bijective rcwa mapping of Z with modulus 32>
  gap> ClassTransposition(0,2,1,4)^rep = ClassTransposition(1,2,0,4); # check
  true
  gap> Factorization(rep);
  [ ClassTransposition(0,2,3,16), ClassTransposition(1,4,11,16),
    ClassTransposition(2,8,3,16), ClassTransposition(6,8,11,16),
    ClassTransposition(1,2,2,8), ClassTransposition(0,4,6,8) ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{NrConjugacyClassesOfRCWAZOfOrder (ord)}}
\logpage{[ 3, 8, 3 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NrConjugacyClassesOfRCWAZOfOrder( ord )\index{NrConjugacyClassesOfRCWAZOfOrder@\texttt{NrConjugacyClassesOfRCWAZOfOrder}!ord}
\label{NrConjugacyClassesOfRCWAZOfOrder:ord}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 The number of conjugacy classes of RCWA($\Z$) of elements of order~\mbox{\texttt{ord}}, as given in Corollary~2.7.1~(b) in~\cite{Kohl05}. 



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> List([2,105],NrConjugacyClassesOfRCWAZOfOrder);
  [ infinity, 218 ]
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{Restriction and induction}}\label{sec:RestrictionAndInduction}
\logpage{[ 3, 9, 0 ]}
{
  There are monomorphisms from the group RCWA($\Z$) into itself. The support of the image of such a monomorphism is the image of
a given injective rcwa mapping. Therefore these monomorphisms are called \emph{restriction monomorphisms}. Taking images of rcwa groups under restrictions by rcwa mappings with
pairwise distinct images permits forming their direct product and their wreath
product with some finite permutation group, regardless of whether they are
tame or not (cp. Section~\ref{sec:DirectProductsAndWreathProducts}). 

\subsection{\textcolor{Chapter }{Restriction (g, f)}}
\logpage{[ 3, 9, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Restriction( g, f )\index{Restriction@\texttt{Restriction}!g, f}
\label{Restriction:g, f}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Restriction( G, f )\index{Restriction@\texttt{Restriction}!G, f}
\label{Restriction:G, f}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The \emph{restriction} of the rcwa mapping \mbox{\texttt{g}} resp. the rcwa group \mbox{\texttt{G}} by the injective rcwa mapping~\mbox{\texttt{f}}. 



 By definition, the restriction $g_f$ of an rcwa mapping \mbox{\texttt{g}} by an injective rcwa mapping~\mbox{\texttt{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{f}} pointwise. If \mbox{\texttt{f}} is bijective, the restriction of \mbox{\texttt{g}} by \mbox{\texttt{f}} is just the conjugate of \mbox{\texttt{g}} under~\mbox{\texttt{f}}. 

 The restriction of an rcwa group~\mbox{\texttt{G}} by an injective rcwa mapping~\mbox{\texttt{f}} is defined as the group whose elements are the restrictions of the elements of~\mbox{\texttt{G}} by~\mbox{\texttt{f}}. The restriction of~\mbox{\texttt{G}} by~\mbox{\texttt{f}} acts on the image of~\mbox{\texttt{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 (g, f)}}
\logpage{[ 3, 9, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Induction( g, f )\index{Induction@\texttt{Induction}!g, f}
\label{Induction:g, f}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Induction( G, f )\index{Induction@\texttt{Induction}!G, f}
\label{Induction:G, f}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 The \emph{induction} of the rcwa mapping \mbox{\texttt{g}} resp. the rcwa group \mbox{\texttt{G}} by the injective rcwa mapping~\mbox{\texttt{f}}. 



 By definition, induction is the right inverse of restriction. This means that
it is \texttt{Induction(Restriction(\mbox{\texttt{g}},\mbox{\texttt{f}}),\mbox{\texttt{f}}) = \mbox{\texttt{g}}} resp. \texttt{Induction(Restriction(\mbox{\texttt{G}},\mbox{\texttt{f}}),\mbox{\texttt{f}}) = \mbox{\texttt{G}}}. The mapping~\mbox{\texttt{g}} resp. the group~\mbox{\texttt{G}} must not move points outside the image of~\mbox{\texttt{f}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Induction(F2tilde,RcwaMapping([[5,3,1]])) = F2;
  true
  
\end{Verbatim}
 }

 }

 \pagebreak[4]  
\section{\textcolor{Chapter }{Getting pseudo-random elements of RCWA(Z)}}\label{sec:Random}
\logpage{[ 3, 10, 0 ]}
{
  \index{Random@\texttt{Random}!RCWA(Z)} There is a method for the operation \texttt{Random} for RCWA($\Z$). This method is 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));
  <bijective rcwa mapping of Z with modulus 60>
  gap> Display(elm);
  
  Bijective rcwa mapping of Z with modulus 12
  
                 n mod 12                |                 n^f
  ---------------------------------------+--------------------------------------
     0  2  4  6  8 10                    | 3n + 2
     1  5  9                             | -n + 2
     3  7                                | (n - 7)/2
    11                                   | (-n + 20)/3
  
  
\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}
 An auxiliary function which is used in this context for choosing the class
transpositions is \texttt{ClassPairs(\mbox{\texttt{m}})}. \index{ClassPairs@\texttt{ClassPairs}!m} This function returns a list of 4-tuples $(r_1,m_1,r_2,m_2)$ of integers corresponding to the pairs of disjoint residue classes $r_1(m_1)$ and $r_2(m_2)$ with $m_1, m_2 \leq m$. 
\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 }{Special attributes for tame rcwa groups}}\label{sec:MethodsForTameGroups}
\logpage{[ 3, 11, 0 ]}
{
  There is a couple of attributes which a priori make only sense for tame rcwa
groups. In the sequel, these attributes are described in detail. 

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

\subsection{\textcolor{Chapter }{RespectedPartition (G)}}
\logpage{[ 3, 11, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RespectedPartition( G )\index{RespectedPartition@\texttt{RespectedPartition}!G}
\label{RespectedPartition:G}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RespectedPartition( g )\index{RespectedPartition@\texttt{RespectedPartition}!g}
\label{RespectedPartition:g}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 A respected partition of the rcwa group \mbox{\texttt{G}} resp. of the rcwa mapping~\mbox{\texttt{g}}. 



 A \emph{respected partition} of~\mbox{\texttt{G}} resp.~\mbox{\texttt{g}} is a partition of the underlying ring~$R$ into a finite number of residue classes on which~\mbox{\texttt{G}} resp. the cyclic group generated by~\mbox{\texttt{g}} acts in a natural way as a permutation group, and on whose elements all
elements of~\mbox{\texttt{G}} resp. all powers of~\mbox{\texttt{g}} are affine. Such a partition exists if and only if \mbox{\texttt{G}} resp. \mbox{\texttt{g}} is tame (see~\cite{Kohl05}, Theorem~2.5.8). 

 \index{RespectedPartitionShort@\texttt{RespectedPartitionShort}!G} \index{RespectedPartitionShort@\texttt{RespectedPartitionShort}!g} \index{RespectedPartitionLong@\texttt{RespectedPartitionLong}!G} \index{RespectedPartitionLong@\texttt{RespectedPartitionLong}!g} Related attributes are \texttt{RespectedPartitionShort} and \texttt{RespectedPartitionLong}. They are used to denote respected partitions consisting of residue classes $r(m)$ where $m$ divides the modulus of~\mbox{\texttt{G}} resp. \mbox{\texttt{g}}, resp. where the modulus of \mbox{\texttt{G}} resp. \mbox{\texttt{g}} divides~$m$. 

 \index{RespectsPartition@\texttt{RespectsPartition}!G} \index{RespectsPartition@\texttt{RespectsPartition}!g} There is an operation \texttt{RespectsPartition(\mbox{\texttt{G}},\mbox{\texttt{P}})} resp. \texttt{RespectsPartition(\mbox{\texttt{g}},\mbox{\texttt{P}})}, which tests whether \mbox{\texttt{G}} resp.~\mbox{\texttt{g}} respects a given partition~\mbox{\texttt{P}}. The permutation induced by \mbox{\texttt{g}} on~\texttt{P} can be computed efficiently using \texttt{PermutationOpNC(\mbox{\texttt{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 (G)}}
\logpage{[ 3, 11, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ActionOnRespectedPartition( G )\index{ActionOnRespectedPartition@\texttt{ActionOnRespectedPartition}!G}
\label{ActionOnRespectedPartition:G}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 The action of the tame rcwa group~\mbox{\texttt{G}} on \texttt{RespectedPartition(\mbox{\texttt{G}})}. 



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> H := ActionOnRespectedPartition(G);
  Group([ (3,7)(5,8), (3,4,5,6) ])
  gap> H = Action(G,P);
  true
  gap> StructureDescription(H);
  "C2 x S4"
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{KernelOfActionOnRespectedPartition (G)}}
\logpage{[ 3, 11, 3 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{KernelOfActionOnRespectedPartition( G )\index{KernelOfActionOnRespectedPartition@\texttt{KernelOfActionOnRespectedPartition}!G}
\label{KernelOfActionOnRespectedPartition:G}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RankOfKernelOfActionOnRespectedPartition( G )\index{RankOfKernelOfActionOnRespectedPartition@\texttt{RankOfKernelOfActionOnRespectedPartition}!G}
\label{RankOfKernelOfActionOnRespectedPartition:G}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 The kernel of the action of the tame rcwa group~\mbox{\texttt{G}} on \texttt{RespectedPartition(\mbox{\texttt{G}})}, resp. the rank of the largest free abelian subgroup of this kernel. 



 The method for \texttt{KernelOfActionOnRespectedPartition} uses the package \textsf{Polycyclic}~\cite{Polycyclic}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> K := KernelOfActionOnRespectedPartition(G);
  <rcwa group over Z with 3 generators>
  gap> RankOfKernelOfActionOnRespectedPartition(G);
  3
  gap> Index(G,K);
  48
  gap> List(GeneratorsOfGroup(K),Factorization);
  [ [ ClassShift(0,4)^2 ], [ ClassShift(2,4)^2 ], [ ClassShift(1,6)^2 ] ]
  gap> IsomorphismPcpGroup(K);
  [ <bijective rcwa mapping of Z with modulus 4>,
    <bijective rcwa mapping of Z with modulus 4>,
    <bijective rcwa mapping of Z with modulus 6> ] -> [ g6*g10, g8*g12, g14*g16
   ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IntegralConjugate (G)}}
\logpage{[ 3, 11, 4 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IntegralConjugate( G )\index{IntegralConjugate@\texttt{IntegralConjugate}!G}
\label{IntegralConjugate:G}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IntegralConjugate( g )\index{IntegralConjugate@\texttt{IntegralConjugate}!g}
\label{IntegralConjugate:g}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 Some integral conjugate of the tame rcwa group~\mbox{\texttt{G}} resp. of the tame bijective rcwa mapping~\mbox{\texttt{g}} in the group RCWA($\Z$). 



 Such conjugates exist, see~\cite{Kohl05}, Theorem~2.5.14. In general there are infinitely many of them. An rcwa mapping mapping~\mbox{\texttt{x}} such that \texttt{\mbox{\texttt{G}}\texttt{\symbol{94}}\mbox{\texttt{x}}=IntegralConjugate(\mbox{\texttt{G}})} resp. \texttt{\mbox{\texttt{g}}\texttt{\symbol{94}}\mbox{\texttt{x}}=IntegralConjugate(\mbox{\texttt{g}})} is stored as an attribute \texttt{IntegralizingConjugator}. \index{IntegralizingConjugator@\texttt{IntegralizingConjugator}!G} \index{IntegralizingConjugator@\texttt{IntegralizingConjugator}!g} 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> IsIntegral(IntegralConjugate(G));
  true
  gap> G^IntegralizingConjugator(G) = IntegralConjugate(G);
  true
  gap> RespectedPartition(G);
  [ 3(6), 5(6), 0(8), 2(8), 4(8), 6(8), 1(12), 7(12) ]
  gap> RespectedPartition(G)^IntegralizingConjugator(G);
  [ 0(8), 1(8), 2(8), 3(8), 4(8), 5(8), 6(8), 7(8) ]
  gap> last = RespectedPartition(IntegralConjugate(G));
  true
  
\end{Verbatim}
 \pagebreak[4] 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Display(IntegralizingConjugator(G));
  
  Bijective rcwa mapping of Z with modulus 24
  
                 n mod 24                |                 n^f
  ---------------------------------------+--------------------------------------
     0  8 16                             | n + 2
     1 13                                | (2n + 16)/3
     2 10 18                             | n + 1
     3  9 15 21                          | (4n - 12)/3
     4 12 20                             | n
     5 11 17 23                          | (4n - 17)/3
     6 14 22                             | n - 1
     7 19                                | (2n + 7)/3
  
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{Some general utility functions}}\label{sec:UtilityFunctions}
\logpage{[ 3, 12, 0 ]}
{
  \index{GeneratorsAndInverses@\texttt{GeneratorsAndInverses}!G} \index{EpimorphismByGenerators@\texttt{EpimorphismByGenerators}!G, H} \index{AllProducts@\texttt{AllProducts}!l, k} \textsf{RCWA} introduces a few small utility functions which can be used for groups in
general: The function \texttt{GeneratorsAndInverses(\mbox{\texttt{G}})} returns a list of generators of \mbox{\texttt{G}} and their inverses, \texttt{EpimorphismByGenerators(\mbox{\texttt{G}},\mbox{\texttt{H}})} is a shorthand for \texttt{GroupHomomorphismByImages(\mbox{\texttt{G}},\mbox{\texttt{H}}, GeneratorsOfGroup(\mbox{\texttt{G}}),GeneratorsOfGroup(\mbox{\texttt{H}}))} (there is also an \texttt{NC} version of this) and the function \texttt{AllProducts(\mbox{\texttt{l}},\mbox{\texttt{k}})} returns the list of all products of \mbox{\texttt{k}} entries of the list~\mbox{\texttt{l}}. }

  
\section{\textcolor{Chapter }{The categories of rcwa groups}}\label{sec:CategoriesOfRcwaGroups}
\logpage{[ 3, 13, 0 ]}
{
  

\subsection{\textcolor{Chapter }{IsRcwaGroup (G)}}
\logpage{[ 3, 13, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaGroup( G )\index{IsRcwaGroup@\texttt{IsRcwaGroup}!G}
\label{IsRcwaGroup:G}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaGroupOverZ( G )\index{IsRcwaGroupOverZ@\texttt{IsRcwaGroupOverZ}!G}
\label{IsRcwaGroupOverZ:G}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaGroupOverZ\_pi( G )\index{IsRcwaGroupOverZpi@\texttt{IsRcwaGroupOverZ\_pi}!G}
\label{IsRcwaGroupOverZpi:G}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRcwaGroupOverGFqx( G )\index{IsRcwaGroupOverGFqx@\texttt{IsRcwaGroupOverGFqx}!G}
\label{IsRcwaGroupOverGFqx:G}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} if \mbox{\texttt{G}} is an rcwa group resp. an rcwa group over the ring of integers resp. an rcwa
group over a semilocalization of the ring of integers resp. an rcwa group over
a polynomial ring in one variable over a finite field, and \texttt{false} otherwise. 



 \index{IsRcwaGroupOverZOrZ_pi@\texttt{IsRcwaGroupOverZOrZ{\textunderscore}pi}!G} 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_Z@\texttt{IsNaturalRCWA{\textunderscore}Z}!G} \index{IsNaturalRCWA_Z_pi@\texttt{IsNaturalRCWA{\textunderscore}Z{\textunderscore}pi}!G} \index{IsNaturalRCWA_GFqx@\texttt{IsNaturalRCWA{\textunderscore}GFqx}!G} To allow distinguishing the entire group RCWA($R$) from others by means of the method selection, it has the characteristic
property \texttt{IsNaturalRCWA{\textunderscore}Z} resp. one of the properties \texttt{IsNaturalRCWA{\textunderscore}Z{\textunderscore}pi} or \texttt{IsNaturalRCWA{\textunderscore}GFqx}, depending on whether $R$ is the ring of integers, one of its semilocalizations or a univariate
polynomial ring over a finite field. }

 }

  }

         
\chapter{\textcolor{Chapter }{Examples}}\label{ch:Examples}
\logpage{[ 4, 0, 0 ]}
{
 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. 

 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{[ 4, 1, 0 ]}
{
  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
  
  
\end{Verbatim}
 This permutation has a few finite cycles: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> ShortCycles(Collatz,[-50..50],50);
  [ [ -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~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> Length(Factorization(Collatz));
  212
  
\end{Verbatim}
 Setting the Info level of \texttt{InfoRCWA} equal to~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~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.~\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{[ 4, 2, 0 ]}
{
  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 proven 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~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~\texttt{T} is contracting essentially easier -- even for mappings with much shorter
trajectories than~\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{[ 4, 3, 0 ]}
{
  In \cite{Andaloro00}, P.~Andaloro has shown that proving that trajectories of integers $n \in 1(16)$ under the Collatz mapping always contain~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~$T$ contains $\Z \setminus 0(3)$ is obviously enough. Thus we put $S := 1(16)$, and successively unite the set~$S$ with its image under~$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~\ref{sec:CollatzImagesAndPreImages}. }

 \pagebreak[4]  
\section{\textcolor{Chapter }{Two examples by Matthews and Leigh}}\label{sec:MatthewsLeighExamples}
\logpage{[ 4, 4, 0 ]}
{
  In \cite{MatthewsLeigh87}, K.~R.~Matthews and G.~M.~Leigh have shown that two trajectories of the following (surjective, but not
injective) mappings are acyclic (mod~$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~mod~$x$ and 1~mod~$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{[ 4, 5, 0 ]}
{
  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~\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{[ 4, 6, 0 ]}
{
  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~$\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{[ 4, 7, 0 ]}
{
  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~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~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{[ 4, 8, 0 ]}
{
  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{a}},\mbox{\texttt{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{a}},\mbox{\texttt{b}}] and [\mbox{\texttt{a}},\mbox{\texttt{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{G}} is isomorphic to the symmetric group on 10~points and acts faithfully on the orbit containing~1. Another question is which groups arise if we take as generators either \mbox{\texttt{ab}}, \mbox{\texttt{ac}} or \mbox{\texttt{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{ab}} and \mbox{\texttt{t}} is isomorphic to ${\rm C}_2 \times {\rm S}_{10}$ . The next group is an extension of a perfect group of order~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{[ 4, 9, 0 ]}
{
  Is the group generated by the permutations \mbox{\texttt{a}} and \mbox{\texttt{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~\mbox{\texttt{U}} which acts on a finite set~\mbox{\texttt{S}} of integers, and which induces on~\mbox{\texttt{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{U}} induces on \mbox{\texttt{S}} a natural symmetric group of degree~6. Therefore the group~\mbox{\texttt{G}} is not solvable, as claimed. We conclude this example by factoring the group
element \mbox{\texttt{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{[ 4, 10, 0 ]}
{
  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{[ 4, 11, 0 ]}
{
  We define an rcwa mapping \mbox{\texttt{x}} of order~257 with modulus~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{[ 4, 12, 0 ]}
{
  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{[ 4, 13, 0 ]}
{
  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 is setwisely stabilized by $T$. Now we would like to determine the preimages of 1(3) resp. 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~$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~3 under~$T^6$. This means that it would be sufficient to prove the $3n+1$ Conjecture for multiples of~3. We can obtain the corresponding result for multiples of~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{[ 4, 14, 0 ]}
{
  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~1 contains also all other positive integers less than or equal to~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~to~do''. The approach taken here is to show that the stabilizer of~1 in~$G$ acts transitively on the set of positive integers greater than~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~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~2. Obviously, it is sufficient to check that any integer greater than~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~1 lies in the same orbit under the action of the stabilizer of~1 in~$G$ as~2, thus that this stabilizer acts transitively on $\mathbb{N} \setminus \{1\}$. But this means that we have established the 2-transitivity of the action of $G$ on~$\mathbb{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~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{[ 4, 15, 0 ]}
{
  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~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~1 under the action of the stabilizer of~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~4). Since $n$~mod~8 determines the image of $n$ under a generator of $G$ (mod~4), it suffices to compute (mod~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{[ 4, 16, 0 ]}
{
  In this section, we show how to construct finite quotients of the two infinite
periodic groups introduced by Rostislav Grigorchuk in~\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~\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{[ 4, 17, 0 ]}
{
  The $3n+1$ Conjecture asserts that the forward orbit of any positive integer under the
Collatz mapping $T$ contains~1. In contrast, it seems likely that ``most'' trajectories of the two mappings  
\[ T_5^\pm: \ \mathbb{Z} \longrightarrow \mathbb{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~$T_5^+$ indeed contains~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~$f$ of $k$~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''~$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~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~1 by successively computing preimages of~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{[ 4, 18, 0 ]}
{
  The free group of rank~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.~\cite{LaHarpe00}, page~27) from PSL(2,$\mathbb{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:G}) to embed free groups of any rank~$\geq 2$. 

 We give another only slightly different representation of the free group of
rank~2. We verify that it really is one by applying the so-called \emph{Table-Tennis Lemma} (see e.g.~\cite{LaHarpe00}, Section~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~4 may help understanding what is actually done in this calculation. It is easy
to see that the group generated by \texttt{r1} and~\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{[ 4, 19, 0 ]}
{
  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{[ 5, 0, 0 ]}
{
  This chapter lists brief descriptions of most 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. 
\begin{description}
\item[{ \texttt{ActionOnRespectedPartition(\mbox{\texttt{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{G}},\mbox{\texttt{g}},\mbox{\texttt{d}})} }]  ``Straightforward''. 
\item[{ \texttt{Ball(\mbox{\texttt{G}},\mbox{\texttt{p}},\mbox{\texttt{d}},\mbox{\texttt{act}})} }]  ``Straightforward''. 
\item[{ \texttt{ClassReflection(\mbox{\texttt{r}},\mbox{\texttt{m}})} }]  ``Trivial''. 
\item[{ \texttt{ClassShift(\mbox{\texttt{r}},\mbox{\texttt{m}})} }]  ``Trivial''. 
\item[{ \texttt{ClassTransposition(\mbox{\texttt{r1}},\mbox{\texttt{m1}},\mbox{\texttt{r2}},\mbox{\texttt{m2}})} }]  ``Trivial''. 
\item[{ \texttt{Coefficients(\mbox{\texttt{f}})} }]  ``Trivial''. 
\item[{ \texttt{CommonRightInverse(\mbox{\texttt{l}},\mbox{\texttt{r}})} }]  (See \texttt{RightInverse}.) 
\item[{ \texttt{DecreasingOn(\mbox{\texttt{f}})} }]  Forms the union of the residue classes which are determined by the
coefficients as indicated. 
\item[{ \texttt{Determinant(\mbox{\texttt{g}})} }]  Evaluation of the given expression. For the mathematical meaning
(epimorphism!), see Theorem~2.11.9 in~\cite{Kohl05}. 
\item[{ \texttt{DirectProduct(\mbox{\texttt{G1}},\mbox{\texttt{G2}}, ... )} }]  Restricts the groups \mbox{\texttt{G1}}, \mbox{\texttt{G2}}, ... to disjoint residue classes. See \texttt{Restriction} and Corollary~2.3.3 in~\cite{Kohl05}. 
\item[{ \texttt{Display(\mbox{\texttt{f}})} }]  ``Trivial''. 
\item[{ \texttt{Divisor(\mbox{\texttt{f}})} }]  Lcm of coefficients, as indicated. 
\item[{ \texttt{FactorizationIntoCSCRCT(\mbox{\texttt{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{f}},\mbox{\texttt{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{f}})} }]  ``Straightforward''. 
\item[{ \texttt{GuessedDivergence(\mbox{\texttt{f}})} }]  Numerical computation of the limit of some series, which seems to converge ``often''. Caution!!! 
\item[{ \texttt{Image(\mbox{\texttt{f}})}, \texttt{Image(\mbox{\texttt{f}},\mbox{\texttt{S}})} }]  ``Straightforward'' if one can compute images of residue classes under affine mappings and unite
and intersect residue classes (Chinese Remainder Theorem). See Lemma~1.2.1 in~\cite{Kohl05}. 
\item[{ \texttt{ImageDensity(\mbox{\texttt{f}})} }]  Evaluation of the given expression. 
\item[{ \texttt{\mbox{\texttt{g}} in \mbox{\texttt{G}}} (membership test) }]  Test whether the mapping \mbox{\texttt{g}} or its inverse is in the list of generators of~\mbox{\texttt{G}}. If it is, return \texttt{true}. Test whether its prime set is a subset of the prime set of~\mbox{\texttt{G}}. If not, return \texttt{false}. Test whether the multiplier or the divisor of~\mbox{\texttt{g}} has a prime factor which does not divide the multiplier of~\mbox{\texttt{G}}. If yes, return \texttt{false}. Test if \mbox{\texttt{G}} is class-wise order-preserving, and \mbox{\texttt{g}} is not. If so, return \texttt{false}. Test if the sign of \mbox{\texttt{g}} is~-1 and all generators of~\mbox{\texttt{G}} have sign~1. If yes, return \texttt{false}. Test if \mbox{\texttt{G}} is class-wise order-preserving, all generators of~\mbox{\texttt{G}} have determinant~0 and \mbox{\texttt{g}} has determinant~$\neq 0$. If yes, return \texttt{false}. Test whether the support of~\mbox{\texttt{g}} is a subset of the support of~\mbox{\texttt{G}}. If not, return \texttt{false}. Test whether \mbox{\texttt{G}} fixes the nonnegative integers setwisely, but~\mbox{\texttt{g}} does not. If yes, return \texttt{false}. 

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

 If \mbox{\texttt{G}} is not tame, proceed as follows: Look for finite orbits of~\mbox{\texttt{G}}. If some are found, test whether \mbox{\texttt{g}} acts on them, and whether the induced permutations lie in the permutation
groups induced by~\mbox{\texttt{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~$m$ such that \mbox{\texttt{g}} does not leave a partition of~$\Z$ into unions of residue classes (mod~$m$) invariant which is fixed by~\mbox{\texttt{G}}. If successful, return \texttt{false}. If not, try to factor \mbox{\texttt{g}} into generators of~\mbox{\texttt{G}} using \texttt{PreImagesRepresentative}. If successful, return \texttt{true}. If \mbox{\texttt{g}} is in \mbox{\texttt{G}}, this terminates after a finite number of steps. Both runtime and memory
requirements are exponential in the word length. If \mbox{\texttt{g}} is not in \mbox{\texttt{G}}, the method runs into an infinite loop. 
\item[{ \texttt{IncreasingOn(\mbox{\texttt{f}})} }]  Forms the union of the residue classes which are determined by the
coefficients as indicated. 
\item[{ \texttt{Induction(\mbox{\texttt{g}},\mbox{\texttt{f}})} }]  Computes \texttt{f * g * RightInverse(\mbox{\texttt{f}})}. 
\item[{ \texttt{Induction(\mbox{\texttt{G}},\mbox{\texttt{f}})} }]  Gets a set of generators by applying \texttt{Induction(\mbox{\texttt{g}},\mbox{\texttt{f}})} to the generators \mbox{\texttt{g}} of~\mbox{\texttt{G}}. 
\item[{ \texttt{InjectiveAsMappingFrom(\mbox{\texttt{f}})} }]  The function starts with the entire source of \mbox{\texttt{f}} as ``preimage'' \texttt{pre} and the empty set as ``image''~\texttt{im}. It loops over the residue classes (mod~\texttt{Mod(\mbox{\texttt{f}})}). For any such residue class \texttt{cl} the following is done: Firstly, the image of \texttt{cl} under~\mbox{\texttt{f}} is added to~\texttt{im}. Secondly, the intersection of the preimage of the intersection of the image
of \texttt{cl} under \mbox{\texttt{f}} and \texttt{im} under \mbox{\texttt{f}} and \texttt{cl} is subtracted from~\texttt{pre}. 
\item[{ \texttt{IntegralConjugate(\mbox{\texttt{f}})}, \texttt{IntegralConjugate(\mbox{\texttt{G}})} }]  Uses the algorithm described in the proof of Theorem~2.5.14 in~\cite{Kohl05}. 
\item[{ \texttt{IntegralizingConjugator(\mbox{\texttt{f}})}, \texttt{IntegralizingConjugator(\mbox{\texttt{G}})} }]  Uses the algorithm described in the proof of Theorem~2.5.14 in~\cite{Kohl05}. 
\item[{ \texttt{Inverse(\mbox{\texttt{f}})} }]  Essentially inversion of affine mappings. See Lemma~1.3.1, Part~(b) in~\cite{Kohl05}. 
\item[{ \texttt{IsClassWiseOrderPreserving(\mbox{\texttt{f}})} }]  Tests whether the first entry of all coefficient triples is positive. 
\item[{ \texttt{IsConjugate(RCWA(Integers),\mbox{\texttt{f}},\mbox{\texttt{g}})} }]  Test whether \mbox{\texttt{f}} and \mbox{\texttt{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~2.5.14 in~\cite{Kohl05} to construct integral conjugates of \mbox{\texttt{f}} and \mbox{\texttt{g}}. Then essentially use the algorithm described in the proof of Theorem~2.6.7 in~\cite{Kohl05} to compute ``standard representatives'' of the conjugacy classes which the integral conjugates of \mbox{\texttt{f}} and \mbox{\texttt{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{f}})} }]  See \texttt{Image}. 
\item[{ \texttt{IsIntegral(\mbox{\texttt{f}})} }]  ``Trivial''. 
\item[{ \texttt{IsomorphismMatrixGroup(\mbox{\texttt{G}})} }]  Uses the algorithm described in the proof of Theorem~2.6.3 in~\cite{Kohl05}. 
\item[{ \texttt{IsomorphismPermGroup(\mbox{\texttt{G}})} }]  If the group \mbox{\texttt{G}} is infinite, there is no isomorphism to a finite permutation group, thus
return \texttt{fail}. Otherwise use \texttt{ActionOnRespectedPartition}. 
\item[{ \texttt{IsomorphismRcwaGroup(\mbox{\texttt{G}})} }]  The method for finite groups uses \texttt{RcwaMapping}, Part~(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~II.B. in~\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} = \mathbb{Z} \setminus r(m)$. 

 The method for free groups uses an adaptation of the construction given on
page~27 in~\cite{LaHarpe00} from PSL(2,$\mathbb{C}$) to RCWA($\mathbb{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{IsSurjective(\mbox{\texttt{f}})} }]  See \texttt{Image}. 
\item[{ \texttt{IsTame(\mbox{\texttt{G}})} }]  Checks whether the modulus of the group is non-zero. 
\item[{ \texttt{IsTame(\mbox{\texttt{f}})} }]  Application of the criteria given in Corollary~2.5.10 and~2.5.12 and Theorem~A.8 and~A.11 in~\cite{Kohl05}. The criterion ``surjective, but not injective means wild'' (Theorem~A.8 in~\cite{Kohl05}) is the subject of~\cite{Kohl06a}. For applying the criterion of the existence of weakly-connected components
of the transition graph which are not strongly-connected (Theorem~A.11 in~\cite{Kohl05}), the package \textsf{GRAPE} is needed. 

 In addition, some probabilistic methods are used. If the result depends on one
of these, a warning is displayed. 
\item[{ \texttt{IsTransitive(\mbox{\texttt{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{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{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: 

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

 If it terminates: If $S = \mathbb{Z}$, return \texttt{true}, otherwise return \texttt{false}. 
\item[{ \texttt{KernelOfActionOnRespectedPartition(\mbox{\texttt{G}})} }]  First determine the abelian invariants of the kernel~\texttt{K}. For this, compute sufficiently many quotients of orders of permutation
groups induced by~\mbox{\texttt{G}} on refinements of the stored respected partition~\texttt{P} by the order of the permutation group induced by~\mbox{\texttt{G}} on~\texttt{P} itself. Then use a random walk through the group \mbox{\texttt{G}}. Compute powers of elements encountered along the way which fix~\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 in this group). Use \textsf{Polycyclic}~\cite{Polycyclic} to collect independent ``nice'' generators of~\texttt{K}. Proceed until the permutation groups induced by~\texttt{K} on the refined respected partitions all equal the initially stored quotients. 
\item[{ \texttt{LargestSourcesOfAffineMappings(\mbox{\texttt{f}})} }]  Forms unions of residue classes modulo the modulus of the mapping, whose
corresponding coefficient triples are equal. 
\item[{ \texttt{LaTeXObj(\mbox{\texttt{f}})} }]  Collects residue classes those corresponding coefficient triples are equal. 
\item[{ \texttt{LikelyContractionCentre(\mbox{\texttt{f}},\mbox{\texttt{maxn}},\mbox{\texttt{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{f}},\mbox{\texttt{p}})} }]  ``Trivial''. 
\item[{ \texttt{mKnot(\mbox{\texttt{m}})} }]  ``Straightforward'', following the definition given in \cite{Keller99}. 
\item[{ \texttt{Modulus(\mbox{\texttt{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{f}})} }]  ``Trivial''. 
\item[{ \texttt{MovedPoints(\mbox{\texttt{G}})} }]  Needs only forming unions of residue classes and determining fixed points of
affine mappings. 
\item[{ \texttt{Multiplier(\mbox{\texttt{f}})} }]  Lcm of coefficients, as indicated. 
\item[{ \texttt{Multpk(\mbox{\texttt{f}},\mbox{\texttt{p}},\mbox{\texttt{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{ord}})} }]  The class numbers are taken from Corollary~2.7.1 in~\cite{Kohl05}. 
\item[{ \texttt{OrbitsModulo(\mbox{\texttt{f}},\mbox{\texttt{m}})} }]  Uses \textsf{GRAPE} to compute the connected components of the transition graph. 
\item[{ \texttt{OrbitsModulo(\mbox{\texttt{G}},\mbox{\texttt{m}})} }]  ``Straightforward''. 
\item[{ \texttt{Order(\mbox{\texttt{f}})} }]  Test for \texttt{IsTame}. If the mapping is not tame, then return \texttt{infinity}. Otherwise use Corollary~2.5.10 in~\cite{Kohl05}. 
\item[{ \texttt{PreImage(\mbox{\texttt{f}},\mbox{\texttt{S}})} }]  See \texttt{Image}. 
\item[{ \texttt{PreImagesRepresentative(\mbox{\texttt{phi}},\mbox{\texttt{g}})}, \texttt{PreImagesRepresentatives(\mbox{\texttt{phi}},\mbox{\texttt{g}})} }]  As indicated in the documentation of these methods. The underlying idea to
successively compute two balls around~1 and~\mbox{\texttt{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{f}})}, \texttt{PrimeSet(\mbox{\texttt{G}})} }]  ``Straightforward''. 
\item[{ \texttt{PrimeSwitch(\mbox{\texttt{p}})} }]  Multiplication of rcwa mappings as indicated. 
\item[{ \texttt{Print(\mbox{\texttt{f}})} }]  ``Trivial''. 
\item[{ \texttt{\mbox{\texttt{f}}*\mbox{\texttt{g}}} }]  Essentially composition of affine mappings. See Lemma~1.3.1, Part~(a) in~\cite{Kohl05}. 
\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{G}})} }]  This performs basically the first part of the computations done by \texttt{KernelOfActionOnRespectedPartition}. 
\item[{ \texttt{RCWA(\mbox{\texttt{R}})} }]  Attributes are set according to Theorem~2.1.1, Theorem~2.1.2, Corollary~2.1.6 and Theorem~2.12.8 in~\cite{Kohl05}. 
\item[{ \texttt{RcwaGroupByPermGroup(\mbox{\texttt{G}})} }]  Uses \texttt{RcwaMapping}, Part~(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~2.1.4 in~\cite{Kohl05}. 
\item[{ \texttt{RepresentativeAction(\mbox{\texttt{G}},\mbox{\texttt{src}},\mbox{\texttt{dest}},\mbox{\texttt{act}})}, \texttt{RepresentativeActionPreImage} }]  As indicated in the documentation of these methods. The underlying idea to
successively compute two balls around \mbox{\texttt{src}} and \mbox{\texttt{dest}} until they intersect non-trivially is standard in computational group theory.
Words standing for products of generators of \mbox{\texttt{G}} are stored for any image of \mbox{\texttt{src}} or \mbox{\texttt{dest}}. 
\item[{ \texttt{RepresentativeAction(\mbox{\texttt{G}},\mbox{\texttt{P1}},\mbox{\texttt{P2}})} }]  Arbitrary mapping: see Lemma~2.1.4 in~\cite{Kohl05}. Tame mapping: see proof of Theorem~2.8.9 in~\cite{Kohl05}. The former is almost trivial, while the latter is a bit complicate and takes
usually also much more time. 
\item[{ \texttt{RepresentativeAction(RCWA(Integers),\mbox{\texttt{f}},\mbox{\texttt{g}})} }]  The algorithm used by \texttt{IsConjugate} constructs actually also an element \texttt{x} such that \texttt{\mbox{\texttt{f}}\texttt{\symbol{94}}x = \mbox{\texttt{g}}}. 
\item[{ \texttt{RespectedPartition(\mbox{\texttt{f}})}, \texttt{RespectedPartition(\mbox{\texttt{G}})} }]  Uses the algorithm described in the proof of Theorem~2.5.8 in~\cite{Kohl05}. 
\item[{ \texttt{Restriction(\mbox{\texttt{g}},\mbox{\texttt{f}})} }]  Computes the action of \texttt{RightInverse(\mbox{\texttt{f}}) * g * f} on the image of~\mbox{\texttt{f}}. 
\item[{ \texttt{Restriction(\mbox{\texttt{G}},\mbox{\texttt{f}})} }]  Gets a set of generators by applying \texttt{Restriction(\mbox{\texttt{g}},\mbox{\texttt{f}})} to the generators \mbox{\texttt{g}} of~\mbox{\texttt{G}}. 
\item[{ \texttt{RightInverse(\mbox{\texttt{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{f}},\mbox{\texttt{k}})} }]  If \mbox{\texttt{f}} is bijective, class-wise order-preserving and has finite order: 

 Find a conjugate of \mbox{\texttt{f}} which is a product of class transpositions. Slice cycles $\prod_{i=2}^l \tau_{r_1(m_1),r_i(m_i)}$ of~\mbox{\texttt{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{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~$km_i$). Finally conjugate the resulting permutation back. 

 Other cases seem to be more difficult and are currently not covered. 
\item[{ \texttt{SemilocalizedRcwaMapping(\mbox{\texttt{f}},\mbox{\texttt{pi}})} }]  ``Trivial''. 
\item[{ \texttt{ShortCycles(\mbox{\texttt{f}},\mbox{\texttt{maxlng}})} }]  Looks for fixed points of affine partial mappings of powers of~\mbox{\texttt{f}}. 
\item[{ \texttt{ShortOrbits(\mbox{\texttt{G}},\mbox{\texttt{S}},\mbox{\texttt{maxlng}})} }]  ``Straightforward''. 
\item[{ \texttt{SetOnWhichMappingIsClassWiseOrderPreserving(\mbox{\texttt{f}})}, etc. }]  Forms the union of the residue classes modulo the modulus of the mapping, in
whose corresponding coefficient triple the first entry is positive, zero resp.
negative. 
\item[{ \texttt{Sign(\mbox{\texttt{g}})} }]  Evaluation of the given expression. For the mathematical meaning
(epimorphism!), see Theorem~2.12.8 in~\cite{Kohl05}. 
\item[{ \texttt{Size(\mbox{\texttt{G}})} }]  Test whether one of the generators of the group~\mbox{\texttt{G}} has infinite order. If so, return \texttt{infinity}. Test whether the group \mbox{\texttt{G}} is tame. If not, return \texttt{infinity}. Test whether \texttt{RankOfKernelOfActionOnRespectedPartition(\mbox{\texttt{G}})} is nonzero. If so, return \texttt{infinity}. Otherwise if \mbox{\texttt{G}} is class-wise order-preserving, return the size of the permutation group
induced on the stored respected partition. If \mbox{\texttt{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{StructureDescription(\mbox{\texttt{G}})} }]  (Not described here.) 
\item[{ \texttt{\mbox{\texttt{f}}+\mbox{\texttt{g}}} }]  Pointwise addition of affine mappings. 
\item[{ \texttt{Trajectory(\mbox{\texttt{f}},\mbox{\texttt{n}},...)} }]  Iterated application of an rcwa mapping. In the methods computing ``accumulated coefficients'' additionally composition of affine mappings. 
\item[{ \texttt{TransitionGraph(\mbox{\texttt{f}},\mbox{\texttt{m}})} }]  ``Straightforward'' -- just check a sufficiently long interval. 
\item[{ \texttt{TransitionMatrix(\mbox{\texttt{f}},\mbox{\texttt{m}})} }]  Evaluation of the given expression. 
\item[{ \texttt{ViewObj(\mbox{\texttt{f}})} }]  ``Trivial''. 
\item[{ \texttt{WreathProduct(\mbox{\texttt{G}},\mbox{\texttt{P}})} }]  Uses \texttt{DirectProduct} to embed the \texttt{DegreeAction(\mbox{\texttt{P}})}th direct power of~\mbox{\texttt{G}}, and \texttt{RcwaMapping}, Part~(d) to embed the finite permutation group~\mbox{\texttt{P}}. 
\item[{ \texttt{WreathProduct(\mbox{\texttt{G}},\mbox{\texttt{Z}})} }]  Restricts \mbox{\texttt{G}} to the residue class~3(4), and encodes the generator of~\mbox{\texttt{Z}} as $\tau_{0(2),1(2)} \cdot \tau_{0(2),1(4)}$. It is used that the images of~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{[ 6, 0, 0 ]}
{
   
\section{\textcolor{Chapter }{Requirements}}\label{sec:Requirements}
\logpage{[ 6, 1, 0 ]}
{
  The \textsf{RCWA} package needs at least \textsf{GAP}~4.4.7, \textsf{ResClasses}~2.3.5, \textsf{GRAPE}~4.0~\cite{GRAPE}, \textsf{Polycyclic}~1.1~\cite{Polycyclic} and \textsf{GAPDoc}~0.999~\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 when \textsf{GRAPE} is loaded can savely be ignored. }

  
\section{\textcolor{Chapter }{Installation}}\label{sec:Installation}
\logpage{[ 6, 2, 0 ]}
{
  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{[ 6, 3, 0 ]}
{
  

\subsection{\textcolor{Chapter }{InfoRCWA}}
\logpage{[ 6, 3, 1 ]}\nobreak
{\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{n}}\texttt{)} is a shorthand for \texttt{SetInfoLevel(InfoRCWA},\mbox{\texttt{n}}\texttt{)}. \index{RCWAInfo@\texttt{RCWAInfo}} }

 }

  
\section{\textcolor{Chapter }{The testing routine}}\label{sec:TheTestingRoutine}
\logpage{[ 6, 4, 0 ]}
{
  

\subsection{\textcolor{Chapter }{RCWATest}}
\logpage{[ 6, 4, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RCWATest(  )\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{[ 6, 5, 0 ]}
{
  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{[ 6, 5, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RCWABuildManual(  )\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}, DVI, Postscript, PDF, HTML and ASCII text. This is accomplished using the \textsf{GAPDoc} package by Frank Lübeck and Max Neunhöffer. Building the manual is possible
only on UNIX systems and requires {\LaTeX}, PDF{\LaTeX} and \textsf{dvips}. }

 }

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

\bibliographystyle{alpha}
\bibliography{rcwa.bib}

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


\printindex

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