Quelle  main.tex

% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}

\usepackage[top=37mm,bottom=37mm,left=27mm,right=27mm]{geometry}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[utf8]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\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{linkColor}{rgb}{0.0,0.0,0.554}
\definecolor{citeColor}{rgb}{0.0,0.0,0.554}
\definecolor{fileColor}{rgb}{0.0,0.0,0.554}
\definecolor{urlColor}{rgb}{0.0,0.0,0.554}
\definecolor{promptColor}{rgb}{0.0,0.0,0.589}
\definecolor{brkpromptColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapinputColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapoutputColor}{rgb}{0.0,0.0,0.0}

%%  for a long time these were red and blue by default,
%%  now black, but keep variables to overwrite
\definecolor{FuncColor}{rgb}{0.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,0.0}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}


\usepackage{fancyvrb}

\usepackage{mathptmx,helvet}
\usepackage[T1]{fontenc}
\usepackage{textcomp}


\usepackage[
            pdftex=true,
            bookmarks=true,        
            a4paper=true,
            pdftitle={Written with GAPDoc},
            pdfcreator={LaTeX with hyperref package / GAPDoc},
            colorlinks=true,
            backref=page,
            breaklinks=true,
            linkcolor=linkColor,
            citecolor=citeColor,
            filecolor=fileColor,
            urlcolor=urlColor,
            pdfpagemode={UseNone}, 
           ]{hyperref}

\newcommand{\maintitlesize}{\fontsize{50}{55}\selectfont}

% 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,}}
%% were never documented, give conflicts with some additional packages

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

%% nicer description environments, allows long labels
\usepackage{enumitem}
\setdescription{style=nextline}

%% depth of toc
\setcounter{tocdepth}{1}




\usepackage{amsfonts}
\usepackage{amsxtra}

\tolerance 2500
\hbadness 2500
\emergencystretch 1.5em
\hfuzz 0.3pt
\widowpenalty=10000
\clubpenalty=10000
\vfuzz \hfuzz
\raggedbottom


%% command for ColorPrompt style examples
\newcommand{\gapprompt}[1]{\color{promptColor}{\bfseries #1}}
\newcommand{\gapbrkprompt}[1]{\color{brkpromptColor}{\bfseries #1}}
\newcommand{\gapinput}[1]{\color{gapinputColor}{#1}}


\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\mbox{}\vfill

\begin{center}{\maintitlesize \textbf{ RCWA \mbox{}}}\\
\vfill

\hypersetup{pdftitle= RCWA }
\markright{\scriptsize \mbox{}\hfill  RCWA  \hfill\mbox{}}
{\Huge \textbf{ Residue\texttt{\symbol{45}}Class\texttt{\symbol{45}}Wise Affine Groups \mbox{}}}\\
\vfill

{\Huge  4.8.0 \mbox{}}\\[1cm]
{ 22 September 2025 \mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\Large \textbf{ Stefan Kohl\\
   \mbox{}}}\\
\hypersetup{pdfauthor= Stefan Kohl\\
   }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{ Stefan Kohl\\
   }  Email: \href{mailto://sk239@st-andrews.ac.uk} {\texttt{sk239@st\texttt{\symbol{45}}andrews.ac.uk}}\\
  Homepage: \href{https://stefan-kohl.github.io/} {\texttt{https://stefan\texttt{\symbol{45}}kohl.github.io/}}}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Abstract}
\logpage{[ 0, 0, 1 ]}
      \textsf{RCWA} is a package for \textsf{GAP}{\nobreakspace}4. It provides implementations of algorithms and methods for
computing in certain infinite permutation groups acting on the set of
integers. This package can be used to investigate the following types of
groups and many more: 
\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. 
\item  Direct products of the above groups. 
\item  Wreath products of the above groups with finite groups and
with{\nobreakspace}({\ensuremath{\mathbb Z}},+). 
\item  Subgroups of any such groups. 
\end{itemize}
 With the help of this package, the author has found a countable simple group
which is generated by involutions interchanging disjoint residue classes of
{\ensuremath{\mathbb Z}} and which all the above groups embed into
\texttt{\symbol{45}}\texttt{\symbol{45}} see{\nobreakspace}\cite{Kohl09}. 

  \mbox{}}\\[1cm]
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 2 ]}
 {\copyright} 2003 \texttt{\symbol{45}} 2018 by Stefan Kohl. 

 \textsf{RCWA} is free software: you can redistribute it and/or modify it under the terms of
the GNU General Public License as published by the Free Software Foundation,
either version 2 of the License, or (at your option) any later version. 

 \textsf{RCWA} is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details. 

 For a copy of the GNU General Public License, see the file \texttt{GPL} in the \texttt{etc} directory of the \textsf{GAP} distribution or see \href{https://www.gnu.org/licenses/gpl.html} {\texttt{https://www.gnu.org/licenses/gpl.html}}. \vspace{-1cm} \mbox{}}\\[1cm]
{\small 
\section*{Acknowledgements}
\logpage{[ 0, 0, 3 ]}
 I am grateful to John P. McDermott for the discovery that the group discussed
in Section{\nobreakspace}\ref{sec:ThompsonsGroupV} is isomorphic to Thompson's Group V in July 2008, and to Laurent Bartholdi for
his hint on how to construct wreath products of
residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine groups
with{\nobreakspace}({\ensuremath{\mathbb Z}},+) in April 2006. Further, I
thank Bettina{\nobreakspace}Eick for communicating this package and for her
valuable suggestions on its manual in the time before its first public release
in April 2005. Last but not least I thank the two anonymous referees for their
constructive criticism and their helpful suggestions. \mbox{}}\\[1cm]
\newpage

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

\tableofcontents
\newpage

      
\chapter{\textcolor{Chapter }{About the RCWA Package}}\label{ch:AboutRCWA}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X83A8C2927FAE2C23}{}
{
 \index{Collatz conjecture@Collatz conjecture} \index{Collatz conjecture@Collatz mapping} This package permits to compute in monoids, in particular groups, whose
elements are \emph{residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine} mappings. Probably the widest\texttt{\symbol{45}}known occurrence of such a
mapping is in the statement of the $3n+1$ conjecture, which asserts that iterated application of the \emph{Collatz mapping} 
  
\[
  T: \ \ \mathbb{Z} \longrightarrow \mathbb{Z}, \ \ \ java.lang.NullPointerException
           n \ \longmapsto java.lang.NullPointerException
          \begin{cases}
          \frac{n}{2}    & \text{if} \ \ n \ \ \text{is even}, \\
          \frac{3n+1}{2} & \text{if} \ \ n \ \ \text{is odd}
          \end{cases}
  \]

   to any given positive integer eventually yields{\nobreakspace}1
(cf.{\nobreakspace}\cite{Lagarias06}). For definitions, see Section{\nobreakspace}\ref{sec:basicdefinitions}. 

 Presently, most research in computational group theory focuses on finite
permutation groups, matrix groups, finitely presented groups, polycyclically
presented groups and automata groups. For details, we refer to{\nobreakspace}\cite{HoltEickOBrien05}. The purpose of this package is twofold: 
\begin{itemize}
\item  On the one hand, it provides the means to deal with another large class of
groups which are accessible to computational methods, and it therefore extends
the range of groups which can be dealt with by means of computation. 
\item  On the other \texttt{\symbol{45}}\texttt{\symbol{45}} and perhaps more
importantly \texttt{\symbol{45}}\texttt{\symbol{45}}
residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine groups appear
to be interesting mathematical objects in their own right, and this package is
intended to serve as a tool to obtain a better understanding of their rich and
often complicated group theoretical and combinatorial structure. 
\end{itemize}
 In principle this package permits to construct and investigate all groups
which have faithful representations as
residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine groups. Among
many others, the following groups and their subgroups belong to this class: 
\begin{itemize}
\item  Finite groups, and certain divisible torsion groups which they embed into. 
\item  Free groups of finite rank. 
\item  Free products of finitely many finite groups. 
\item  Direct products of the above groups. 
\item  Wreath products of the above groups with finite groups and
with{\nobreakspace}({\ensuremath{\mathbb Z}},+). 
\end{itemize}
 This list permits already to conclude that there are finitely generated
residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine groups which
do not have finite presentations, and such with algorithmically unsolvable
membership problem. However the list is certainly by far not exhaustive, and
using this package it is easy to construct groups of types which are not
mentioned there. 

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

 Proofs of most of the results mentioned so far can be found in{\nobreakspace}\cite{Kohl09}. Descriptions of a part of the algorithms and methods which are implemented
in this package can be found in{\nobreakspace}\cite{Kohl08b}. 

 The reader might want to know what type of results one can obtain with \textsf{RCWA}. However, the answer to this is that the package can be applied in various
ways to various different problems, and it is simply not possible to say in
general what can be found out with its help. So one really cannot give a
better answer here than for the same question about \textsf{GAP} itself. The best way to get familiar with the package and its capabilities is
likely to experiment with the examples discussed in this manual and the groups
generated by 3 class transpositions from the corresponding data library. 

 Of course, sometimes this package does not provide an
out\texttt{\symbol{45}}of\texttt{\symbol{45}}the\texttt{\symbol{45}}box
solution for a given problem. But quite often it is still possible to find an
answer by an interactive trial\texttt{\symbol{45}}and\texttt{\symbol{45}}error
approach. With substantial help of this package, the author has found the
results mentioned above. Interactive sessions with this package have also led
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\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine permutations
(see{\nobreakspace}\texttt{FactorizationIntoCSCRCT} (\ref{FactorizationIntoCSCRCT:for an rcwa permutation of Z})) solely by means of theory would likely have been very hard.  }

       
\chapter{\textcolor{Chapter }{Residue\texttt{\symbol{45}}Class\texttt{\symbol{45}}Wise Affine Mappings}}\label{ch:RcwaMappings}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X7FD73FCB8510050E}{}
{
   This chapter contains the basic definitions, and it describes how to enter
residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine mappings and
how to compute with them. 

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

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

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

 \index{tame@tame!rcwa mapping} \index{tame@tame!rcwa group} \index{wild@wild!rcwa mapping} \index{wild@wild!rcwa group} \index{rcwa mapping@rcwa mapping!tame} \index{rcwa group@rcwa group!tame} \index{rcwa mapping@rcwa mapping!wild} \index{rcwa group@rcwa group!wild} An rcwa mapping is called \emph{tame} if the set of moduli of its powers is bounded, or equivalently if it permutes
a partition of{\nobreakspace}{\ensuremath{\mathbb 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
\texttt{\symbol{45}}groups which are not tame are called \emph{wild}. Tame rcwa mappings and \texttt{\symbol{45}}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\texttt{\symbol{45}}class\texttt{\symbol{45}}wise
affine mappings and \texttt{\symbol{45}}groups can be generalized in the
obvious way to suitable rings other than{\nobreakspace}{\ensuremath{\mathbb
Z}}. In fact, this package provides also some support for
residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine groups over ${\ensuremath{\mathbb Z}}^2$, over semilocalizations of{\nobreakspace}{\ensuremath{\mathbb Z}} and over
univariate polynomial rings over finite fields. The ring ${\ensuremath{\mathbb Z}}^2$ has been chosen as an example of a suitable ring which is not a principal
ideal domain, the semilocalizations of{\nobreakspace}{\ensuremath{\mathbb Z}}
have been chosen as examples of rings with only finitely many prime elements,
and the univariate polynomial rings over finite fields have been chosen as
examples of rings with nonzero characteristic. }

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

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

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

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

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



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

 In the one\texttt{\symbol{45}}argument form, the argument{\nobreakspace}\mbox{\texttt{\mdseries\slshape cl}} stands for the residue class{\nobreakspace}$r(m)$. Enclosing the argument list in list brackets is permitted. 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@Display(ClassShift(5,12));A
  
  Tame rcwa permutation of Z with modulus 12, of order infinity
  
          /
          | n+12 if n in 5(12)
   n |-> <  n    if n in Z \ 5(12)
          |
          java.lang.NullPointerException
  
\end{Verbatim}
 }

 

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



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

 In the one\texttt{\symbol{45}}argument form, the argument{\nobreakspace}\mbox{\texttt{\mdseries\slshape cl}} stands for the residue class{\nobreakspace}$r(m)$. Enclosing the argument list in list brackets is permitted. 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@Display(ClassReflection(5,9));A
  
  Rcwa permutation of Z with modulus 9, of order 2
  
          /
          | -n+10 if n in 5(9)
   n |-> <  n     if n in Z \ 5(9)
          |
          java.lang.NullPointerException
  
\end{Verbatim}
 }

 \pagebreak[4] 

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



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

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

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

 \index{ClassPairs@\texttt{ClassPairs}!m} A list of all class transpositions interchanging residue classes with moduli
less than or equal to a given bound \mbox{\texttt{\mdseries\slshape m}} can be obtained by \texttt{List(ClassPairs([\mbox{\texttt{\mdseries\slshape P}}],\mbox{\texttt{\mdseries\slshape m}}),ClassTransposition)}, where the function \texttt{ClassPairs} returns a list of all 4\texttt{\symbol{45}}tuples $(r_1,m_1,r_2,m_2)$ of integers corresponding to the unordered pairs of disjoint residue classes $r_1(m_1)$ and $r_2(m_2)$ with $m_1$ and $m_2$ less than or equal to the specified bound. If a list of primes is given as
optional argument \mbox{\texttt{\mdseries\slshape P}}, then the returned list contains only those 4\texttt{\symbol{45}}tuples where
all prime factors of $m_1$ and $m_2$ lie in \mbox{\texttt{\mdseries\slshape P}}. If the option \texttt{divisors} is set, the returned list contains only the 4\texttt{\symbol{45}}tuples where $m_1$ and $m_2$ divide \mbox{\texttt{\mdseries\slshape m}}. 

 \index{NrClassPairs@\texttt{NrClassPairs}!m} \index{ExtRepOfObj@\texttt{ExtRepOfObj}!for a class transposition} The function \texttt{NrClassPairs(\mbox{\texttt{\mdseries\slshape m}})} returns the length of the list \texttt{ClassPairs(\mbox{\texttt{\mdseries\slshape m}})}, where the result is computed much faster and without actually generating the
list of tuples. Given a class transposition \mbox{\texttt{\mdseries\slshape ct}}, the corresponding 4\texttt{\symbol{45}}tuple can be obtained by \texttt{ExtRepOfObj(\mbox{\texttt{\mdseries\slshape ct}})} 

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

 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@Display(ClassTransposition(1,2,8,10):CycleNotation:=false);A
  
  Rcwa permutation of Z with modulus 10, of order 2
  
          /
          | 5n+3    if n in 1(2)
   n |-> <  (n-3)/5 if n in 8(10)
          | n       if n in 0(2) \ 8(10)
          java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@List(ClassPairs(4),ClassTransposition);A
  [ ( 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) ) ]
  !gapprompt@gap>A !gapinput@NrClassPairs(100);A
  3528138
  !gapprompt@gap>A !gapinput@SplittedClassTransposition(ClassTransposition(0,2,1,4),3);A
  [ ( 0(6), 1(12) ), ( 2(6), 5(12) ), ( 4(6), 9(12) ) ]
\end{Verbatim}
 }

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

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

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

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



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

 \index{RotationFactor@\texttt{RotationFactor}!of a class rotation} In the two\texttt{\symbol{45}}argument form, the argument{\nobreakspace}\mbox{\texttt{\mdseries\slshape cl}} stands for the residue class{\nobreakspace}$r(m)$. Enclosing the argument list in list brackets is permitted. The argument \mbox{\texttt{\mdseries\slshape u}} is stored as an attribute \texttt{RotationFactor}. 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@Display(ClassRotation(ResidueClass(Z_pi(2),2,1),1/3));A
  
  Tame rcwa permutation of Z_( 2 ) with modulus 2, of order infinity
  
          /
          | 1/3 n + 2/3 if n in 1(2)
   n |-> <  n           if n in 0(2)
          |
          java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@x := Indeterminate(GF(8),1);; SetName(x,"x");A
  !gapprompt@gap>A !gapinput@R := PolynomialRing(GF(8),1);;A
  !gapprompt@gap>A !gapinput@cr := ClassRotation(1,x,Z(8)*One(R)); Support(cr);A
  ClassRotation( 1(x), Z(2^3) )
  1(x) \ [ 1 ]
  !gapprompt@gap>A !gapinput@Display(cr);A
  
  Rcwa permutation of GF(2^3)[x] with modulus x, of order 7
  
          /
          | Z(2^3)*P + Z(2^3)^3 if P in 1(x)
   P |-> <  P                   otherwise
          |
          java.lang.NullPointerException
  
\end{Verbatim}
 }

 \index{IsClassShift@\texttt{IsClassShift}!for an rcwa mapping} \index{IsClassReflection@\texttt{IsClassReflection}!for an rcwa mapping} \index{IsClassRotation@\texttt{IsClassRotation}!for an rcwa mapping} \index{IsClassTransposition@\texttt{IsClassTransposition}!for an rcwa mapping} \index{IsGeneralizedClassTransposition@\texttt{IsGeneralizedClassTransposition}!for an rcwa mapping} \texttt{IsClassShift}, \texttt{IsClassReflection}, \texttt{IsClassRotation}, \texttt{IsClassTransposition} and \texttt{IsGeneralizedClassTransposition} are properties which indicate whether a given rcwa mapping belongs to the
corresponding series. 

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



 In all cases the argument{\nobreakspace}\mbox{\texttt{\mdseries\slshape R}} is the underlying ring, \mbox{\texttt{\mdseries\slshape m}} is the modulus and \mbox{\texttt{\mdseries\slshape coeffs}} is the coefficient list. A \emph{coefficient list} for an rcwa mapping with modulus $m$ consists of $|R/mR|$ coefficient triples \texttt{[}$a_{r(m)}$, $b_{r(m)}$, $c_{r(m)}$\texttt{]}. Their ordering is determined by the ordering of the representatives of the
residue classes (mod{\nobreakspace}$m$) in the sorted list returned by \texttt{AllResidues(\mbox{\texttt{\mdseries\slshape R}}, \mbox{\texttt{\mdseries\slshape m}})}. In case $R = {\ensuremath{\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. 

 If one or several of the arguments \mbox{\texttt{\mdseries\slshape R}}, \mbox{\texttt{\mdseries\slshape m}} and \mbox{\texttt{\mdseries\slshape coeffs}} are omitted or replaced by other arguments, the former are either derived from
the latter or default values are chosen. 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{\mdseries\slshape R}} with modulus \mbox{\texttt{\mdseries\slshape m}} and coefficients \mbox{\texttt{\mdseries\slshape coeffs}}, 
\item[{(b)}]  of \mbox{\texttt{\mdseries\slshape R}} = {\ensuremath{\mathbb Z}} or \mbox{\texttt{\mdseries\slshape R}} = ${\ensuremath{\mathbb Z}}_{(\pi)}$ with modulus \texttt{Length(\mbox{\texttt{\mdseries\slshape coeffs}})} and coefficients \mbox{\texttt{\mdseries\slshape coeffs}}, 
\item[{(c)}]  of \mbox{\texttt{\mdseries\slshape R}} = {\ensuremath{\mathbb Z}} with modulus \texttt{Length(\mbox{\texttt{\mdseries\slshape coeffs}})} and coefficients \mbox{\texttt{\mdseries\slshape coeffs}}, 
\item[{(d)}]  of \mbox{\texttt{\mdseries\slshape R}} = {\ensuremath{\mathbb Z}}, permuting any set \texttt{\mbox{\texttt{\mdseries\slshape range}}+k*Length(\mbox{\texttt{\mdseries\slshape range}})} like \mbox{\texttt{\mdseries\slshape perm}} permutes \mbox{\texttt{\mdseries\slshape range}}, 
\item[{(e)}]  of \mbox{\texttt{\mdseries\slshape R}} = {\ensuremath{\mathbb Z}} with modulus \mbox{\texttt{\mdseries\slshape m}} and values given by a list \mbox{\texttt{\mdseries\slshape val}} of 2 pairs \texttt{[}preimage\texttt{, }image\texttt{]} per residue class (mod \mbox{\texttt{\mdseries\slshape m}}), 
\item[{(f)}]  of \mbox{\texttt{\mdseries\slshape R}} = ${\ensuremath{\mathbb Z}}_{(\pi)}$ with modulus \texttt{Length(\mbox{\texttt{\mdseries\slshape coeffs}})} and coefficients \mbox{\texttt{\mdseries\slshape coeffs}} (the set of primes $\pi$ which denotes the underlying ring is passed as argument{\nobreakspace}\mbox{\texttt{\mdseries\slshape pi}}), 
\item[{(g)}]  of \mbox{\texttt{\mdseries\slshape R}} = GF(\mbox{\texttt{\mdseries\slshape q}})[\mbox{\texttt{\mdseries\slshape x}}] with modulus{\nobreakspace}\mbox{\texttt{\mdseries\slshape m}} and coefficients \mbox{\texttt{\mdseries\slshape coeffs}}, 
\item[{(h)}]  an rcwa permutation which induces a bijection between the partitions \mbox{\texttt{\mdseries\slshape P1}} and \mbox{\texttt{\mdseries\slshape P2}} of{\nobreakspace}\mbox{\texttt{\mdseries\slshape R}} into residue classes and which is affine on the elements of \mbox{\texttt{\mdseries\slshape P1}}, 
\item[{(i)}]  an rcwa permutation with ``residue class cycles'' given by a list \mbox{\texttt{\mdseries\slshape cycles}} of lists of pairwise disjoint residue classes, each of which it permutes
cyclically, or 
\item[{(j)}]  the rcwa permutation of{\nobreakspace}{\ensuremath{\mathbb Z}} given by the
arithmetical expression \mbox{\texttt{\mdseries\slshape expression}} \texttt{\symbol{45}}\texttt{\symbol{45}} a string consisting of class
transpositions (e.g. \texttt{"(0(2),1(4))"}) or cycles permuting residue classes (e.g. \texttt{"(0(2),1(8),3(4),5(8))"}), class shifts (e.g. \texttt{"cs(4(6))"}, class reflections (e.g. \texttt{"cr(3(4))"}), arithmetical operators (\texttt{"*"}, \texttt{"/"} and \texttt{"\texttt{\symbol{94}}"}) and brackets (\texttt{"("}, \texttt{")"}), 
\end{description}
 respectively. The methods for the operation \texttt{RcwaMapping} perform a number of argument checks, which can be skipped by using \texttt{RcwaMappingNC} instead. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@R := PolynomialRing(GF(2),1);; x := X(GF(2),1);; SetName(x,"x");|
  !gapprompt@gap>| !gapinput@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+1>
  !gapprompt@gap>| !gapinput@RcwaMapping(Z_pi(2),[[1/3,0,1]]);                              # (b)|
  Rcwa mapping of Z_( 2 ): n -> 1/3 n
  !gapprompt@gap>| !gapinput@a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);                  # (c)|
  <rcwa mapping of Z with modulus 3>
  !gapprompt@gap>| !gapinput@RcwaMapping((1,2,3),[1..4]);                                   # (d)|
  ( 1(4), 2(4), 3(4) )
  !gapprompt@gap>| !gapinput@T = RcwaMapping(2,[[1,2],[2,1],[3,5],[4,2]]);                  # (e)|
  true
  !gapprompt@gap>| !gapinput@RcwaMapping([2],[[1/3,0,1]]);                                  # (f)|
  Rcwa mapping of Z_( 2 ): n -> 1/3 n
  !gapprompt@gap>| !gapinput@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+1>
  !gapprompt@gap>| !gapinput@a = RcwaMapping(List([[0,3],[1,3],[2,3]],ResidueClass),|
  !gapprompt@>| !gapinput@                   List([[0,2],[1,4],[3,4]],ResidueClass));       # (h)|
  true
  !gapprompt@gap>| !gapinput@RcwaMapping([List([[0,2],[1,4],[3,8],[7,16]],ResidueClass)]);  # (i)|
  ( 0(2), 1(4), 3(8), 7(16) )
  !gapprompt@gap>| !gapinput@Cycle(last,ResidueClass(0,2));|
  [ 0(2), 1(4), 3(8), 7(16) ]
  !gapprompt@gap>| !gapinput@g := RcwaMapping("((0(4),1(6))*cr(0(6)))^2/cs(2(8))");         # (j)|
  <rcwa permutation of Z with modulus 72>
  !gapprompt@gap>| !gapinput@g = (ClassTransposition(0,4,1,6) * ClassReflection(0,6))^2/|
  !gapprompt@>| !gapinput@        ClassShift(2,8);|
  true
  
\end{Verbatim}
 }

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

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



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

 \index{View@\texttt{View}!for an rcwa mapping} \index{Display@\texttt{Display}!for an rcwa mapping} \index{Print@\texttt{Print}!for an rcwa mapping} \index{String@\texttt{String}!for an rcwa mapping} \noindent Rcwa mappings can be \texttt{View}ed, \texttt{Display}ed, \texttt{Print}ed and written to a \texttt{String}. The output of the \texttt{View} method is kept reasonably short. In most cases it does not describe an rcwa
mapping completely. In these cases the output is enclosed in brackets. There
are options \texttt{CycleNotation}, \texttt{AsClassMapping}, \texttt{PrintNotation} and \texttt{AbridgedNotation} to take influence on how certain rcwa mappings are shown. These options can
either be not set, set to \texttt{true} or set to \texttt{false}. If the option \texttt{CycleNotation} is set, it is tried harder to write down an rcwa permutation of
{\ensuremath{\mathbb Z}} of finite order as a product of disjoint residue
class cycles, if this is possible. If the option \texttt{AsClassMapping} is set, \texttt{Display} shows which residue classes are mapped to which by the affine partial
mappings, and marks any loops. The option \texttt{PrintNotation} influences the output in favour of \textsf{GAP} \texttt{\symbol{45}} readability, and the option \texttt{AbridgedNotation} can be used to abridge longer names like \texttt{ClassShift}, \texttt{ClassReflection} etc.. By default, the output of the methods for \texttt{Display} and \texttt{Print} describes an rcwa mapping in full. The \texttt{Print}ed representation of an rcwa mapping is \textsf{GAP} \texttt{\symbol{45}} readable if and only if the \texttt{Print}ed representation of the elements of the underlying ring is so. 

 \index{LaTeXStringRcwaMapping@\texttt{LaTeXStringRcwaMapping}!for an rcwa mapping} There is also an operation \texttt{LaTeXStringRcwaMapping}, which takes as argument an rcwa mapping and returns a corresponding {\LaTeX} string. The output makes use of the {\LaTeX} macro package \textsf{amsmath}. If the option \mbox{\texttt{\mdseries\slshape Factorization}} is set and the argument is bijective, a factorization into class shifts, class
reflections, class transpositions and prime switches is printed (cf. \texttt{FactorizationIntoCSCRCT} (\ref{FactorizationIntoCSCRCT:for an rcwa permutation of Z})). For rcwa mappings with modulus greater than{\nobreakspace}1, an indentation
by \mbox{\texttt{\mdseries\slshape Indentation}} characters can be obtained by setting this option value accordingly. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Print(LaTeXStringRcwaMapping(T));|
  n \ \mapsto java.lang.NullPointerException
  \begin{cases}
    n/2      & \text{if} \ n \in 0(2), \\
    (3n+1)/2 & \text{if} \ n \in 1(2).
  \end{cases}
  
\end{Verbatim}
 \index{LaTeXAndXDVI@\texttt{LaTeXAndXDVI}!for an rcwa mapping} There is an operation \texttt{LaTeXAndXDVI} which displays an rcwa mapping in an \textsf{xdvi} window. This works as follows: The string returned by \texttt{LaTeXStringRcwaMapping} 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{\mdseries\slshape xdvi}} has the same effect. The operation \texttt{LaTeXAndXDVI} is only available on UNIX systems, and requires suitable installations of {\LaTeX} and \textsf{xdvi}. }

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

 Testing rcwa mappings for equality requires only comparing their coefficient
lists, hence is cheap. Rcwa mappings can be multiplied, thus there is a method
for \texttt{*}. Rcwa permutations can also be inverted, thus there is a method for \texttt{Inverse}. The latter method is usually accessed by raising a mapping to a power with
negative exponent. Multiplying, inverting and computing powers of tame rcwa
mappings is cheap. Computing powers of wild mappings is usually expensive
\texttt{\symbol{45}}\texttt{\symbol{45}} run time and memory requirements
normally grow approximately exponentially with the exponent. How expensive
multiplying a couple of wild mappings is, varies very much. In any case, the
amount of memory required for storing an rcwa mapping is proportional to its
modulus. Whether a given mapping is tame or wild can be determined by the
operation \texttt{IsTame}. There is a method for \texttt{Order}, which can not only compute a finite order, but which can also detect
infinite order. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@T := RcwaMapping([[1,0,2],[3,1,2]]);;          # The Collatz mapping.|
  !gapprompt@gap>| !gapinput@a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; # Collatz' permutation.|
  !gapprompt@gap>| !gapinput@List([-4..4],k->Modulus(a^k));|
  [ 256, 64, 16, 4, 1, 3, 9, 27, 81 ]
  !gapprompt@gap>| !gapinput@IsTame(T) or IsTame(a);|
  false
  !gapprompt@gap>| !gapinput@IsTame(ClassShift(0,1)) and IsTame(ClassTransposition(0,2,1,2));|
  true
  !gapprompt@gap>| !gapinput@T^2*a*T*a^-3;|
  <rcwa mapping of Z with modulus 768>
  !gapprompt@gap>| !gapinput@(ClassShift(1,3)*ClassReflection(2,7))^1000000;|
  <rcwa permutation of Z with modulus 21>
  
\end{Verbatim}
 \index{IsInjective@\texttt{IsInjective}!for an rcwa mapping} \index{IsSurjective@\texttt{IsSurjective}!for an rcwa mapping} \index{IsBijective@\texttt{IsBijective}!for an rcwa mapping} \index{Image@\texttt{Image}!of an rcwa mapping} There are methods installed for \texttt{IsInjective}, \texttt{IsSurjective}, \texttt{IsBijective} and \texttt{Image}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@[ IsInjective(T), IsSurjective(T), IsBijective(a) ];|
  [ false, true, true ]
  !gapprompt@gap>| !gapinput@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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@15^T;|
  23
  !gapprompt@gap>| !gapinput@ResidueClass(1,2)^T;|
  2(3)
  !gapprompt@gap>| !gapinput@List([[0,3],[1,3],[2,3]],ResidueClass)^a;|
  [ 0(2), 1(4), 3(4) ]
  
\end{Verbatim}
 \index{PreImageElm@\texttt{PreImageElm}!of a ring element under an rcwa mapping} \index{PreImagesElm@\texttt{PreImagesElm}!of a ring element under an rcwa mapping} \index{PreImage@\texttt{PreImage}!of a set of ring elements under an rcwa mapping} \index{PreImage@\texttt{PreImage}!of a residue class union under an rcwa mapping} For computing preimages of elements under rcwa mappings, there are methods for \texttt{PreImageElm} and \texttt{PreImagesElm}. The preimage of a finite set of ring elements or of a union of finitely many
residue classes under an rcwa mapping can be computed by \texttt{PreImage}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@PreImagesElm(T,8);|
  [ 5, 16 ]
  !gapprompt@gap>| !gapinput@PreImage(T,ResidueClass(Integers,3,2));|
  Z \ 0(6) U 2(6)
  !gapprompt@gap>| !gapinput@M := [1];; l := [1];;|
  !gapprompt@gap>| !gapinput@while Length(M) < 5000 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 ]
  
\end{Verbatim}
 \index{Support@\texttt{Support}!of an rcwa mapping} \index{MovedPoints@\texttt{MovedPoints}!of an rcwa mapping} \index{RestrictedPerm@\texttt{RestrictedPerm}!for an rcwa permutation and a residue class union} \index{DensityOfSupport@\texttt{DensityOfSupport}!of an rcwa mapping} \index{DensityOfSetOfFixedPoints@\texttt{DensityOfSetOfFixedPoints}!of an rcwa mapping} There is a method for the operation \texttt{Support} for computing the support of an rcwa mapping. A synonym for \texttt{Support} is \texttt{MovedPoints}. The natural density of the support of an rcwa mapping of
{\ensuremath{\mathbb Z}} can be computed efficiently with the operation \texttt{DensityOfSupport}. Likewise, the natural density of the set of fixed points of an rcwa mapping
of {\ensuremath{\mathbb Z}} can be computed efficiently with the operation \texttt{DensityOfSetOfFixedPoints}. There is also a method for \texttt{RestrictedPerm} for computing the restriction of an rcwa permutation to a union of residue
classes which it fixes setwise. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@List([a,a^2],Support);|
  [ Z \ [ -1, 0, 1 ], Z \ [ -3, -2, -1, 0, 1, 2, 3 ] ]
  !gapprompt@gap>| !gapinput@RestrictedPerm(ClassShift(0,2)*ClassReflection(1,2),|
  !gapprompt@>| !gapinput@                  ResidueClass(0,2));|
  <rcwa mapping of Z with modulus 2>
  !gapprompt@gap>| !gapinput@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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@b := ClassShift(0,3) * a;;|
  !gapprompt@gap>| !gapinput@[ Image((a + b)), Image((a - b)) ];|
  [ 2(4), [ -2, 0 ] ]
  
\end{Verbatim}
 \index{Modulus@\texttt{Modulus}!of an rcwa mapping} \index{Mod@\texttt{Mod}!for an rcwa mapping} \index{Coefficients@\texttt{Coefficients}!of an rcwa mapping} \index{rcwa mapping@rcwa mapping!coercion} \index{rcwa group@rcwa group!coercion} There are operations \texttt{Modulus} (abbreviated \texttt{Mod}) and \texttt{Coefficients} for retrieving the modulus and the coefficient list of an rcwa mapping. The
meaning of the return values is as described in Section{\nobreakspace}\ref{sec:EnteringRcwaMappings}. 

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

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

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

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



 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@LargestSourcesOfAffineMappings(ClassShift(3,7));|
  [ Z \ 3(7), 3(7) ]
  !gapprompt@gap>| !gapinput@LargestSourcesOfAffineMappings(ClassReflection(0,1));|
  [ Integers ]
  !gapprompt@gap>| !gapinput@u := RcwaMapping([[3,0,5],[9,1,5],[3,-1,5],[9,-2,5],[9,4,5]]);;|
  !gapprompt@gap>| !gapinput@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) ] ]
  !gapprompt@gap>| !gapinput@kappa := ClassTransposition(2,4,3,4) * ClassTransposition(4,6,8,12)|
  !gapprompt@>| !gapinput@          * ClassTransposition(3,4,4,6);|
  <rcwa permutation of Z with modulus 12>
  !gapprompt@gap>| !gapinput@LargestSourcesOfAffineMappings(kappa);|
  [ 2(4), 1(4) U 0(12), 3(12) U 7(12), 4(12), 8(12), 11(12) ]
  
\end{Verbatim}
 }

 

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



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

 

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



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

 \index{ClassWiseOrderPreservingOn@\texttt{ClassWiseOrderPreservingOn}} \index{ClassWiseConstantOn@\texttt{ClassWiseConstantOn}} \index{ClassWiseOrderReversingOn@\texttt{ClassWiseOrderReversingOn}} There are attributes \texttt{ClassWiseOrderPreservingOn}, \texttt{ClassWiseConstantOn} and \texttt{ClassWiseOrderReversingOn} which store the union of the residue classes (mod{\nobreakspace}\texttt{Mod(\mbox{\texttt{\mdseries\slshape f}})}) on which an rcwa mapping{\nobreakspace}\mbox{\texttt{\mdseries\slshape f}} of{\nobreakspace}{\ensuremath{\mathbb Z}} or of a semilocalization thereof is
class\texttt{\symbol{45}}wise order\texttt{\symbol{45}}preserving,
class\texttt{\symbol{45}}wise constant or class\texttt{\symbol{45}}wise
order\texttt{\symbol{45}}reversing, respectively. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@List([ClassTransposition(1,2,0,4),ClassShift(2,3),|
  !gapprompt@>| !gapinput@         ClassReflection(2,5)],ClassWiseOrderPreservingOn);|
  [ Integers, Integers, Z \ 2(5) ]
  
\end{Verbatim}
 \index{ShiftsUpOn@\texttt{ShiftsUpOn}} \index{ShiftsDownOn@\texttt{ShiftsDownOn}} Also there are attributes \texttt{ShiftsUpOn} and \texttt{ShiftsDownOn} which store the union of the residue classes (mod{\nobreakspace}\texttt{Mod(\mbox{\texttt{\mdseries\slshape f}})}) on which an rcwa mapping{\nobreakspace}\mbox{\texttt{\mdseries\slshape f}} of{\nobreakspace}{\ensuremath{\mathbb Z}} induces affine mappings $n \mapsto n + c$ for $c > 0$, respectively, $c < 0$. 

 Finally, there are epimorphisms from the subgroup of RCWA({\ensuremath{\mathbb
Z}}) formed by all class\texttt{\symbol{45}}wise
order\texttt{\symbol{45}}preserving elements to ({\ensuremath{\mathbb Z}},+)
and from RCWA({\ensuremath{\mathbb Z}}) itself to the cyclic group of
order{\nobreakspace}2, respectively: 

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



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

 Let $f$ be an rcwa mapping of the integers, and let $m$ denote its modulus. Using the notation $f|_{r(m)}: n \mapsto (a_{r(m)} \cdot n + b_{r(m)})/c_{r(m)}$ for the affine partial mappings, the \emph{determinant} det($f$) of{\nobreakspace}$f$ is given by 
      
\[
        \sum_{r(m) \in \mathbb{Z}/m\mathbb{Z}} b_{r(m)}/(|a_{r(m)}| \cdot m).
      \]

       The determinant mapping is an epimorphism from the group of all
class\texttt{\symbol{45}}wise order\texttt{\symbol{45}}preserving rcwa
permutations of{\nobreakspace}{\ensuremath{\mathbb Z}} to
({\ensuremath{\mathbb Z}},+), see{\nobreakspace}\cite{Kohl05}, Theorem{\nobreakspace}2.11.9. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@List([ClassTransposition(0,4,5,12),ClassShift(3,7)],Determinant);|
  [ 0, 1 ]
  !gapprompt@gap>| !gapinput@Determinant(ClassTransposition(0,4,5,12)*ClassShift(3,7)^100);   |
  100
  
\end{Verbatim}
 }

 

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



 Let $\sigma$ be an rcwa permutation of the integers, and let $m$ denote its modulus. Using the notation $\sigma|_{r(m)}: n \mapsto (a_{r(m)} \cdot n + b_{r(m)})/c_{r(m)}$ for the affine partial mappings, the \emph{sign} of{\nobreakspace}$\sigma$ is defined by 
      
\[
        (-1)^{\displaystyle{{\rm det}(\sigma)
            + \sum_{r(m): \ a_{r(m)} < 0} \frac{m - 2r}{m}}}.
      \]

       The sign mapping is an epimorphism from RCWA({\ensuremath{\mathbb Z}}) to the
group ${\ensuremath{\mathbb Z}}^\times$ of units of{\nobreakspace}{\ensuremath{\mathbb Z}}, see{\nobreakspace}\cite{Kohl05}, Theorem{\nobreakspace}2.12.8. Therefore the kernel of the sign mapping is a
normal subgroup of RCWA({\ensuremath{\mathbb Z}}) of index{\nobreakspace}2.
The simple group CT({\ensuremath{\mathbb Z}}) is a subgroup of this kernel. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@List([ClassTransposition(3,4,2,6),|
  !gapprompt@>| !gapinput@         ClassShift(0,3),ClassReflection(2,5)],Sign);|
  [ 1, -1, -1 ]
  
\end{Verbatim}
 }

 }

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

\subsection{\textcolor{Chapter }{CTCSCRSplit (for an rcwa permutation of Z)}}
\logpage{[ 2, 5, 1 ]}\nobreak
\hyperdef{L}{X829BA0537F2372FF}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CTCSCRSplit({\mdseries\slshape g})\index{CTCSCRSplit@\texttt{CTCSCRSplit}!for an rcwa permutation of Z}
\label{CTCSCRSplit:for an rcwa permutation of Z}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 a list of 3 rcwa permutations $a$, $b$ and $c$ whose product equals \mbox{\texttt{\mdseries\slshape g}}, where $a$ fixes the nonnegative integers setwise, $b$ is integral and class\texttt{\symbol{45}}wise
order\texttt{\symbol{45}}preserving and $c$ is integral. 



 Assuming the hypothesis that CT({\ensuremath{\mathbb Z}}) is the group of all
rcwa permutations of {\ensuremath{\mathbb Z}} which fix the nonnegative
integers setwise, $a$ is always an element of CT({\ensuremath{\mathbb Z}}). 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@g := ClassTransposition(0,4,1,6)*ClassShift(2,5)*ClassReflection(2,3);|
  <rcwa permutation of Z with modulus 180>
  !gapprompt@gap>| !gapinput@facts := CTCSCRSplit(g);|
  [ <rcwa permutation of Z with modulus 60>, ClassShift( 2(30) ), 
    ClassReflection( 2(3) ) ]
  !gapprompt@gap>| !gapinput@Product(facts) = g;|
  true
  !gapprompt@gap>| !gapinput@List(facts,IsSignPreserving);|
  [ true, false, false ]
  !gapprompt@gap>| !gapinput@List(facts,IsIntegral);|
  [ false, true, true ]
  !gapprompt@gap>| !gapinput@List(facts,IsClassWiseOrderPreserving);|
  [ true, true, false ]
  
\end{Verbatim}
 }

 

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



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

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

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

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

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

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

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

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

\subsection{\textcolor{Chapter }{PrimeSwitch (p)}}
\logpage{[ 2, 5, 3 ]}\nobreak
\hyperdef{L}{X861C74E97AE5DA3B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PrimeSwitch({\mdseries\slshape p})\index{PrimeSwitch@\texttt{PrimeSwitch}!p}
\label{PrimeSwitch:p}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PrimeSwitch({\mdseries\slshape p, k})\index{PrimeSwitch@\texttt{PrimeSwitch}!p, k}
\label{PrimeSwitch:p, k}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PrimeSwitch({\mdseries\slshape p, r, m})\index{PrimeSwitch@\texttt{PrimeSwitch}!p, r, m}
\label{PrimeSwitch:p, r, m}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PrimeSwitch({\mdseries\slshape p, cl})\index{PrimeSwitch@\texttt{PrimeSwitch}!p, cl}
\label{PrimeSwitch:p, cl}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 in the first 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)}$, in the second form the restriction of $\sigma_p$ by $n \mapsto kn$, and in the third and fourth form the \emph{prime switch} $\sigma_{p,r(m)} := \tau_{r_1(m/2),r_2(m)} \cdot \tau_{r_2(m),r_1(pm/2)} \cdot
\tau_{r(m/2),r_1(pm/2)}$. In the latter case, \mbox{\texttt{\mdseries\slshape cl}} is the residue class $r(m)$, the residue $r_1$ is $1-(r \mod 2)$, and $r_2$ is defined by the equality $r(m) \cup r_2(m) = r(m/2)$. 



 For an odd prime $p$, the prime switch $\sigma_p$ is an rcwa permutation of{\nobreakspace}{\ensuremath{\mathbb Z}} with
modulus{\nobreakspace}$4p$, multiplier{\nobreakspace}$p$ and divisor{\nobreakspace}2. The prime switch $\sigma_{p,r(m)}$ has multiplier{\nobreakspace}$p$ and divisor{\nobreakspace}2, and the class where the multiplication by $p$ occurs is just $r(m)$. The key mathematical property of a prime switch is that it is a product of
class transpositions whose multiplier and divisor are coprime. 

 Prime switches can be distinguished from other rcwa mappings by their \textsf{GAP} property \texttt{IsPrimeSwitch}. \index{IsPrimeSwitch@\texttt{IsPrimeSwitch}!for an rcwa mapping} 
\begin{Verbatim}[commandchars=!@B,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>B !gapinput@Display(PrimeSwitch(3));B
  
  Wild rcwa permutation of Z with modulus 12
  
          /
          | (3n+4)/2 if n in 2(4)
          | n-1      if n in 5(6) U 8(12)
          | n+1      if n in 1(6)
   n |-> <  n/2      if n in 0(12)
          | n-3      if n in 4(12)
          | n        if n in 3(6)
          |
          java.lang.NullPointerException
  
  !gapprompt@gap>B !gapinput@Display(PrimeSwitch(3):AsClassMapping);B
  
  Wild rcwa permutation of Z with modulus 12
  
    0(12) -> 0(6)  loop
     1(6) -> 2(6)
     2(4) -> 5(6)
     3(6) -> 3(6)  id
    4(12) -> 1(12)
     5(6) -> 4(6)
    8(12) -> 7(12)
  
  !gapprompt@gap>B !gapinput@Factorization(PrimeSwitch(3));B
  [ ( 1(6), 0(8) ), ( 5(6), 4(8) ), ( 0(4), 1(6) ), ( 2(4), 5(6) ), 
    ( 2(6), 1(12) ), ( 4(6), 7(12) ) ]
  !gapprompt@gap>B !gapinput@Display(PrimeSwitch(5,3,4));B
  
  Wild rcwa permutation of Z with modulus 20
  
          /
          | n+1     if n in 0(2)
          | 5n-5    if n in 3(4)
   n |-> <  (n-1)/2 if n in 1(4) \ 1(20)
          | n-1     if n in 1(20)
          |
          java.lang.NullPointerException
  
  !gapprompt@gap>B !gapinput@Multpk(PrimeSwitch(5,3,4),5,1);B
  3(4)
  !gapprompt@gap>B !gapinput@PrimeSwitch(5,3,4) = PrimeSwitch(5,ResidueClass(3,4));B
  true
  !gapprompt@gap>B !gapinput@Factorization(PrimeSwitch(5,3,4));B
  [ ( 0(2), 1(4) ), ( 1(4), 0(10) ), ( 1(2), 0(10) ) ]
  
\end{Verbatim}
 }

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

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



 The argument \mbox{\texttt{\mdseries\slshape m}} must be an odd integer greater than{\nobreakspace}1. 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@Display(mKnot(5));A
  
  Wild rcwa permutation of Z with modulus 5
  
          /
          | 6n/5     if n in 0(5)
          | (4n+1)/5 if n in 1(5)
   n |-> <  (6n-2)/5 if n in 2(5)
          | (4n+3)/5 if n in 3(5)
          | (6n-4)/5 if n in 4(5)
          java.lang.NullPointerException
  
\end{Verbatim}
 }

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

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

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



 Currently, extracting roots is implemented for rcwa permutations of finite
order. 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@Root(ClassTransposition(0,2,1,2),100);A
  ( 0(8), 2(8), 4(8), 6(8), 1(8), 3(8), 5(8), 7(8) )
  !gapprompt@gap>A !gapinput@Display(last:CycleNotation:=false);A
  
  Tame rcwa permutation of Z with modulus 8
  
          /
          | n+2 if n in Z \ 6(8) U 7(8)
   n |-> <  n-5 if n in 6(8)
          | n-7 if n in 7(8)
          java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@last^100 = ClassTransposition(0,2,1,2);A
  true
  
\end{Verbatim}
 }

 }

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

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



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

 

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



 The mappings \mbox{\texttt{\mdseries\slshape l}} and \mbox{\texttt{\mdseries\slshape r}} must be injective, and their images must form a partition of their source. 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@twice := 2*IdentityRcwaMappingOfZ; twiceplus1 := twice+1;A
  Rcwa mapping of Z: n -> 2n
  Rcwa mapping of Z: n -> 2n + 1
  !gapprompt@gap>A !gapinput@Display(CommonRightInverse(twice,twiceplus1));A
  
  Rcwa mapping of Z with modulus 2
  
          /
          | n/2     if n in 0(2)
   n |-> <  (n-1)/2 if n in 1(2)
          |
          java.lang.NullPointerException
  
\end{Verbatim}
 }

 

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



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

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

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



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

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



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

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



 If the argument is an rcwa mapping of {\ensuremath{\mathbb Z}} in sparse
representation, an option \texttt{classes} is interpreted; if set, the step of forming the union of the residue classes
in question is omitted, and the list of residue classes is returned instead of
their union. This may save time and memory if the modulus is large. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@List([1..3],k->IncreasingOn(T^k));|
  [ 1(2), 3(4), 3(4) U 1(8) U 6(8) ]
  !gapprompt@gap>| !gapinput@List([1..3],k->DecreasingOn(T^k));|
  [ 0(2), Z \ 3(4), 0(4) U 2(8) U 5(8) ]
  !gapprompt@gap>| !gapinput@a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; # Collatz' permutation|
  !gapprompt@gap>| !gapinput@List([-2..2],k->IncreasingOn(a^k));|
  [ Z \ 1(8) U 7(8), 0(2), [  ], Z \ 0(3), 1(9) U 4(9) U 5(9) U 8(9) ]
  
\end{Verbatim}
 }

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

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



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

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

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



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

 

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



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

 

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



 Let $M$ be this matrix. Then for any two residue classes $r_1(m), r_2(m) \in R/mR$, the entry $M_{r_1(m),r_2(m)}$ is defined by 
      
\[
        M_{r_1(m),r_2(m)} \ := java.lang.NullPointerException
                 \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{\mdseries\slshape m}} and the square of the modulus of{\nobreakspace}\mbox{\texttt{\mdseries\slshape f}}. The assignment of the residue classes (mod{\nobreakspace}\mbox{\texttt{\mdseries\slshape m}}) to the rows and columns of the matrix corresponds to the ordering of the
residues in \texttt{AllResidues(Source(\mbox{\texttt{\mdseries\slshape f}}),\mbox{\texttt{\mdseries\slshape m}})}. 

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

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



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

 

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



 The returned list may also include supersets of the named residue classes
instead if \mbox{\texttt{\mdseries\slshape f}} is affine even on these. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Loops(ClassTransposition(0,2,1,2)*ClassTransposition(0,2,1,4));|
  [ 0(4), 1(4) ]
  
\end{Verbatim}
 }

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

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



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

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

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



 This operation tries to compute the \emph{contraction centre} of the rcwa mapping \mbox{\texttt{\mdseries\slshape f}}. Assuming its existence this is the unique finite subset $S_0$ of the source of{\nobreakspace}\mbox{\texttt{\mdseries\slshape f}} on which \mbox{\texttt{\mdseries\slshape f}} induces a permutation and which intersects non\texttt{\symbol{45}}trivially
with any trajectory of{\nobreakspace}\mbox{\texttt{\mdseries\slshape f}}. The mapping{\nobreakspace}\mbox{\texttt{\mdseries\slshape f}} is assumed to be \emph{contracting}, i.e. to have such a contraction centre. As in general contraction centres
are likely not computable, the methods for this operation are probabilistic
and may return wrong results. The argument \mbox{\texttt{\mdseries\slshape maxn}} is a bound on the starting value and \mbox{\texttt{\mdseries\slshape bound}} is a bound on the elements of the trajectories to be searched. If the limit \mbox{\texttt{\mdseries\slshape bound}} is exceeded, an Info message on Info level{\nobreakspace}3 of \texttt{InfoRCWA} is given. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@T := RcwaMapping([[1,0,2],[3,1,2]]);; # The Collatz mapping.|
  !gapprompt@gap>| !gapinput@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 more information.
  [ -136, -91, -82, -68, -61, -55, -41, -37, -34, -25, -17, -10, -7, -5, 
    -1, 0, 1, 2 ]
  
\end{Verbatim}
 }

 

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



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

 }

  
\section{\textcolor{Chapter }{ Saving memory \texttt{\symbol{45}}\texttt{\symbol{45}} the sparse
representation of rcwa mappings }}\label{sec:SparseRepresentationOfRcwaMappings}
\logpage{[ 2, 9, 0 ]}
\hyperdef{L}{X86F0E0D17E6A9663}{}
{
  \index{rcwa mapping@rcwa mapping!sparse representation} \index{RcwaMapping@\texttt{RcwaMapping}!by list of coefficients, sparse representation} It is quite common that an rcwa mapping with large modulus has only few
distinct affine partial mappings. In this case the ``standard'' representation which stores a coefficient triple for each residue class modulo
the modulus is unsuitable. For this reason there is a second representation of
rcwa mappings, the ``sparse'' representation. Depending on the rcwa mappings involved, using this
representation may speed up computations and reduce memory requirements by
orders of magnitude. For rcwa mappings with almost as many distinct affine
partial mappings as there are residue classes modulo the modulus, using sparse
representation makes computations slower and more
memory\texttt{\symbol{45}}consuming. Presently, the sparse representation is
only available for rcwa mappings of {\ensuremath{\mathbb Z}}. 

 The sparse representation of an rcwa mapping consists of the modulus and a
list of 5\texttt{\symbol{45}}tuples $(r,m,a_{r(m)},b_{r(m)},c_{r(m)})$ of integers. Any such 5\texttt{\symbol{45}}tuple specifies the coefficients of
the restriction $n \mapsto (a_{r(m)} \cdot n + b_{r(m)})/c_{r(m)}$ of the mapping to a residue class $r(m)$. The $r(m)$ are chosen to form the coarsest possible partition of {\ensuremath{\mathbb Z}}
into residue classes such that the restriction of the mapping to any of them
is affine. Also the list of coefficient tuples is sorted, all $c_{r(m)}$ are positive and $\gcd(c_{r(m)},\gcd(a_{r(m)},b_{r(m)})) = 1$. This way the coefficient list of an rcwa mapping of {\ensuremath{\mathbb Z}}
is unique. 

 Changing the representation of rcwa mappings does not change their behaviour
with respect to ``\texttt{=}'' and ``\texttt{{\textless}}'' The product of two rcwa mappings in sparse representation is in sparse
representation again, just like the product of two rcwa mappings in standard
representation is in standard representation. Also, inverses are in the same
representation. The product of two rcwa mappings in different representation
may be in any of the representations of the factors. 

\subsection{\textcolor{Chapter }{SparseRepresentation (of an rcwa mapping)}}
\logpage{[ 2, 9, 1 ]}\nobreak
\hyperdef{L}{X879451B17AD78B07}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SparseRepresentation({\mdseries\slshape f})\index{SparseRepresentation@\texttt{SparseRepresentation}!of an rcwa mapping}
\label{SparseRepresentation:of an rcwa mapping}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SparseRep({\mdseries\slshape f})\index{SparseRep@\texttt{SparseRep}!of an rcwa mapping}
\label{SparseRep:of an rcwa mapping}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StandardRepresentation({\mdseries\slshape f})\index{StandardRepresentation@\texttt{StandardRepresentation}!of an rcwa mapping}
\label{StandardRepresentation:of an rcwa mapping}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StandardRep({\mdseries\slshape f})\index{StandardRep@\texttt{StandardRep}!of an rcwa mapping}
\label{StandardRep:of an rcwa mapping}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 the rcwa mapping \mbox{\texttt{\mdseries\slshape f}} in sparse, respectively, standard representation. 



 Appropriate attribute values and properties are copied over to the rcwa
mapping in the ``new'' representation. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@a := ClassTransposition(1,2,4,6);|
  ( 1(2), 4(6) )
  !gapprompt@gap>| !gapinput@b := ClassTransposition(1,3,2,6);|
  ( 1(3), 2(6) )
  !gapprompt@gap>| !gapinput@c := ClassTransposition(2,3,4,6);|
  ( 2(3), 4(6) )
  !gapprompt@gap>| !gapinput@g := (b*a*c)^2*a;|
  <rcwa permutation of Z with modulus 288>
  !gapprompt@gap>| !gapinput@h := SparseRep(g);|
  <rcwa permutation of Z with modulus 288 and 21 affine parts>
  !gapprompt@gap>| !gapinput@g = h;|
  true
  !gapprompt@gap>| !gapinput@Coefficients(h);|
  [ [ 0, 6, 1, 0, 1 ], [ 1, 3, 16, -1, 3 ], [ 2, 96, 9, 14, 16 ], 
    [ 3, 24, 9, 5, 4 ], [ 5, 24, 3, 1, 4 ], [ 8, 36, 2, -7, 9 ], 
    [ 9, 48, 27, 29, 8 ], [ 11, 24, 9, 5, 4 ], [ 14, 48, 27, 38, 8 ], 
    [ 15, 24, 27, 19, 4 ], [ 17, 48, 9, 7, 8 ], [ 20, 72, 3, 4, 4 ], 
    [ 21, 24, 1, -3, 6 ], [ 23, 24, 27, 19, 4 ], [ 26, 48, 3, 2, 8 ], 
    [ 32, 36, 4, -11, 9 ], [ 33, 48, 9, 7, 8 ], [ 38, 48, 9, 10, 8 ], 
    [ 41, 48, 27, 29, 8 ], [ 50, 96, 27, 58, 16 ], [ 56, 72, 1, 0, 4 ] ]
  !gapprompt@gap>| !gapinput@h^2;|
  <rcwa permutation of Z with modulus 13824 and 71 affine parts>
  !gapprompt@gap>| !gapinput@h^3;|
  <rcwa permutation of Z with modulus 663552 and 201 affine parts>
  
\end{Verbatim}
 Memory consumption may differ a lot between sparse\texttt{\symbol{45}} and
standard representation: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@MemoryUsage(h^3);               # on a 64-bit machine|
  18254
  !gapprompt@gap>| !gapinput@MemoryUsage(StandardRep(h^3));  # on a 64-bit machine|
  42467894
\end{Verbatim}
 }

 }

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

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



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

 

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

}

 }

  }

       
\chapter{\textcolor{Chapter }{Residue\texttt{\symbol{45}}Class\texttt{\symbol{45}}Wise Affine Groups}}\label{ch:RcwaGroups}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X874A3BB684F0639A}{}
{
   In this chapter, we describe how to construct
residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine groups and how
to compute with them.  
\section{\textcolor{Chapter }{Constructing residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine
groups}}\label{sec:ContructingRcwaGroups}
\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X81242A6586A604A3}{}
{
  \index{Group@\texttt{Group}} \index{GroupByGenerators@\texttt{GroupByGenerators}} \index{GroupWithGenerators@\texttt{GroupWithGenerators}} As any other groups in \textsf{GAP}, residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine
(rcwa\texttt{\symbol{45}}) groups can be constructed by \texttt{Group}, \texttt{GroupByGenerators} or \texttt{GroupWithGenerators}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(ClassTransposition(0,2,1,4),ClassShift(0,5));|
  <rcwa group over Z with 2 generators>
  !gapprompt@gap>| !gapinput@IsTame(G); Size(G); IsSolvable(G); IsPerfect(G);|
  true
  infinity
  false
  false
  
\end{Verbatim}
 An rcwa group isomorphic to a given group can be obtained by taking the image
of a faithful rcwa representation: 

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



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

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@F := FreeProduct(Group((1,2)(3,4),(1,3)(2,4)),Group((1,2,3)),|
  !gapprompt@>| !gapinput@                    SymmetricGroup(3));|
  <fp group on the generators [ f1, f2, f3, f4, f5 ]>
  !gapprompt@gap>| !gapinput@IsomorphismRcwaGroup(F);|
  [ f1, f2, f3, f4, f5 ] -> [ <rcwa permutation of Z with modulus 12>,
    <rcwa permutation of Z with modulus 24>,
    <rcwa permutation of Z with modulus 12>,
    <rcwa permutation of Z with modulus 72>,
    <rcwa permutation of Z with modulus 36> ]
  !gapprompt@gap>| !gapinput@IsomorphismRcwaGroup(FreeGroup(2));|
  [ f1, f2 ] -> [ <wild rcwa permutation of Z with modulus 8>,
    <wild rcwa permutation of Z with modulus 8> ]
  !gapprompt@gap>| !gapinput@F2 := Image(last);|
  <wild rcwa group over Z with 2 generators>
  
\end{Verbatim}
 }

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

\subsection{\textcolor{Chapter }{DirectProduct (for rcwa groups over Z)}}
\logpage{[ 3, 1, 2 ]}\nobreak
\hyperdef{L}{X79CAE48981C11FE8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DirectProduct({\mdseries\slshape G1, G2, ...})\index{DirectProduct@\texttt{DirectProduct}!for rcwa groups over Z}
\label{DirectProduct:for rcwa groups over Z}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 an rcwa group isomorphic to the direct product of the rcwa groups
over{\nobreakspace}{\ensuremath{\mathbb Z}} given as arguments. 



 There is certainly no unique or canonical way to embed a direct product of
rcwa groups into RCWA({\ensuremath{\mathbb Z}}). This method chooses to embed
the groups \mbox{\texttt{\mdseries\slshape G1}}, \mbox{\texttt{\mdseries\slshape G2}}, \mbox{\texttt{\mdseries\slshape G3}}{\nobreakspace}... via restrictions by $n \mapsto mn$, $n \mapsto mn+1$, $n \mapsto mn+2${\nobreakspace}... ($\rightarrow${\nobreakspace}\texttt{Restriction} (\ref{Restriction:of an rcwa group, by an injective rcwa mapping})), where $m$ denotes the number of groups given as arguments. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@F2 := Image(IsomorphismRcwaGroup(FreeGroup(2)));;|
  !gapprompt@gap>| !gapinput@F2xF2 := DirectProduct(F2,F2);|
  <wild rcwa group over Z with 4 generators>
  !gapprompt@gap>| !gapinput@Image(Projection(F2xF2,1)) = F2;|
  true
  
\end{Verbatim}
 }

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



 The first\texttt{\symbol{45}}mentioned method embeds the \texttt{NrMovedPoints(\mbox{\texttt{\mdseries\slshape P}})}th direct power of{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} using the method for \texttt{DirectProduct}, and lets the permutation group{\nobreakspace}\mbox{\texttt{\mdseries\slshape P}} act naturally on the set of residue classes modulo \texttt{NrMovedPoints(\mbox{\texttt{\mdseries\slshape P}})}. The second\texttt{\symbol{45}}mentioned method restricts ($\rightarrow${\nobreakspace}\texttt{Restriction} (\ref{Restriction:of an rcwa group, by an injective rcwa mapping})) the group{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} to the residue class{\nobreakspace}3(4), and maps the generator of the
infinite cyclic group{\nobreakspace}\mbox{\texttt{\mdseries\slshape Z}} to \texttt{ClassTransposition(0,2,1,2) * ClassTransposition(0,2,1,4)}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@F2 := Image(IsomorphismRcwaGroup(FreeGroup(2)));;|
  !gapprompt@gap>| !gapinput@F2wrA5 := WreathProduct(F2,AlternatingGroup(5));;|
  !gapprompt@gap>| !gapinput@Embedding(F2wrA5,1);|
  [ <wild rcwa permutation of Z with modulus 8>,
    <wild rcwa permutation of Z with modulus 8> ] ->
  [ <wild rcwa permutation of Z with modulus 40>,
    <wild rcwa permutation of Z with modulus 40> ]
  !gapprompt@gap>| !gapinput@Embedding(F2wrA5,2);|
  [ (1,2,3,4,5), (3,4,5) ] -> [ ( 0(5), 1(5), 2(5), 3(5), 4(5) ), 
    ( 2(5), 3(5), 4(5) ) ]
  !gapprompt@gap>| !gapinput@ZwrZ := WreathProduct(Group(ClassShift(0,1)),Group(ClassShift(0,1)));|
  <wild rcwa group over Z with 2 generators>
  !gapprompt@gap>| !gapinput@Embedding(ZwrZ,1);|
  [ ClassShift( Z ) ] ->
  [ <tame rcwa permutation of Z with modulus 4, of order infinity> ]
  !gapprompt@gap>| !gapinput@Embedding(ZwrZ,2);|
  [ ClassShift( Z ) ] -> [ <wild rcwa permutation of Z with modulus 4> ]
  
\end{Verbatim}
 }

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

\subsection{\textcolor{Chapter }{MergerExtension (for finite permutation groups)}}
\logpage{[ 3, 1, 4 ]}\nobreak
\hyperdef{L}{X8794913B878DD5C4}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{MergerExtension({\mdseries\slshape G, points, point})\index{MergerExtension@\texttt{MergerExtension}!for finite permutation groups}
\label{MergerExtension:for finite permutation groups}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 roughly spoken, an extension of \mbox{\texttt{\mdseries\slshape G}} by an involution which ``merges'' \mbox{\texttt{\mdseries\slshape points}} into \mbox{\texttt{\mdseries\slshape point}}. 



 The arguments of this operation are a finite permutation group \mbox{\texttt{\mdseries\slshape G}}, a set \mbox{\texttt{\mdseries\slshape points}} of points moved by \mbox{\texttt{\mdseries\slshape G}} and a single point \mbox{\texttt{\mdseries\slshape point}} moved by \mbox{\texttt{\mdseries\slshape G}} which is not in \mbox{\texttt{\mdseries\slshape points}}. 

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

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

\subsection{\textcolor{Chapter }{GroupByResidueClasses (the group `permuting a given list of residue classes')}}
\logpage{[ 3, 1, 5 ]}\nobreak
\hyperdef{L}{X8143AB647801F438}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupByResidueClasses({\mdseries\slshape classes})\index{GroupByResidueClasses@\texttt{GroupByResidueClasses}!the group `permuting a given list of residue classes'}
\label{GroupByResidueClasses:the group `permuting a given list of residue classes'}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the group which is generated by all class transpositions which interchange
disjoint residue classes in \mbox{\texttt{\mdseries\slshape classes}}. 



 The argument \mbox{\texttt{\mdseries\slshape classes}} must be a list of residue classes. 

 If the residue classes in \mbox{\texttt{\mdseries\slshape classes}} are pairwise disjoint, then the returned group is the symmetric group on \mbox{\texttt{\mdseries\slshape classes}}. If any two residue classes in \mbox{\texttt{\mdseries\slshape classes}} intersect non\texttt{\symbol{45}}trivially, then the returned group is
trivial. In many other cases, the returned group is infinite. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := GroupByResidueClasses(List([[0,2],[0,4],[1,4],[2,4],[3,4]],|
  !gapprompt@>| !gapinput@                                   ResidueClass));|
  <rcwa group over Z with 8 generators>
  !gapprompt@gap>| !gapinput@H := Group(List([[0,2,1,2],[1,2,2,4],[0,2,1,4],[1,4,2,4]],|
  !gapprompt@>| !gapinput@                   ClassTransposition)); # Thompson's group V|
  <(0(2),1(2)),(1(2),2(4)),(0(2),1(4)),(1(4),2(4))>
  !gapprompt@gap>| !gapinput@G = H;|
  true
  
\end{Verbatim}
 }

 Various ways to construct rcwa groups are based on certain monomorphisms from
the group RCWA($R$) into itself. Examples are the constructions of direct products and wreath
products described above. The support of the image of such a monomorphism is
the image of a given injective rcwa mapping. For this reason, these
monomorphisms are called \emph{restriction monomorphisms}. The following operation computes images of rcwa mappings and
\texttt{\symbol{45}}groups under these embeddings of RCWA($R$) into itself: 
\subsection{\textcolor{Chapter }{ Restriction (of an rcwa mapping or \texttt{\symbol{45}}group, by an injective
rcwa mapping) }}\logpage{[ 3, 1, 6 ]}
\hyperdef{L}{X852EF2C079E4D7FF}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Restriction({\mdseries\slshape g, f})\index{Restriction@\texttt{Restriction}!of an rcwa mapping, by an injective rcwa mapping}
\label{Restriction:of an rcwa mapping, by an injective rcwa mapping}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Restriction({\mdseries\slshape G, f})\index{Restriction@\texttt{Restriction}!of an rcwa group, by an injective rcwa mapping}
\label{Restriction:of an rcwa group, by an injective rcwa mapping}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 the restriction of the rcwa mapping \mbox{\texttt{\mdseries\slshape g}} (respectively the rcwa group \mbox{\texttt{\mdseries\slshape G}}) by the injective rcwa mapping{\nobreakspace}\mbox{\texttt{\mdseries\slshape f}}. 



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

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

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



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

 \index{SmallGeneratingSet@\texttt{SmallGeneratingSet}} Once having constructed an rcwa group, it is sometimes possible to obtain a
smaller generating set by the operation \texttt{SmallGeneratingSet}. 

 \index{View@\texttt{View}!for an rcwa group} \index{Display@\texttt{Display}!for an rcwa group} \index{Print@\texttt{Print}!for an rcwa group} \index{String@\texttt{String}!for an rcwa group} There are methods for the operations \texttt{View}, \texttt{Display}, \texttt{Print} and \texttt{String} which are applicable to rcwa groups. 

 \index{rcwa group@rcwa group!modulus} \index{rcwa group@rcwa group!multiplier} \index{rcwa group@rcwa group!divisor} \index{rcwa group@rcwa group!prime set} \index{rcwa group@rcwa group!class-wise translating} \index{rcwa group@rcwa group!integral} \index{rcwa group@rcwa group!class-wise order-preserving} \index{rcwa group@rcwa group!sign-preserving} \index{Modulus@\texttt{Modulus}!of an rcwa group} \index{Mod@\texttt{Mod}!for an rcwa group} \index{ModulusOfRcwaMonoid@\texttt{ModulusOfRcwaMonoid}!for an rcwa group} \index{Multiplier@\texttt{Multiplier}!of an rcwa group} \index{Mult@\texttt{Mult}!for an rcwa group} \index{Divisor@\texttt{Divisor}!of an rcwa group} \index{Div@\texttt{Div}!for an rcwa group} \index{PrimeSet@\texttt{PrimeSet}!of an rcwa group} \index{IsClassWiseTranslating@\texttt{IsClassWiseTranslating}!for an rcwa group} \index{IsIntegral@\texttt{IsIntegral}!for an rcwa group} \index{IsClassWiseOrderPreserving@\texttt{IsClassWiseOrderPreserving}!for an rcwa group} \index{IsSignPreserving@\texttt{IsSignPreserving}!for an rcwa group} Basic attributes of an rcwa group which are derived from the coefficients of
its elements are \texttt{Modulus}, \texttt{Multiplier}, \texttt{Divisor} and \texttt{PrimeSet}. The \emph{modulus} of an rcwa group is the lcm of the moduli of its elements if such an lcm
exists, i.e. if the group is tame, and 0 otherwise. The \emph{multiplier} respectively \emph{divisor} of an rcwa group is the lcm of the multipliers respectively divisors of its
elements in case such an lcm exists and $\infty$ otherwise. The \emph{prime set} of an rcwa group is the union of the prime sets of its elements. There are
shorthands \texttt{Mod}, \texttt{Mult} and \texttt{Div} defined for \texttt{Modulus}, \texttt{Multiplier} and \texttt{Divisor}, respectively. An rcwa group is called \emph{class\texttt{\symbol{45}}wise translating}, \emph{integral} or \emph{class\texttt{\symbol{45}}wise order\texttt{\symbol{45}}preserving} if all of its elements are so. There are corresponding methods available for \texttt{IsClassWiseTranslating}, \texttt{IsIntegral} and \texttt{IsClassWiseOrderPreserving}. There is a property \texttt{IsSignPreserving}, which indicates whether a given rcwa group
over{\nobreakspace}{\ensuremath{\mathbb Z}} acts on the set of nonnegative
integers. The latter holds for any subgroup of CT({\ensuremath{\mathbb Z}})
(cf. below). 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(ClassTransposition(0,2,1,2),ClassTransposition(1,3,2,6),|
  !gapprompt@>| !gapinput@              ClassReflection(2,4));|
  <rcwa group over Z with 3 generators>
  !gapprompt@gap>| !gapinput@List([Modulus,Multiplier,Divisor,PrimeSet,IsClassWiseTranslating,|
  !gapprompt@>| !gapinput@         IsIntegral,IsClassWiseOrderPreserving,IsSignPreserving],f->f(G));|
  [ 24, 2, 2, [ 2, 3 ], false, false, false, false ]
  
\end{Verbatim}
 All rcwa groups over a ring $R$ are subgroups of RCWA($R$). The group RCWA($R$) itself is not finitely generated, thus cannot be constructed as described
above. It is handled as a special case: 

\subsection{\textcolor{Chapter }{RCWA (the group formed by all rcwa permutations of a ring)}}
\logpage{[ 3, 1, 8 ]}\nobreak
\hyperdef{L}{X79450C1C8756FEB3}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RCWA({\mdseries\slshape R})\index{RCWA@\texttt{RCWA}!the group formed by all rcwa permutations of a ring}
\label{RCWA:the group formed by all rcwa permutations of a ring}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the group RCWA(\mbox{\texttt{\mdseries\slshape R}}) of all residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine
permutations of the ring{\nobreakspace}\mbox{\texttt{\mdseries\slshape R}}. 



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

 Examples of rcwa permutations can be obtained via \texttt{Random(RCWA(\mbox{\texttt{\mdseries\slshape R}}))}, see Section{\nobreakspace}\ref{sec:Random}. \index{NrConjugacyClassesOfRCWAZOfOrder@\texttt{NrConjugacyClassesOfRCWAZOfOrder}} The number of conjugacy classes of RCWA({\ensuremath{\mathbb Z}}) of elements
of given order is known, cf. Corollary{\nobreakspace}2.7.1{\nobreakspace}(b)
in{\nobreakspace}\cite{Kohl05}. It can be determined by the function \texttt{NrConjugacyClassesOfRCWAZOfOrder}: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@List([2,105],NrConjugacyClassesOfRCWAZOfOrder);|
  [ infinity, 218 ]
  
\end{Verbatim}
 We denote the group which is generated by all class transpositions of the
ring{\nobreakspace}$R$ by CT($R$). This group is handled as a special case as well: 

\subsection{\textcolor{Chapter }{CT (the group generated by all class transpositions of a ring)}}
\logpage{[ 3, 1, 9 ]}\nobreak
\hyperdef{L}{X7BD42D8481300E25}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CT({\mdseries\slshape R})\index{CT@\texttt{CT}!the group generated by all class transpositions of a ring}
\label{CT:the group generated by all class transpositions of a ring}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CT({\mdseries\slshape P, Integers})\index{CT@\texttt{CT}!subgroup of CT(Z)}
\label{CT:subgroup of CT(Z)}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the group CT(\mbox{\texttt{\mdseries\slshape R}}) which is generated by all class transpositions of the ring{\nobreakspace}\mbox{\texttt{\mdseries\slshape R}}, respectively, the group CT(\mbox{\texttt{\mdseries\slshape P}},{\ensuremath{\mathbb Z}}) which is generated by all class transpositions
of{\nobreakspace}{\ensuremath{\mathbb Z}} which interchange residue classes
whose moduli have only prime factors in the finite set \mbox{\texttt{\mdseries\slshape P}}. 



 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@CT_Z := CT(Integers);|
  CT(Z)
  !gapprompt@gap>| !gapinput@IsSimpleGroup(CT_Z); # One of a number of stored attributes/properties.|
  true
  !gapprompt@gap>| !gapinput@V := CT([2],Integers);|
  CT_[ 2 ](Z)
  !gapprompt@gap>| !gapinput@GeneratorsOfGroup(V);|
  [ ( 0(2), 1(2) ), ( 1(2), 2(4) ), ( 0(2), 1(4) ), ( 1(4), 2(4) ) ]
  !gapprompt@gap>| !gapinput@G := CT([2,3],Integers); |
  CT_[ 2, 3 ](Z)
  !gapprompt@gap>| !gapinput@GeneratorsOfGroup(G);|
  [ ( 0(2), 1(2) ), ( 0(3), 1(3) ), ( 1(3), 2(3) ), ( 0(2), 1(4) ), 
    ( 0(2), 5(6) ), ( 0(3), 1(6) ) ]
  
\end{Verbatim}
 }

 \index{Mirrored@\texttt{Mirrored}} The group CT({\ensuremath{\mathbb Z}}) has an outer automorphism which is
given by conjugation with $n \mapsto -n - 1$. This automorphism can be applied to an rcwa mapping of {\ensuremath{\mathbb
Z}} or to an rcwa group over {\ensuremath{\mathbb Z}} by the operation \texttt{Mirrored}. The group \texttt{Mirrored(}\mbox{\texttt{\mdseries\slshape G}}\texttt{)} acts on the nonnegative integers as \mbox{\texttt{\mdseries\slshape G}} acts on the negative integers, and vice versa. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ct := ClassTransposition(0,2,1,6);|
  ( 0(2), 1(6) )
  !gapprompt@gap>| !gapinput@Mirrored(ct);|
  ( 1(2), 4(6) )
  !gapprompt@gap>| !gapinput@G := Group(List([[0,2,1,2],[0,3,2,3],[2,4,1,6]],ClassTransposition));;|
  !gapprompt@gap>| !gapinput@ShortOrbits(G,[-100..100],100);|
  [ [ 0 .. 5 ] ]
  !gapprompt@gap>| !gapinput@ShortOrbits(Mirrored(G),[-100..100],100);|
  [ [ -6 .. -1 ] ]
  
\end{Verbatim}
 \index{AllElementsOfCTZWithGivenModulus@\texttt{AllElementsOfCTZWithGivenModulus}} \index{NrElementsOfCTZWithGivenModulus@\texttt{NrElementsOfCTZWithGivenModulus}} Under the hypothesis that CT({\ensuremath{\mathbb Z}}) is the setwise
stabilizer of ${\ensuremath{\mathbb N}}_0$ in RCWA({\ensuremath{\mathbb Z}}), the elements of CT({\ensuremath{\mathbb
Z}}) with modulus dividing a given positive integer $m$ are parametrized by the ordered partitions of {\ensuremath{\mathbb Z}} into $m$ residue classes. The list of these elements for given $m$ can be obtained by the function \texttt{AllElementsOfCTZWithGivenModulus}, and the numbers of such elements for $m \leq 24$ are stored in the list \texttt{NrElementsOfCTZWithGivenModulus}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@NrElementsOfCTZWithGivenModulus{[1..8]};|
  [ 1, 1, 17, 238, 4679, 115181, 3482639, 124225680 ]
  
\end{Verbatim}
 \index{NrConjugacyClassesOfRCWAZOfOrder@\texttt{NrConjugacyClassesOfCTZOfOrder}} The number of conjugacy classes of CT({\ensuremath{\mathbb Z}}) of elements of
given order is also known under the hypothesis that CT({\ensuremath{\mathbb
Z}}) is the setwise stabilizer of ${\ensuremath{\mathbb N}}_0$ in RCWA({\ensuremath{\mathbb Z}}). It can be determined by the function \texttt{NrConjugacyClassesOfCTZOfOrder}. }

  
\section{\textcolor{Chapter }{ Basic routines for investigating
residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine groups }}\label{sec:InvestigatingRcwaGroups}
\logpage{[ 3, 2, 0 ]}
\hyperdef{L}{X80C042BE82EE0F9A}{}
{
  In the previous section we have seen how to construct rcwa groups. The purpose
of this section is to describe how to obtain information on the structure of
an rcwa group and on its action on the underlying ring. The easiest way to get
a little (but really only \emph{a very little}!) information on the group structure is a dedicated method for the operation \texttt{StructureDescription}: 

\subsection{\textcolor{Chapter }{StructureDescription (for an rcwa group)}}
\logpage{[ 3, 2, 1 ]}\nobreak
\hyperdef{L}{X864A7E3E87F366A8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StructureDescription({\mdseries\slshape G})\index{StructureDescription@\texttt{StructureDescription}!for an rcwa group}
\label{StructureDescription:for an rcwa group}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 a string which sometimes gives a little glimpse of the structure of the rcwa
group{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}}. 



 The attribute \texttt{StructureDescription} for finite groups is documented in the \textsf{GAP} Reference Manual. Therefore we describe here only issues which are specific to
infinite groups, and in particular to rcwa groups. 

 Wreath products are denoted by{\nobreakspace}\texttt{wr}, and free products are denoted by{\nobreakspace}\texttt{*}. The infinite cyclic group ({\ensuremath{\mathbb Z}},+) is denoted
by{\nobreakspace}\texttt{Z}, the infinite dihedral group is denoted by{\nobreakspace}\texttt{D0} and free groups of rank $2,3,4,\dots$ are denoted by{\nobreakspace}\texttt{F2}, \texttt{F3}, \texttt{F4},{\nobreakspace}$\dots$. While for finite groups the symbol{\nobreakspace}\texttt{.} is used to denote a non\texttt{\symbol{45}}split extension, for rcwa groups in
general it stands for an extension which may be split or not. For wild groups
in most cases it happens that there is a large section on which no structural
information can be obtained. Such sections of the group with unknown structure
are denoted by \texttt{{\textless}unknown{\textgreater}}. In general, the structure of a section denoted by \texttt{{\textless}unknown{\textgreater}} can be very complicated and very difficult to exhibit. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(ClassTransposition(0,2,1,4),ClassShift(0,5));;|
  !gapprompt@gap>| !gapinput@StructureDescription(G);|
  "(Z x Z x Z x Z x Z x Z x Z) . (C2 x S7)"
  !gapprompt@gap>| !gapinput@G := Group(ClassTransposition(0,2,1,4),|
  !gapprompt@>| !gapinput@              ClassShift(2,4),ClassReflection(1,2));;|
  !gapprompt@gap>| !gapinput@StructureDescription(G:short);|
  "Z^2.((S3xS3):2)"
  !gapprompt@gap>| !gapinput@F2 := Image(IsomorphismRcwaGroup(FreeGroup(2)));;|
  !gapprompt@gap>| !gapinput@PSL2Z := Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(3),|
  !gapprompt@>| !gapinput@                                                   CyclicGroup(2))));;|
  !gapprompt@gap>| !gapinput@G := DirectProduct(PSL2Z,F2);|
  <wild rcwa group over Z with 4 generators>
  !gapprompt@gap>| !gapinput@StructureDescription(G);|
  "(C3 * C2) x F2"
  !gapprompt@gap>| !gapinput@G := WreathProduct(G,CyclicGroup(IsRcwaGroupOverZ,infinity));|
  <wild rcwa group over Z with 5 generators>
  !gapprompt@gap>| !gapinput@StructureDescription(G);|
  "((C3 * C2) x F2) wr Z"
  !gapprompt@gap>| !gapinput@Collatz := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);;|
  !gapprompt@gap>| !gapinput@G := Group(Collatz,ClassShift(0,1));;|
  !gapprompt@gap>| !gapinput@StructureDescription(G:short);|
  "<unknown>.Z"
  
\end{Verbatim}
 }

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

 \index{Size@\texttt{Size}!for an rcwa group} The order of an rcwa group can be computed by the operation \texttt{Size}. An rcwa group is finite if and only if it is tame and its action on a
suitably chosen respected partition (see{\nobreakspace}\texttt{RespectedPartition} (\ref{RespectedPartition:of a tame rcwa group})) is faithful. Hence the problem of computing the order of an rcwa group
reduces to the problem of deciding whether it is tame, the problem of deciding
whether it acts faithfully on a respected partition and the problem of
computing the order of the finite permutation group induced on the respected
partition. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(ClassTransposition(0,2,1,2),ClassTransposition(1,3,2,3),|
  !gapprompt@>| !gapinput@              ClassReflection(0,5));|
  <rcwa group over Z with 3 generators>
  !gapprompt@gap>| !gapinput@Size(G);|
  46080
  
\end{Verbatim}
 \index{IsomorphismPermGroup@\texttt{IsomorphismPermGroup}!for a finite rcwa group} For a finite rcwa group, an isomorphism to a permutation group can be computed
by \texttt{IsomorphismPermGroup}: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(ClassTransposition(0,2,1,2),ClassTransposition(0,3,1,3));;|
  !gapprompt@gap>| !gapinput@IsomorphismPermGroup(G);|
  [ ( 0(2), 1(2) ), ( 0(3), 1(3) ) ] -> [ (1,2)(3,4)(5,6), (1,2)(4,5) ]
  
\end{Verbatim}
 \index{rcwa group@rcwa group!membership test} \index{OrbitLengthBound@\texttt{OrbitLengthBound}} In general the membership problem for rcwa groups is algorithmically
unsolvable, see Corollary{\nobreakspace}4.5 in{\nobreakspace}\cite{Kohl09}. A consequence of this is that a membership test ``\texttt{g in G}'' may run into an infinite loop if the rcwa permutation \texttt{g} is not an element of the rcwa group \texttt{G}. For tame rcwa groups however membership can always be decided. For wild rcwa
groups, membership can very often be decided quite quick as well, but
\texttt{\symbol{45}}\texttt{\symbol{45}} as said
\texttt{\symbol{45}}\texttt{\symbol{45}} not always. Anyway, if \texttt{g} is contained in \texttt{G}, the membership test will eventually always return \texttt{true}, provided that there are sufficient computing resources available (memory
etc.). 

 On Info level{\nobreakspace}2 of \texttt{InfoRCWA} the membership test provides information on reasons why the given rcwa
permutation is an element of the given rcwa group or{\nobreakspace}not. 

 The membership test ``\texttt{g in G}'' recognizes an option \texttt{OrbitLengthBound}. If this option is set, it returns \texttt{false} once it has computed balls of size exceeding \texttt{OrbitLengthBound} about 1 and \texttt{g} in \texttt{G}, and these balls are still disjoint. Note however that due to the algorithmic
unsolvability of the membership problem, \textsf{RCWA} has no means to check the correctness of such bound in a given case. So the
correct use of this option has to remain within the full responsibility of the
user. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(ClassShift(0,3),ClassTransposition(0,3,2,6));;|
  !gapprompt@gap>| !gapinput@ ClassShift(2,6)^7 * ClassTransposition(0,3,2,6)|
  !gapprompt@>| !gapinput@  * ClassShift(0,3)^-3 in G;|
  true
  !gapprompt@gap>| !gapinput@ClassShift(0,1) in G;|
  false
  
\end{Verbatim}
 \index{rcwa group@rcwa group!conjugacy problem} \index{IsConjugate@\texttt{IsConjugate}!for elements of RCWA(R)} \index{IsConjugate@\texttt{IsConjugate}!for elements of CT(R)} The conjugacy problem for rcwa groups is difficult, and \textsf{RCWA} provides only methods to solve it in some reasonably easy cases. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@IsConjugate(RCWA(Integers),|
  !gapprompt@>| !gapinput@               ClassTransposition(0,2,1,4),ClassShift(0,1));|
  false
  !gapprompt@gap>| !gapinput@IsConjugate(CT(Integers),ClassTransposition(0,2,1,6),|
  !gapprompt@>| !gapinput@                            ClassTransposition(1,4,0,8));|
  true
  !gapprompt@gap>| !gapinput@g := RepresentativeAction(CT(Integers),ClassTransposition(0,2,1,6),|
  !gapprompt@>| !gapinput@                                          ClassTransposition(1,4,0,8));|
  <rcwa permutation of Z with modulus 48>
  !gapprompt@gap>| !gapinput@ClassTransposition(0,2,1,6)^g = ClassTransposition(1,4,0,8);|
  true
  
\end{Verbatim}
 \index{IsTame@\texttt{IsTame}!for an rcwa group} There is a property \texttt{IsTame} which indicates whether an rcwa group is tame or not: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(ClassTransposition(0,2,1,4),ClassShift(1,3));;|
  !gapprompt@gap>| !gapinput@H := Group(ClassTransposition(0,2,1,6),ClassShift(1,3));;|
  !gapprompt@gap>| !gapinput@IsTame(G);|
  true
  !gapprompt@gap>| !gapinput@IsTame(H);|
  false
  
\end{Verbatim}
 \index{IsSolvableGroup@\texttt{IsSolvableGroup}!for an rcwa group} \index{IsPerfectGroup@\texttt{IsPerfectGroup}!for an rcwa group} \index{DerivedSubgroup@\texttt{DerivedSubgroup}!of an rcwa group} \index{Index@\texttt{Index}!for rcwa groups} \index{IsomorphismMatrixGroup@\texttt{IsomorphismMatrixGroup}!for an rcwa group} \index{Exponent@\texttt{Exponent}!of an rcwa group} For tame rcwa groups, there are methods for \texttt{IsSolvableGroup} and \texttt{IsPerfectGroup} available, and usually derived subgroups and subgroup indices can be computed
as well. Linear representations of tame groups over the rationals can be
determined by the operation \texttt{IsomorphismMatrixGroup}. Testing a wild group for solvability or perfectness is currently not always
feasible, and wild groups have in general no faithful
finite\texttt{\symbol{45}}dimensional linear representations. There is a
method for \texttt{Exponent} available, which works basically for any rcwa group. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(ClassTransposition(0,2,1,4),ClassShift(1,2));;|
  !gapprompt@gap>| !gapinput@IsPerfect(G);|
  false
  !gapprompt@gap>| !gapinput@IsSolvable(G);|
  true
  !gapprompt@gap>| !gapinput@D1 := DerivedSubgroup(G);; D2 := DerivedSubgroup(D1);;|
  !gapprompt@gap>| !gapinput@IsAbelian(D2);|
  true
  !gapprompt@gap>| !gapinput@Index(G,D1); Index(D1,D2);|
  infinity
  9
  !gapprompt@gap>| !gapinput@StructureDescription(G); StructureDescription(D1);|
  "(Z x Z x Z) . S3"
  "(Z x Z) . C3"
  !gapprompt@gap>| !gapinput@Q := D1/D2;|
  Group([ (), (1,2,4)(3,5,7)(6,8,9), (1,3,6)(2,5,8)(4,7,9) ])
  !gapprompt@gap>| !gapinput@StructureDescription(Q); |
  "C3 x C3"
  !gapprompt@gap>| !gapinput@Exponent(G);|
  infinity
  !gapprompt@gap>| !gapinput@phi := IsomorphismMatrixGroup(G);;|
  !gapprompt@gap>| !gapinput@Display(Image(phi,ClassTransposition(0,2,1,4)));|
  [ [     0,     0,   1/2,  -1/2,     0,     0 ], 
    [     0,     0,     0,     1,     0,     0 ], 
    [     2,     1,     0,     0,     0,     0 ], 
    [     0,     1,     0,     0,     0,     0 ], 
    [     0,     0,     0,     0,     1,     0 ], 
    [     0,     0,     0,     0,     0,     1 ] ]
  
\end{Verbatim}
 When investigating a group, a basic task is to find relations among the
generators: 

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



 The argument \mbox{\texttt{\mdseries\slshape r}} is the ``search radius'', i.e. the radius of the ball around{\nobreakspace}1 which is scanned for
relations. In general, the larger \mbox{\texttt{\mdseries\slshape r}} is chosen the smaller the kernel of the returned epimorphism is. If the
group{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} has finite presentations, the kernel will in principle get trivial provided
that \mbox{\texttt{\mdseries\slshape r}} is chosen large enough. If the optional argument \mbox{\texttt{\mdseries\slshape maxparts}} is given, it limits the search space to elements with at most \mbox{\texttt{\mdseries\slshape maxparts}} affine parts. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@a := ClassTransposition(2,4,3,4);;|
  !gapprompt@gap>| !gapinput@b := ClassTransposition(4,6,8,12);;|
  !gapprompt@gap>| !gapinput@c := ClassTransposition(3,4,4,6);;|
  !gapprompt@gap>| !gapinput@G := SparseRep(Group(a,b,c));|
  <(2(4),3(4)),(4(6),8(12)),(3(4),4(6))>
  !gapprompt@gap>| !gapinput@phi := EpimorphismFromFpGroup(G,6);|
  #I  there are 3 generators and 12 relators of total length 330
  #I  there are 3 generators and 11 relators of total length 312
  [ a, b, c ] -> [ ( 2(4), 3(4) ), ( 4(6), 8(12) ), ( 3(4), 4(6) ) ]
  !gapprompt@gap>| !gapinput@RelatorsOfFpGroup(Source(phi));|
  [ a^2, b^2, c^2, (b*c)^3, (a*b)^6, (a*b*c*b)^3, (a*c*b*c)^3, 
    (a*b*a*c)^12, ((a*b)^2*a*c)^12, (a*b*(a*c)^2)^12, (a*b*c*a*c*b)^12 ]
  
\end{Verbatim}
 }

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

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



 The epimorphism \mbox{\texttt{\mdseries\slshape phi}} must map the generators of the free group to the generators of the rcwa group
one\texttt{\symbol{45}}by\texttt{\symbol{45}}one. 

 This method can be used for factoring elements of rcwa groups into generators.
The implementation is based on \texttt{RepresentativeActionPreImage}, see \texttt{RepresentativeAction} (\ref{RepresentativeAction:G, source, destination, action}). 

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

 }

  
\section{\textcolor{Chapter }{ The natural action of an rcwa group on the underlying ring }}\label{sec:ActionOnR}
\logpage{[ 3, 3, 0 ]}
\hyperdef{L}{X8151BE577FFDCE87}{}
{
  Knowing a natural permutation representation of a group usually helps
significantly in computing in it and in obtaining results on its structure.
This holds particularly for the natural action of an rcwa group on its
underlying ring. In this section we describe \textsf{RCWA}'s functionality related to this action. 

 \index{Support@\texttt{Support}!of an rcwa group} \index{MovedPoints@\texttt{MovedPoints}!of an rcwa group} \index{IsTransitive@\texttt{IsTransitive}!for an rcwa group, on its underlying ring} The support, i.e. the set of moved points, of an rcwa group can be determined
by \texttt{Support} or \texttt{MovedPoints} (these are synonyms). Testing for transitivity on the underlying ring or on a
union of residue classes thereof is often feasible: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(ClassTransposition(1,2,0,4),ClassShift(0,2));;|
  !gapprompt@gap>| !gapinput@IsTransitive(G,Integers);|
  true
  
\end{Verbatim}
 
\index{IsTransitiveOnNonnegativeIntegersInSupport@\texttt{IsTransitiveOnNonnegativeIntegersIn- Support}!for an rcwa group over Z}
\index{TryIsTransitiveOnNonnegativeIntegersInSupport@\texttt{TryIsTransitiveOnNonnegativeIntegers- InSupport}!for an rcwa group over Z and a search limit}
  \index{TransitivityCertificate@\texttt{TransitivityCertificate}!for an rcwa group over Z and a search limit} \index{TryToComputeTransitivityCertificate@\texttt{TryToComputeTransitivityCertificate}!for an rcwa group over Z and a search limit} \index{SimplifiedCertificate@\texttt{SimplifiedCertificate}!for a transitivity certificate of an rcwa groups over Z} Groups generated by class transpositions of the integers act on the set of
nonnegative integers. There is a property \texttt{IsTransitiveOnNonnegativeIntegersInSupport(\mbox{\texttt{\mdseries\slshape G}})} which indicates whether such group acts transitively on the set of nonnegative
integers in its support. Since such transitivity test is a computationally
hard problem, methods may fail. If \texttt{IsTransitiveOnNonnegativeIntegersInSupport} returns \texttt{true}, an attribute \texttt{TransitivityCertificate} is set; this is a record containing components \texttt{phi}, \texttt{words}, \texttt{classes}, \texttt{smallpointbound}, \texttt{status} and \texttt{complete} as follows: 
\begin{description}
\item[{\texttt{phi}}]  is an epimorphism from a free group to \mbox{\texttt{\mdseries\slshape G}} which maps generators to generators. 
\item[{\texttt{words}, \texttt{classes}}]  two lists. \texttt{\symbol{45}}\texttt{\symbol{45}} \texttt{words[i]} is a preimage under \texttt{phi} of an element of \mbox{\texttt{\mdseries\slshape G}} which maps all sufficiently large positive integers in the residue classes \texttt{classes[i]} to smaller nonnegative integers. 
\item[{\texttt{smallpointbound}}]  in addition to finding a list of group elements $g_i$ such that for any large enough integer $n$ in the support of \mbox{\texttt{\mdseries\slshape G}} there is some $g_i$ such that $n^{g_i} < n$, for verifying transitivity it was necessary to check that all integers less
than or equal to \texttt{smallpointbound} in the support of \mbox{\texttt{\mdseries\slshape G}} lie in the same orbit. 
\item[{\texttt{status}}]  the string \texttt{"transitive"} in case all checks have been completed successfully. 
\item[{\texttt{complete}}]  \texttt{true} in case all checks have been completed successfully. 
\end{description}
 Parts of this information for possibly intransitive groups can be obtained by
the operation \texttt{TryToComputeTransitivityCertificate(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape searchlimit}})}, where \mbox{\texttt{\mdseries\slshape searchlimit}} is the maximum radius about a point within which smaller points are searched
and taken into consideration. This operation interprets an option \texttt{abortdensity} \texttt{\symbol{45}}\texttt{\symbol{45}} if set, the operation returns the
data computed so far once the density of the set of positive integers in the
support of \mbox{\texttt{\mdseries\slshape G}} for which no group element is found which maps them to smaller integers
reaches or drops below \texttt{abortdensity}. A simplified certificate can be obtained via \texttt{SimplifiedCertificate(\mbox{\texttt{\mdseries\slshape cert}})}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(List([[0,2,1,2],[0,3,2,3],[1,2,2,4]],|
  !gapprompt@>| !gapinput@                   ClassTransposition));|
  <(0(2),1(2)),(0(3),2(3)),(1(2),2(4))>
  !gapprompt@gap>| !gapinput@IsTransitiveOnNonnegativeIntegersInSupport(G);|
  true
  !gapprompt@gap>| !gapinput@TransitivityCertificate(G);|
  rec( 
    classes := [ [ 1(2) ], [ 2(6) ], [ 6(12), 10(12) ], [ 0(12) ], 
        [ 4(12) ] ], complete := true, 
    phi := [ a, b, c ] -> [ ( 0(2), 1(2) ), ( 0(3), 2(3) ), ( 1(2), 2(4) ) 
       ], smallpointbound := 4, status := "transitive", 
    words := [ a, b, c, b*c, a*b ] )
  !gapprompt@gap>| !gapinput@SimplifiedCertificate(last);|
  rec( classes := [ [ 1(2) ], [ 2(4) ], [ 4(12) ], [ 0(12), 8(12) ] ], 
    complete := true, 
    phi := [ a, b, c ] -> [ ( 0(2), 1(2) ), ( 0(3), 2(3) ), ( 1(2), 2(4) ) 
       ], smallpointbound := 4, status := "transitive", 
    words := [ a, c, a*b, b*c ] )
  !gapprompt@gap>| !gapinput@G := Group(List([[0,2,1,2],[1,2,2,4],[1,4,2,6]],|
  !gapprompt@>| !gapinput@                   ClassTransposition));              # '3n+1 group'|
  <(0(2),1(2)),(1(2),2(4)),(1(4),2(6))>
  !gapprompt@gap>| !gapinput@cert := TryToComputeTransitivityCertificate(G,10);|
  rec(
    classes := [ [ 1(2) ], [ 2(4) ], [ 4(32) ], [ 8(24), 44(48), 20(96) ], 
        [ 0(24), 16(24) ] ], complete := false, 
    phi := [ a, b, c ] -> [ ( 0(2), 1(2) ), ( 1(2), 2(4) ), ( 1(4), 2(6) ) 
       ], remaining := [ 12(48), 28(48), 52(96), 84(96) ], 
    smallpointbound := 42, status := "unclear", 
    words := [ a, b, (a*c)^2*b*a*b, c, a*c*b ] )
  !gapprompt@gap>| !gapinput@Union(Flat(cert.classes));|
  <union of 90 residue classes (mod 96) (6 classes)>
  !gapprompt@gap>| !gapinput@Difference(Integers,Union(Flat(cert.classes)));|
  12(48) U 28(48) U 52(96) U 84(96)
  !gapprompt@gap>| !gapinput@cert := TryToComputeTransitivityCertificate(G,20); # try larger bound|
  rec(
    classes := [ [ 1(2) ], [ 2(4) ], [ 4(32) ], [ 8(24), 44(48), 20(96) ], 
        [ 0(24), 16(24) ], [ 12(768), 268(768) ], [ 28(768), 540(768) ] ], 
    complete := false, 
    phi := [ a, b, c ] -> [ ( 0(2), 1(2) ), ( 1(2), 2(4) ), ( 1(4), 2(6) ) 
       ], 
    remaining := [ 52(96), 84(96), 60(192), 108(192), 124(192), 172(192), 
        76(384), 204(384), 220(384), 348(384), 156(768), 396(768), 
        412(768), 652(768) ], smallpointbound := 1074, status := "unclear", 
    words := [ a, b, (a*c)^2*b*a*b, c, a*c*b, (a*c)^3*b*c*b*a*b, 
        (a*c)^4*b*a*b*a*b ] )
  !gapprompt@gap>| !gapinput@Difference(Integers,Union(Flat(cert.classes)));|
  <union of 44 residue classes (mod 768) (14 classes)>
  !gapprompt@gap>| !gapinput@Intersection([0..100],last);|
  [ 52, 60, 76, 84 ]
  
\end{Verbatim}
 \index{SupersetOfOrbitRepresentatives@\texttt{SupersetOfOrbitRepresentatives}!for an rcwa group over Z and search limits} Let \mbox{\texttt{\mdseries\slshape G}} be a subgroup of CT({\ensuremath{\mathbb Z}}). Then, a set which has
nontrivial intersection with every orbit of \mbox{\texttt{\mdseries\slshape G}} on ${\ensuremath{\mathbb N}}_0$ can be determined by the operation \texttt{SupersetOfOrbitRepresentatives(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape maxsaddle}},\mbox{\texttt{\mdseries\slshape maxprog}})}. This operation returns a record with the following components: 
\begin{description}
\item[{\texttt{R}}]  A set which \texttt{\symbol{45}}\texttt{\symbol{45}} possibly among other
numbers \texttt{\symbol{45}}\texttt{\symbol{45}} contains the smallest
representatives of all the orbits of \mbox{\texttt{\mdseries\slshape G}} on the nonnegative integers. The parameters \mbox{\texttt{\mdseries\slshape maxsaddle}} and \mbox{\texttt{\mdseries\slshape maxprog}} can be used to control the size of this set. In general, larger values may
make the set smaller. 
\item[{\texttt{D}}]  A list of residue class unions whose union is a (not necessarily proper)
superset the complement of \texttt{R} in {\ensuremath{\mathbb Z}}. The intersection of \texttt{R} and the union of the sets in \texttt{D} is always finite. 
\item[{\texttt{g}}]  A list of elements of \mbox{\texttt{\mdseries\slshape G}} such that \texttt{n\texttt{\symbol{94}}g[i] {\textless} n} for all sufficiently large \texttt{n} in \texttt{D[i]}, for \texttt{i = 1, ... , Length(g) = Length(D)}. 
\item[{\texttt{phi}}]  An epimorphism from a free group \texttt{F} of rank the number of generators of \mbox{\texttt{\mdseries\slshape G}} to \mbox{\texttt{\mdseries\slshape G}} which maps generators to generators. 
\item[{\texttt{w}}]  A list of words \texttt{w[i]} in \texttt{F} such that \texttt{w[i]\texttt{\symbol{94}}phi = g[i]}, for \texttt{i = 1, ... , Length(w) = Length(g)}. 
\end{description}
 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(ClassTransposition(1,3,2,3),ClassTransposition(3,4,4,6),|
  !gapprompt@>| !gapinput@              ClassTransposition(2,4,1,6));|
  <(1(3),2(3)),(3(4),4(6)),(2(4),1(6))>
  !gapprompt@gap>| !gapinput@R := SupersetOfOrbitRepresentatives(G,4,6);|
  rec( D := [ 2(3), 4(6), 1(6) ], R := 0(3) U [ 1 ], 
    g := 
      [ ( 1(3), 2(3) ), <rcwa permutation of Z with modulus 12 and 
          5 affine parts>, <rcwa permutation of Z with modulus 12 and 
          5 affine parts> ], 
    pi := [ a, b, c ] -> [ ( 1(3), 2(3) ), ( 3(4), 4(6) ), ( 2(4), 1(6) ) ], 
    w := [ a, b, c ] )
  
\end{Verbatim}
 Further, there are methods to compute orbits under the action of an rcwa
group: 
\subsection{\textcolor{Chapter }{ Orbit (for an rcwa group and either a point or a set) }}\logpage{[ 3, 3, 1 ]}
\hyperdef{L}{X7C046BE97EE53692}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Orbit({\mdseries\slshape G, point})\index{Orbit@\texttt{Orbit}!for an rcwa group and a point}
\label{Orbit:for an rcwa group and a point}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Orbit({\mdseries\slshape G, set})\index{Orbit@\texttt{Orbit}!for an rcwa group and a set}
\label{Orbit:for an rcwa group and a set}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 the orbit of the point{\nobreakspace}\mbox{\texttt{\mdseries\slshape point}} respectively the set{\nobreakspace}\mbox{\texttt{\mdseries\slshape set}} under the natural action of the rcwa group{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} on its underlying ring. 



 The second argument can either be an element or a subset of the underlying
ring of the rcwa group{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}}. Since orbits under the action of rcwa groups can be finite or infinite, and
since infinite orbits are not necessarily residue class unions, the orbit may
either be returned in the form of a list, in the form of a residue class union
or in the form of an orbit object. It is possible to loop over orbits returned
as orbit objects, they can be compared and there is a membership test for
them. However note that equality and membership for such orbits cannot always
be decided. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(ClassShift(0,2),ClassTransposition(0,3,1,3));|
  <rcwa group over Z with 2 generators>
  !gapprompt@gap>| !gapinput@Orbit(G,0);|
  Z \ 5(6)
  !gapprompt@gap>| !gapinput@Orbit(G,5);|
  [ 5 ]
  !gapprompt@gap>| !gapinput@Orbit(G,ResidueClass(0,2));|
  [ 0(2), 1(6) U 2(6) U 3(6), 1(3) U 3(6), 0(3) U 1(6), 0(3) U 4(6), 
    1(3) U 0(6), 0(3) U 2(6), 0(6) U 1(6) U 2(6), 2(6) U 3(6) U 4(6), 
    1(3) U 2(6) ]
  !gapprompt@gap>| !gapinput@Length(Orbit(G,ResidueClass(0,4)));|
  80
  !gapprompt@gap>| !gapinput@G := Group(ClassTransposition(0,2,1,2),ClassTransposition(0,2,1,4),|
  !gapprompt@>| !gapinput@              ClassReflection(0,3));|
  <rcwa group over Z with 3 generators>
  !gapprompt@gap>| !gapinput@orb := Orbit(G,2);|
  <orbit of 2 under <wild rcwa group over Z with 3 generators>>
  !gapprompt@gap>| !gapinput@1015808 in orb;|
  true
  !gapprompt@gap>| !gapinput@First(orb,n->ForAll([n,n+2,n+6,n+8,n+30,n+32,n+36,n+38],IsPrime));|
  -19
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{GrowthFunctionOfOrbit (for an rcwa group, a point and bounds on radius and sphere size)}}
\logpage{[ 3, 3, 2 ]}\nobreak
\hyperdef{L}{X7B7A3AF97D195E33}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GrowthFunctionOfOrbit({\mdseries\slshape G, n, r{\textunderscore}max, size{\textunderscore}max})\index{GrowthFunctionOfOrbit@\texttt{GrowthFunctionOfOrbit}!for an rcwa group, a point and bounds on radius and sphere size}
\label{GrowthFunctionOfOrbit:for an rcwa group, a point and bounds on radius and sphere size}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GrowthFunctionOfOrbit({\mdseries\slshape orb, r{\textunderscore}max, size{\textunderscore}max})\index{GrowthFunctionOfOrbit@\texttt{GrowthFunctionOfOrbit}!for an rcwa group orbit and bounds on radius and sphere size}
\label{GrowthFunctionOfOrbit:for an rcwa group orbit and bounds on radius and sphere size}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 a list whose ($r+1$)\texttt{\symbol{45}}th entry is the size of the sphere of radius $r$ about \mbox{\texttt{\mdseries\slshape n}} under the action of the group \mbox{\texttt{\mdseries\slshape G}}, where the argument \mbox{\texttt{\mdseries\slshape r{\textunderscore}max}} is the largest possible radius to be considered, and the computation stops
once the sphere size exceeds \mbox{\texttt{\mdseries\slshape size{\textunderscore}max}}. 



 An option \texttt{"small"} is interpreted \texttt{\symbol{45}}\texttt{\symbol{45}} see example below. In
place of the group \mbox{\texttt{\mdseries\slshape G}} and the point \mbox{\texttt{\mdseries\slshape n}}, one can pass as first argument also an rcwa group orbit object \mbox{\texttt{\mdseries\slshape orb}}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(List([[0,4,1,4],[0,3,5,6],[0,4,5,6]],ClassTransposition));|
  <(0(4),1(4)),(0(3),5(6)),(0(4),5(6))>
  !gapprompt@gap>| !gapinput@GrowthFunctionOfOrbit(G,18,100,20);|
  [ 1, 1, 2, 3, 4, 3, 4, 4, 4, 4, 3, 3, 3, 4, 3, 4, 4, 5, 5, 6, 8, 6, 5, 
    5, 4, 3, 3, 4, 4, 4, 3, 3, 5, 4, 5, 6, 5, 2, 3, 3, 2, 3, 3, 4, 5, 4, 
    4, 4, 6, 5, 5, 3, 4, 2, 3, 4, 4, 2, 3, 4, 4, 2, 3, 3, 4, 3, 5, 3, 5, 
    4, 5, 6, 5, 3, 4, 5, 6, 5, 4, 3, 5, 4, 5, 5, 4, 4, 5, 5, 3, 4, 5, 3, 
    3, 4, 5, 4, 2, 3, 4, 4, 4 ]
  !gapprompt@gap>| !gapinput@last = GrowthFunctionOfOrbit(Orbit(G,18),100,20);|
  true
  !gapprompt@gap>| !gapinput@GrowthFunctionOfOrbit(G,18,20,20:small:=[0..100]);|
  rec( smallpoints := [ 18, 24, 25, 27, 30, 32, 33, 36, 37, 39, 40, 41, 
        42, 44, 45, 48, 49, 51, 52, 53, 56, 57, 59, 60, 61, 64, 65, 66, 
        68, 69, 71, 75, 76, 77, 80, 81, 83, 88, 89, 92, 93, 95, 100 ], 
    spheresizes := [ 1, 1, 2, 3, 4, 3, 4, 4, 4, 4, 3, 3, 3, 4, 3, 4, 4, 5, 
        5, 6, 8 ] )
  !gapprompt@gap>| !gapinput@G := Group(List([[0,2,1,2],[1,2,2,4],[1,4,2,6]],ClassTransposition));|
  <(0(2),1(2)),(1(2),2(4)),(1(4),2(6))>
  !gapprompt@gap>| !gapinput@GrowthFunctionOfOrbit(G,0,100,10000);|
  [ 1, 1, 1, 1, 1, 1, 1, 2, 3, 3, 4, 5, 7, 6, 7, 9, 12, 14, 19, 21, 28, 
    29, 37, 42, 55, 57, 72, 78, 99, 113, 148, 164, 215, 226, 288, 344, 
    462, 478, 612, 686, 894, 985, 1284, 1416, 1847, 2018, 2620, 2902, 
    3786, 4167, 5432, 5958, 7749, 8568, 11178 ]
  
\end{Verbatim}
 }

 \index{DistanceToNextSmallerPointInOrbit@\texttt{DistanceToNextSmallerPointInOrbit}} Given an rcwa group \mbox{\texttt{\mdseries\slshape G}} over {\ensuremath{\mathbb Z}} and an integer \mbox{\texttt{\mdseries\slshape n}}, \texttt{DistanceToNextSmallerPointInOrbit(}\mbox{\texttt{\mdseries\slshape G}}\texttt{,}\mbox{\texttt{\mdseries\slshape n}}\texttt{)} computes the smallest number $d$ such that there is a product $g$ of $d$ generators or inverses of generators of \mbox{\texttt{\mdseries\slshape G}} which maps \mbox{\texttt{\mdseries\slshape n}} to an integer with absolute value less than |\mbox{\texttt{\mdseries\slshape n}}|, provided that the orbit of \mbox{\texttt{\mdseries\slshape n}} contains such integer. \textsf{RCWA} provides a function to draw pictures of orbits of rcwa groups
on{\nobreakspace}${\ensuremath{\mathbb Z}}^2$. The pictures are written to files in bitmap\texttt{\symbol{45}}
(bmp\texttt{\symbol{45}}) format. The author has successfully tested this
feature both under Linux and under Windows, and the generated pictures can be
processed further with many common graphics programs: 

\subsection{\textcolor{Chapter }{DrawOrbitPicture (G, p0, bound, h, w, colored, palette, filename)}}
\logpage{[ 3, 3, 3 ]}\nobreak
\hyperdef{L}{X7D9DFAC97F9F0891}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DrawOrbitPicture({\mdseries\slshape G, p0, bound, h, w, colored, palette, filename})\index{DrawOrbitPicture@\texttt{DrawOrbitPicture}!G, p0, bound, h, w, colored, palette, filename}
\label{DrawOrbitPicture:G, p0, bound, h, w, colored, palette, filename}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing. 



 Draws a picture of the orbit(s) of the point(s) \mbox{\texttt{\mdseries\slshape p0}} under the action of the group \mbox{\texttt{\mdseries\slshape G}} on{\nobreakspace}${\ensuremath{\mathbb Z}}^2$. The argument \mbox{\texttt{\mdseries\slshape p0}} is either one point or a list of points. The argument \mbox{\texttt{\mdseries\slshape bound}} denotes the bound to which the ball about \mbox{\texttt{\mdseries\slshape p0}} is to be computed, in terms of absolute values of coordinates. The size of the
generated picture is \mbox{\texttt{\mdseries\slshape h}}{\nobreakspace}x{\nobreakspace}\mbox{\texttt{\mdseries\slshape w}} pixels. The argument \mbox{\texttt{\mdseries\slshape colored}} is a boolean which indicates whether a 24\texttt{\symbol{45}}bit true color
picture or a monochrome picture should be generated. In the former case, \mbox{\texttt{\mdseries\slshape palette}} must be a list of triples of integers in the range $0, \dots, 255$, denoting the RGB values of the colors to be used. In the latter case, \mbox{\texttt{\mdseries\slshape palette}} is not used, and any value can be passed. The picture is written in
bitmap\texttt{\symbol{45}} (bmp\texttt{\symbol{45}}) format to a file named \mbox{\texttt{\mdseries\slshape filename}}. This is done using the utility function \texttt{SaveAsBitmapPicture} from \textsf{ResClasses}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@PSL2Z := Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(2),|
  !gapprompt@>| !gapinput@                                                   CyclicGroup(3))));;|
  !gapprompt@gap>| !gapinput@DrawOrbitPicture(PSL2Z,[0,1],2000,512,512,false,fail,"example1.bmp");|
  !gapprompt@gap>| !gapinput@DrawOrbitPicture(PSL2Z,Combinations([1..4],2),2000,512,512,true,|
  !gapprompt@>| !gapinput@                    [[255,0,0],[0,255,0],[0,0,255]],"example2.bmp");|
  
\end{Verbatim}
 }

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

 Finite orbits give rise to finite quotients of a group, and finite cycles can
help to check for conjugacy. Therefore it is important to be able to determine
them: 
\subsection{\textcolor{Chapter }{ ShortOrbits (for rcwa groups) \& ShortCycles (for rcwa permutations) }}\logpage{[ 3, 3, 4 ]}
\hyperdef{L}{X78F145197F63A25D}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ShortOrbits({\mdseries\slshape G, S, maxlng})\index{ShortOrbits@\texttt{ShortOrbits}!for rcwa group, set of points and bound on length}
\label{ShortOrbits:for rcwa group, set of points and bound on length}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ShortOrbits({\mdseries\slshape G, S, maxlng, maxn})\index{ShortOrbits@\texttt{ShortOrbits}!for rcwa group, set of points and bounds on length and points}
\label{ShortOrbits:for rcwa group, set of points and bounds on length and points}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ShortCycles({\mdseries\slshape g, S, maxlng})\index{ShortCycles@\texttt{ShortCycles}!for rcwa permutation, set of points and bound on length}
\label{ShortCycles:for rcwa permutation, set of points and bound on length}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ShortCycles({\mdseries\slshape g, S, maxlng, maxn})\index{ShortCycles@\texttt{ShortCycles}!for rcwa permutation, set of points and bounds on length and points}
\label{ShortCycles:for rcwa permutation, set of points and bounds on length and points}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ShortCycles({\mdseries\slshape g, maxlng})\index{ShortCycles@\texttt{ShortCycles}!for rcwa permutation and bound on length}
\label{ShortCycles:for rcwa permutation and bound on length}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 in the first form a list of all orbits of the rcwa group{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} of length at most \mbox{\texttt{\mdseries\slshape maxlng}} which intersect non\texttt{\symbol{45}}trivially with the set{\nobreakspace}\mbox{\texttt{\mdseries\slshape S}}. In the second form a list of all orbits of the rcwa group{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} of length at most \mbox{\texttt{\mdseries\slshape maxlng}} which intersect non\texttt{\symbol{45}}trivially with the set{\nobreakspace}\mbox{\texttt{\mdseries\slshape S}} and which, in terms of euclidean norm, do not exceed \mbox{\texttt{\mdseries\slshape maxn}}. In the third form a list of all cycles of the rcwa permutation \mbox{\texttt{\mdseries\slshape g}} of length at most{\nobreakspace}\mbox{\texttt{\mdseries\slshape maxlng}} which intersect non\texttt{\symbol{45}}trivially with the set{\nobreakspace}\mbox{\texttt{\mdseries\slshape S}}. In the fourth form a list of all cycles of the rcwa permutation \mbox{\texttt{\mdseries\slshape g}} of length at most{\nobreakspace}\mbox{\texttt{\mdseries\slshape maxlng}} which intersect non\texttt{\symbol{45}}trivially with the set{\nobreakspace}\mbox{\texttt{\mdseries\slshape S}} and which, in terms of euclidean norm, do not exceed \mbox{\texttt{\mdseries\slshape maxn}}. In the fifth form a list of all cycles of the rcwa permutation \mbox{\texttt{\mdseries\slshape g}} of length at most \mbox{\texttt{\mdseries\slshape maxlng}} which do not correspond to cycles consisting of residue classes. 



 The operation \texttt{ShortOrbits} recognizes an option \mbox{\texttt{\mdseries\slshape finite}}. If this option is set, it is assumed that all orbits are finite, in order to
speed up the computation. If furthermore \mbox{\texttt{\mdseries\slshape maxlng}} is negative, a list of \emph{all} orbits which intersect non\texttt{\symbol{45}}trivially with{\nobreakspace}\mbox{\texttt{\mdseries\slshape S}} is returned. 

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

 
\subsection{\textcolor{Chapter }{ ShortResidueClassOrbits \& ShortResidueClassCycles }}\logpage{[ 3, 3, 5 ]}
\hyperdef{L}{X80D18D0778A96C16}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ShortResidueClassOrbits({\mdseries\slshape G, modulusbound, maxlng})\index{ShortResidueClassOrbits@\texttt{ShortResidueClassOrbits}!for rcwa group and bounds on modulus and length}
\label{ShortResidueClassOrbits:for rcwa group and bounds on modulus and length}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ShortResidueClassCycles({\mdseries\slshape g, modulusbound, maxlng})\index{ShortResidueClassCycles@\texttt{ShortResidueClassCycles}!for rcwa permutation and bounds on modulus and length}
\label{ShortResidueClassCycles:for rcwa permutation and bounds on modulus and length}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ResidueClassCyclesThroughResidueClass({\mdseries\slshape g, cl, modulusbound})\index{ResidueClassCyclesThroughResidueClass@\texttt{Residue}\-\texttt{Class}\-\texttt{Cycles}\-\texttt{Through}\-\texttt{Residue}\-\texttt{Class}!for rcwa permutation, residue class and bound on modulus}
\label{ResidueClassCyclesThroughResidueClass:for rcwa permutation, residue class and bound on modulus}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 in the first form a list of all orbits of residue classes under the action of
the rcwa group \mbox{\texttt{\mdseries\slshape G}} which contain a residue class $r(m)$ such that $m$ divides \mbox{\texttt{\mdseries\slshape modulusbound}} and which are not longer than \mbox{\texttt{\mdseries\slshape maxlng}}. In the second form a list of all cycles of residue classes of the rcwa
permutation{\nobreakspace}\mbox{\texttt{\mdseries\slshape g}} which contain a residue class $r(m)$ such that $m$ divides \mbox{\texttt{\mdseries\slshape modulusbound}} and which are not longer than \mbox{\texttt{\mdseries\slshape maxlng}}. In the third form a list of all cycles of residue classes of the rcwa
permutation{\nobreakspace}\mbox{\texttt{\mdseries\slshape g}} which contain a residue class $r(m)$ which is a subset of the residue class \mbox{\texttt{\mdseries\slshape cl}} on which \mbox{\texttt{\mdseries\slshape g}} is affine and whose modulus $m$ divides \mbox{\texttt{\mdseries\slshape modulusbound}}. 



 We are only talking about a \emph{cycle} of residue classes of an rcwa permutation $g$ if the restrictions of $g$ to all contained residue classes are affine. Similarly we are only talking
about an \emph{orbit} of residue classes under the action of an rcwa group $G$ if the restrictions of all elements of $G$ to all residue classes in the orbit are affine. 

 The returned lists may contain additional cycles, resp., orbits, which do not
contain a residue class $r(m)$ such that $m$ divides \mbox{\texttt{\mdseries\slshape modulusbound}}, but which happen to be found without additional efforts. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@g := ClassTransposition(0,2,1,2)*ClassTransposition(0,4,1,6);|
  <rcwa permutation of Z with modulus 12>
  !gapprompt@gap>| !gapinput@ShortResidueClassCycles(g,Mod(g)^2,20);|
  [ [ 2(12), 3(12) ], [ 10(12), 11(12) ], [ 4(24), 5(24), 7(36), 6(36) ], 
    [ 20(24), 21(24), 31(36), 30(36) ], 
    [ 8(48), 9(48), 13(72), 19(108), 18(108), 12(72) ], 
    [ 40(48), 41(48), 61(72), 91(108), 90(108), 60(72) ], 
    [ 16(96), 17(96), 25(144), 37(216), 55(324), 54(324), 36(216), 24(144) 
       ], 
    [ 80(96), 81(96), 121(144), 181(216), 271(324), 270(324), 180(216), 
        120(144) ] ]
  !gapprompt@gap>| !gapinput@ResidueClassCyclesThroughResidueClass(g,ResidueClass(1,4),2^2*12);|
  [ [ 5(24), 7(36), 6(36), 4(24) ], [ 21(24), 31(36), 30(36), 20(24) ], 
    [ 9(48), 13(72), 19(108), 18(108), 12(72), 8(48) ], 
    [ 41(48), 61(72), 91(108), 90(108), 60(72), 40(48) ] ]
  !gapprompt@gap>| !gapinput@Collected(List(ResidueClassCyclesThroughResidueClass(g,|
  !gapprompt@>| !gapinput@                  ResidueClass(1,4),2^6*12),Length));|
  [ [ 4, 2 ], [ 6, 4 ], [ 8, 6 ], [ 10, 8 ], [ 12, 4 ], [ 14, 2 ] ]
  !gapprompt@gap>| !gapinput@List(ResidueClassCyclesThroughResidueClass(g,|
  !gapprompt@>| !gapinput@        ResidueClass(1,4),2^4*12),cyc->cyc[1]);|
  [ 5(24), 21(24), 9(48), 41(48), 13(72), 61(72), 17(96), 81(96), 25(144), 
    121(144), 33(192), 161(192) ]
  !gapprompt@gap>| !gapinput@Display(Difference(ResidueClass(1,4),Union(last)));|
  1(36) U 49(144) U 97(144) U 65(192) U 129(192)
  !gapprompt@gap>| !gapinput@G := Group(List([[0,6,5,6],[1,4,4,6],[2,4,3,6]],ClassTransposition));|
  <(0(6),5(6)),(1(4),4(6)),(2(4),3(6))>
  !gapprompt@gap>| !gapinput@ShortResidueClassOrbits(G,48,10);|
  [ [ 7(12) ], [ 8(12) ], [ 1(24), 4(36) ], [ 2(24), 3(36) ], 
    [ 12(24), 17(24), 28(36) ], [ 18(24), 23(24), 27(36) ], 
    [ 37(48), 58(72), 87(108) ], [ 38(48), 57(72), 88(108) ], 
    [ 0(48), 5(48), 10(72), 15(108) ], [ 6(48), 11(48), 9(72), 16(108) ] ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ComputeCycleLength (for an rcwa permutation and a point)}}
\logpage{[ 3, 3, 6 ]}\nobreak
\hyperdef{L}{X80C080287A355EFF}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ComputeCycleLength({\mdseries\slshape g, n})\index{ComputeCycleLength@\texttt{ComputeCycleLength}!for an rcwa permutation and a point}
\label{ComputeCycleLength:for an rcwa permutation and a point}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record containing the length, the largest point and the position of the
largest point of the cycle of the rcwa permutation \mbox{\texttt{\mdseries\slshape g}} which contains the point \mbox{\texttt{\mdseries\slshape n}}, provided that this cycle is finite. 



 If the cycle is infinite, the function will run into an infinite loop unless
the option \texttt{"abortat"} is set to the maximum number of iterates to be tried before aborting. Iterates
are not stored, to save memory. The function interprets an option \texttt{"notify"}, which defaults to 10000; every ``notify'' iterations, the number of binary digits of the latest iterate is printed. This
output can be suppressed by the option \texttt{quiet}. The function also interprets an option \texttt{"small"}, which may be set to a range within which small points are recorded and
returned in a component \texttt{smallpoints}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@g := Product(List([[0,5,3,5],[1,2,0,6],[2,4,3,6]],|
  !gapprompt@>| !gapinput@                     ClassTransposition));|
  <rcwa permutation of Z with modulus 180>
  !gapprompt@gap>| !gapinput@ComputeCycleLength(g,20:small:=[0..1000]);|
  n = 20: after 10000 steps, the iterate has 1919 binary digits.
  n = 20: after 20000 steps, the iterate has 2908 binary digits.
  n = 20: after 30000 steps, the iterate has 1531 binary digits.
  n = 20: after 40000 steps, the iterate has 708 binary digits.
  rec( aborted := false, g := <rcwa permutation of Z with modulus 180>, 
    length := 45961, 
    maximum := 180479928411509527091314790144929480041473309862957394384783java.lang.NullPointerException
  0525935437431021442346166422201250935268553945158085769924448388724679753java.lang.NullPointerException
  5271669245363980744610119632280105994423399614803956244808653465492205657java.lang.NullPointerException
  8650363041608376587943180444494842094693691286183613056599672737336761093java.lang.NullPointerException
  3101035841077322874883200384115281051837032147150147712534199292886436789java.lang.NullPointerException
  7520389780289517825203780151058517520194926468391308525704499649905091899java.lang.NullPointerException
  9667529835495635671154681958992898010506577172313321500572646883756736685java.lang.NullPointerException
  0158653917532084531267455434808219032998691038943070902228427549279555530java.lang.NullPointerException
  6429870190316109419051531138721361826083376315737131067799731181096142797java.lang.NullPointerException
  4868525347003646887454985757711743327946232372385342293662007684758208408java.lang.NullPointerException
  8635715976464060647431260835037213863991037813998261883899050447111540742java.lang.NullPointerException
  5857187943077255493709629738212709349458790098815926920248565399938335540java.lang.NullPointerException
  8092502449690267365120996852, maxpos := 19825, n := 20, 
    smallpoints := [ 20, 23, 66, 99, 294, 295, 298, 441, 447, 882, 890, 
        893 ] )
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{CycleRepresentativesAndLengths (for rcwa permutation and set of seed points)}}
\logpage{[ 3, 3, 7 ]}\nobreak
\hyperdef{L}{X7F76B04E86C77B94}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CycleRepresentativesAndLengths({\mdseries\slshape g, S})\index{CycleRepresentativesAndLengths@\texttt{CycleRepresentativesAndLengths}!for rcwa permutation and set of seed points}
\label{CycleRepresentativesAndLengths:for rcwa permutation and set of seed points}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 a list of pairs (cycle representative, length of cycle) for all cycles of the
rcwa permutation \mbox{\texttt{\mdseries\slshape g}} which have a nontrivial intersection with the set \mbox{\texttt{\mdseries\slshape S}}, where fixed points are omitted. 



 The rcwa permutation \mbox{\texttt{\mdseries\slshape g}} is assumed to have only finite cycles. If \mbox{\texttt{\mdseries\slshape g}} has an infinite cycle which intersects non\texttt{\symbol{45}}trivially with \mbox{\texttt{\mdseries\slshape S}}, this may cause an infinite loop unless a cycle length limit is set via the
option \texttt{abortat}. The output can be suppressed by the option \texttt{quiet}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@g := ClassTransposition(0,2,1,2)*ClassTransposition(0,4,1,6);;|
  !gapprompt@gap>| !gapinput@CycleRepresentativesAndLengths(g,[0..50]);|
  [ [ 2, 2 ], [ 4, 4 ], [ 8, 6 ], [ 10, 2 ], [ 14, 2 ], [ 16, 8 ], 
    [ 20, 4 ], [ 22, 2 ], [ 26, 2 ], [ 28, 4 ], [ 32, 10 ], [ 34, 2 ], 
    [ 38, 2 ], [ 40, 6 ], [ 44, 4 ], [ 46, 2 ], [ 50, 2 ] ]
  !gapprompt@gap>| !gapinput@g := Product(List([[0,5,3,5],[1,2,0,6],[2,4,3,6]],|
  !gapprompt@>| !gapinput@                     ClassTransposition));|
  <rcwa permutation of Z with modulus 180>
  !gapprompt@gap>| !gapinput@CycleRepresentativesAndLengths(g,[0..100]:abortat:=100000);|
  n = 20: after 10000 steps, the iterate has 1919 binary digits.
  n = 20: after 20000 steps, the iterate has 2908 binary digits.
  n = 20: after 30000 steps, the iterate has 1531 binary digits.
  n = 20: after 40000 steps, the iterate has 708 binary digits.
  n = 79: after 10000 steps, the iterate has 1679 binary digits.
  n = 100: after 10000 steps, the iterate has 712 binary digits.
  n = 100: after 20000 steps, the iterate has 2507 binary digits.
  n = 100: after 30000 steps, the iterate has 3311 binary digits.
  n = 100: after 40000 steps, the iterate has 3168 binary digits.
  n = 100: after 50000 steps, the iterate has 3947 binary digits.
  n = 100: after 60000 steps, the iterate has 4793 binary digits.
  n = 100: after 70000 steps, the iterate has 5325 binary digits.
  n = 100: after 80000 steps, the iterate has 6408 binary digits.
  n = 100: after 90000 steps, the iterate has 7265 binary digits.
  n = 100: after 100000 steps, the iterate has 7918 binary digits.
  [ [ 0, 7 ], [ 5, 3 ], [ 7, 7159 ], [ 11, 9 ], [ 19, 342 ],
    [ 20, 45961 ], [ 25, 3 ], [ 26, 21 ], [ 29, 2 ], [ 31, 3941 ],
    [ 34, 19 ], [ 37, 7 ], [ 40, 5 ], [ 41, 7 ], [ 46, 3 ], [ 49, 2 ],
    [ 59, 564 ], [ 61, 577 ], [ 65, 3 ], [ 67, 23 ], [ 71, 41 ],
    [ 79, 16984 ], [ 80, 5 ], [ 85, 3 ], [ 86, 3 ], [ 89, 2 ], [ 91, 9 ],
    [ 94, 1355 ], [ 97, 7 ], [ 100, fail ] ]
  
\end{Verbatim}
 }

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

\subsection{\textcolor{Chapter }{FixedResidueClasses (for rcwa mapping and bound on modulus)}}
\logpage{[ 3, 3, 8 ]}\nobreak
\hyperdef{L}{X8777A62286597D53}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FixedResidueClasses({\mdseries\slshape g, maxmod})\index{FixedResidueClasses@\texttt{FixedResidueClasses}!for rcwa mapping and bound on modulus}
\label{FixedResidueClasses:for rcwa mapping and bound on modulus}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FixedResidueClasses({\mdseries\slshape G, maxmod})\index{FixedResidueClasses@\texttt{FixedResidueClasses}!for rcwa group and bound on modulus}
\label{FixedResidueClasses:for rcwa group and bound on modulus}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 the set of residue classes with modulus greater than 1 and less than or equal
to \mbox{\texttt{\mdseries\slshape maxmod}} which the rcwa mapping \mbox{\texttt{\mdseries\slshape g}}, respectively the rcwa group \mbox{\texttt{\mdseries\slshape G}}, fixes setwise. 



 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@FixedResidueClasses(ClassTransposition(0,2,1,4),8);|
  [ 2(3), 3(4), 4(5), 6(7), 3(8), 7(8) ]
  !gapprompt@gap>| !gapinput@FixedResidueClasses(Group(ClassTransposition(0,2,1,4),|
  !gapprompt@>| !gapinput@                             ClassTransposition(0,3,1,3)),12);|
  [ 2(3), 8(9), 11(12) ]
  
\end{Verbatim}
 }

 Frequently one needs to compute balls of certain radius around points or group
elements, be it to estimate the growth of a group, be it to see how an orbit
looks like, be it to search for a group element with certain properties or be
it for other purposes: 
\subsection{\textcolor{Chapter }{ Ball (for group, element and radius or group, point, radius and action) }}\logpage{[ 3, 3, 9 ]}
\hyperdef{L}{X8735855587CC029F}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Ball({\mdseries\slshape G, g, r})\index{Ball@\texttt{Ball}!for group, element and radius}
\label{Ball:for group, element and radius}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Ball({\mdseries\slshape G, p, r, action})\index{Ball@\texttt{Ball}!for group, point, radius and action}
\label{Ball:for group, point, radius and action}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Ball({\mdseries\slshape G, p, r})\index{Ball@\texttt{Ball}!for group, point and radius}
\label{Ball:for group, point and radius}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 the ball of radius{\nobreakspace}\mbox{\texttt{\mdseries\slshape r}} around the element{\nobreakspace}\mbox{\texttt{\mdseries\slshape g}} in the group{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}}, respectively the ball of radius{\nobreakspace}\mbox{\texttt{\mdseries\slshape r}} around the point{\nobreakspace}\mbox{\texttt{\mdseries\slshape p}} under the action{\nobreakspace}\mbox{\texttt{\mdseries\slshape action}} of the group{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}}, respectively the ball of radius{\nobreakspace}\mbox{\texttt{\mdseries\slshape r}} around the point{\nobreakspace}\mbox{\texttt{\mdseries\slshape p}} under the action{\nobreakspace}\texttt{OnPoints} of the group{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}}, 



 All balls are understood with respect to \texttt{GeneratorsOfGroup(\mbox{\texttt{\mdseries\slshape G}})}. As membership tests can be expensive, the former method does not check
whether \mbox{\texttt{\mdseries\slshape g}} is indeed an element of{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}}. The methods require that element\texttt{\symbol{45}} / point comparisons are
cheap. They are not only applicable to rcwa groups. If the option \mbox{\texttt{\mdseries\slshape Spheres}} is set, the ball is split up and returned as a list of spheres. There is a
related operation \texttt{RestrictedBall(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape g}},\mbox{\texttt{\mdseries\slshape r}},\mbox{\texttt{\mdseries\slshape modulusbound}})} specifically for rcwa groups which computes only those elements of the ball
whose moduli do not exceed \mbox{\texttt{\mdseries\slshape modulusbound}}, and which can be reached from \mbox{\texttt{\mdseries\slshape g}} without computing intermediate elements whose moduli do exceed \mbox{\texttt{\mdseries\slshape modulusbound}}. The latter operation interprets an option \texttt{"boundaffineparts"}. \texttt{\symbol{45}}\texttt{\symbol{45}} If this option is set and the group \mbox{\texttt{\mdseries\slshape G}} and the element \mbox{\texttt{\mdseries\slshape g}} are in sparse representation, then \mbox{\texttt{\mdseries\slshape modulusbound}} is actually taken to be a bound on the number of affine parts rather than a
bound on the modulus. \index{RestrictedBall@\texttt{RestrictedBall}!G, g, r, modulusbound} 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@PSL2Z := Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(2),|
  !gapprompt@>| !gapinput@                                                   CyclicGroup(3))));;|
  !gapprompt@gap>| !gapinput@List([1..10],k->Length(Ball(PSL2Z,[0,1],k,OnTuples)));|
  [ 4, 8, 14, 22, 34, 50, 74, 106, 154, 218 ]
  !gapprompt@gap>| !gapinput@Ball(Group((1,2),(2,3),(3,4)),(),2:Spheres);|
  [ [ () ], [ (3,4), (2,3), (1,2) ],
    [ (2,3,4), (2,4,3), (1,2)(3,4), (1,2,3), (1,3,2) ] ]
  !gapprompt@gap>| !gapinput@G := Group(List([[1,2,4,6],[1,3,2,6],[2,3,4,6]],ClassTransposition));;|
  !gapprompt@gap>| !gapinput@B := RestrictedBall(G,One(G),20,36:Spheres);; # try replacing 36 by 72|
  !gapprompt@gap>| !gapinput@List(B,Length);|
  [ 1, 3, 6, 12, 4, 6, 6, 4, 4, 4, 6, 6, 3, 3, 2, 0, 0, 0, 0, 0, 0 ]
  
\end{Verbatim}
 }

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

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



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

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

 The algorithm is based on computing balls of increasing radius around \mbox{\texttt{\mdseries\slshape source}} and \mbox{\texttt{\mdseries\slshape destination}} until they intersect non\texttt{\symbol{45}}trivially. 
\begin{Verbatim}[commandchars=!@H,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>H !gapinput@a := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);; SetName(a,"a");H
  !gapprompt@gap>H !gapinput@b := ClassShift(1,4:Name:="b");; G := Group(a,b);;H
  !gapprompt@gap>H !gapinput@elm := RepresentativeAction(G,[7,4,9],[4,5,13],OnTuples);;H
  !gapprompt@gap>H !gapinput@Display(elm);H
  
  Rcwa permutation of Z with modulus 12
  
          /
          | n-3 if n in 1(6) U 10(12)
          | n+4 if n in 5(12) U 9(12)
   n |-> <  n+1 if n in 4(12)
          | n   if n in 0(6) U 2(6) U 3(12) U 11(12)
          |
          java.lang.NullPointerException
  
  !gapprompt@gap>H !gapinput@List([7,4,9],n->n^elm);H
  [ 4, 5, 13 ]
  !gapprompt@gap>H !gapinput@elm := RepresentativeAction(G,[6,-3,8],[-9,4,11],OnPoints);;H
  !gapprompt@gap>H !gapinput@Display(elm);H
  
  Rcwa permutation of Z with modulus 12
  
          /
          | 2n/3      if n in 0(6) U 3(12)
          | (4n+1)/3  if n in 2(6) U 11(12)
          | (4n-1)/3  if n in 4(6) U 7(12)
   n |-> <  (2n-8)/3  if n in 1(12)
          | (4n-17)/3 if n in 5(12)
          | (4n-15)/3 if n in 9(12)
          |
          java.lang.NullPointerException
  
  !gapprompt@gap>H !gapinput@[6,-3,8]^elm; List([6,-3,8],n->n^elm); # `OnPoints' allows reorderingH
  [ -9, 4, 11 ]
  [ 4, -9, 11 ]
  !gapprompt@gap>H !gapinput@F := FreeGroup("a","b");; phi := EpimorphismByGenerators(F,G);;H
  !gapprompt@gap>H !gapinput@w := RepresentativeActionPreImage(G,[10,-4,9,5],[4,5,13,-8],H
  !gapprompt@>H !gapinput@                                     OnTuples,F);H
  a*b^-1*a^-1*(b^-1*a)^2*b*a*b^-2*a*b*a^-1*b
  !gapprompt@gap>H !gapinput@elm := w^phi;H
  <rcwa permutation of Z with modulus 324>
  !gapprompt@gap>H !gapinput@List([10,-4,9,5],n->n^elm);H
  [ 4, 5, 13, -8 ]
  
\end{Verbatim}
 }

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

\subsection{\textcolor{Chapter }{ProjectionsToInvariantUnionsOfResidueClasses (for rcwa group and modulus)}}
\logpage{[ 3, 3, 11 ]}\nobreak
\hyperdef{L}{X8587246A7F890849}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ProjectionsToInvariantUnionsOfResidueClasses({\mdseries\slshape G, m})\index{ProjectionsToInvariantUnionsOfResidueClasses@\texttt{Projections}\-\texttt{To}\-\texttt{Invariant}\-\texttt{Unions}\-\texttt{Of}\-\texttt{Residue}\-\texttt{Classes}!for rcwa group and modulus}
\label{ProjectionsToInvariantUnionsOfResidueClasses:for rcwa group and modulus}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 the projections of the rcwa group{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} to the unions of residue classes (mod{\nobreakspace}\mbox{\texttt{\mdseries\slshape m}}) which it fixes setwise. 



 The corresponding partition of a set of representatives for the residue
classes (mod{\nobreakspace}\mbox{\texttt{\mdseries\slshape m}}) can be obtained by the operation \texttt{OrbitsModulo(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape m}})}. \index{OrbitsModulo@\texttt{OrbitsModulo}!for an rcwa group and a modulus} 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(ClassTransposition(0,2,1,2),ClassShift(3,4));;|
  !gapprompt@gap>| !gapinput@ProjectionsToInvariantUnionsOfResidueClasses(G,4);|
  [ [ ( 0(2), 1(2) ), ClassShift( 3(4) ) ] -> 
      [ ( 0(4), 1(4) ), IdentityMapping( Integers ) ], 
    [ ( 0(2), 1(2) ), ClassShift( 3(4) ) ] -> 
      [ ( 2(4), 3(4) ), <rcwa permutation of Z with modulus 4> ] ]
  !gapprompt@gap>| !gapinput@List(last,phi->Support(Image(phi)));|
  [ 0(4) U 1(4), 2(4) U 3(4) ]
  
\end{Verbatim}
 }

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

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



 The arguments \mbox{\texttt{\mdseries\slshape P1}} and \mbox{\texttt{\mdseries\slshape P2}} must be partitions of the underlying ring $R$ into the same number of unions of residue classes. The method for $R = {\ensuremath{\mathbb Z}}$ recognizes the option \texttt{IsTame}, which can be used to demand a tame result. If this option is set and there
is no tame rcwa permutation which maps \mbox{\texttt{\mdseries\slshape P1}} to{\nobreakspace}\mbox{\texttt{\mdseries\slshape P2}}, the method runs into an infinite loop. This happens if the condition in
Theorem{\nobreakspace}2.8.9 in{\nobreakspace}\cite{Kohl05} is not satisfied. If the option \texttt{IsTame} is not set and the partitions \mbox{\texttt{\mdseries\slshape P1}} and \mbox{\texttt{\mdseries\slshape P2}} both consist entirely of single residue classes, then the returned mapping is
affine on any residue class in{\nobreakspace}\mbox{\texttt{\mdseries\slshape P1}}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@P1 := AllResidueClassesModulo(3);|
  [ 0(3), 1(3), 2(3) ]
  !gapprompt@gap>| !gapinput@P2 := List([[0,2],[1,4],[3,4]],ResidueClass);|
  [ 0(2), 1(4), 3(4) ]
  !gapprompt@gap>| !gapinput@elm := RepresentativeAction(RCWA(Integers),P1,P2);|
  <rcwa permutation of Z with modulus 3>
  !gapprompt@gap>| !gapinput@P1^elm = P2;|
  true
  !gapprompt@gap>| !gapinput@IsTame(elm);|
  false
  !gapprompt@gap>| !gapinput@elm := RepresentativeAction(RCWA(Integers),P1,P2:IsTame);|
  <tame rcwa permutation of Z with modulus 24>
  !gapprompt@gap>| !gapinput@P1^elm = P2;|
  true
  !gapprompt@gap>| !gapinput@elm := RepresentativeAction(RCWA(Integers),|
  !gapprompt@>| !gapinput@            [ResidueClass(1,3),|
  !gapprompt@>| !gapinput@             ResidueClassUnion(Integers,3,[0,2])],|
  !gapprompt@>| !gapinput@            [ResidueClassUnion(Integers,5,[2,4]),|
  !gapprompt@>| !gapinput@             ResidueClassUnion(Integers,5,[0,1,3])]);|
  <rcwa permutation of Z with modulus 6>
  !gapprompt@gap>| !gapinput@[ResidueClass(1,3),ResidueClassUnion(Integers,3,[0,2])]^elm;|
  [ 2(5) U 4(5), Z \ 2(5) U 4(5) ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{CollatzLikeMappingByOrbitTree (for rcwa group, root point and range of radii)}}
\logpage{[ 3, 3, 13 ]}\nobreak
\hyperdef{L}{X82DBAF35788FA239}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CollatzLikeMappingByOrbitTree({\mdseries\slshape G, n, min{\textunderscore}r, max{\textunderscore}r})\index{CollatzLikeMappingByOrbitTree@\texttt{CollatzLikeMappingByOrbitTree}!for rcwa group, root point and range of radii}
\label{CollatzLikeMappingByOrbitTree:for rcwa group, root point and range of radii}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 either an rcwa mapping $f$ which maps the sphere of radius $r$ about \mbox{\texttt{\mdseries\slshape n}} under the action of \mbox{\texttt{\mdseries\slshape G}} into the sphere of radius $r-1$ about \mbox{\texttt{\mdseries\slshape n}} for every $r$ ranging from \mbox{\texttt{\mdseries\slshape min{\textunderscore}r}} to \mbox{\texttt{\mdseries\slshape max{\textunderscore}r}}, or \texttt{fail}. 



 Obviously not for every rcwa group and every root point a mapping $f$ with these properties exists, and if it exists, it usually depends on the
choice of generators of the group. 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@G := Group(ClassTransposition(0,2,1,2),ClassTransposition(1,2,2,4),A
  !gapprompt@>A !gapinput@              ClassTransposition(1,4,2,6));;A
  !gapprompt@gap>A !gapinput@G := SparseRep(G);;A
  !gapprompt@gap>A !gapinput@f := CollatzLikeMappingByOrbitTree(G,0,4,10);A
  <rcwa mapping of Z with modulus 4 and 4 affine parts>
  !gapprompt@gap>A !gapinput@Display(f);A
  
  Rcwa mapping of Z with modulus 4 and 4 affine parts
  
          /
          | n+1      if n in 0(4)
          | (3n+1)/2 if n in 1(4)
   n |-> <  n/2      if n in 2(4)
          | n-1      if n in 3(4)
          |
          java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@B := Ball(G,0,15:Spheres);A
  [ [ 0 ], [ 1 ], [ 2 ], [ 3 ], [ 6 ], [ 7 ], [ 14 ], [ 9, 15 ], [ 8, 18, 30 ], 
    [ 5, 19, 31 ], [ 4, 10, 38, 62 ], [ 11, 25, 39, 41, 63 ], 
    [ 22, 24, 40, 50, 78, 82, 126 ], [ 23, 33, 51, 79, 83, 127 ], 
    [ 32, 46, 66, 102, 158, 166, 254 ], 
    [ 21, 47, 67, 103, 105, 159, 167, 169, 255 ] ]
  !gapprompt@gap>A !gapinput@List([3..15],i->IsSubset(B[i-1],B[i]^f));A
  [ true, true, true, true, true, true, true, true, true, true, true, true,
    true ]
  !gapprompt@gap>A !gapinput@Trajectory(f,52,[0,1]);A
  [ 52, 53, 80, 81, 122, 61, 92, 93, 140, 141, 212, 213, 320, 321, 482, 241, 
    362, 181, 272, 273, 410, 205, 308, 309, 464, 465, 698, 349, 524, 525, 788, 
    789, 1184, 1185, 1778, 889, 1334, 667, 666, 333, 500, 501, 752, 753, 1130, 
    565, 848, 849, 1274, 637, 956, 957, 1436, 1437, 2156, 2157, 3236, 3237, 
    4856, 4857, 7286, 3643, 3642, 1821, 2732, 2733, 4100, 4101, 6152, 6153, 
    9230, 4615, 4614, 2307, 2306, 1153, 1730, 865, 1298, 649, 974, 487, 486, 
    243, 242, 121, 182, 91, 90, 45, 68, 69, 104, 105, 158, 79, 78, 39, 38, 19, 
    18, 9, 14, 7, 6, 3, 2, 1 ]
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{ Special attributes of tame
residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine groups }}\label{sec:MethodsForTameGroups}
\logpage{[ 3, 4, 0 ]}
\hyperdef{L}{X781CBEFA7F39B58D}{}
{
  There are a couple of attributes which a priori make only sense for tame rcwa
groups. With their help, various structural information about a given such
group can be obtained. We have already seen above that there are for example
methods for \texttt{IsSolvableGroup}, \texttt{IsPerfectGroup} and \texttt{DerivedSubgroup} available for tame rcwa groups, while testing wild groups for solvability or
perfectness is currently not always feasible. The purpose of this section is
to describe the specific attributes of tame groups which are needed for these
computations. 
\subsection{\textcolor{Chapter }{ RespectedPartition (of a tame rcwa group or \texttt{\symbol{45}}permutation) }}\logpage{[ 3, 4, 1 ]}
\hyperdef{L}{X7F523A6B87825AB8}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RespectedPartition({\mdseries\slshape G})\index{RespectedPartition@\texttt{RespectedPartition}!of a tame rcwa group}
\label{RespectedPartition:of a tame rcwa group}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RespectedPartition({\mdseries\slshape g})\index{RespectedPartition@\texttt{RespectedPartition}!of a tame rcwa permutation}
\label{RespectedPartition:of a tame rcwa permutation}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 a shortest and coarsest possible respected partition of the rcwa group \mbox{\texttt{\mdseries\slshape G}} / of the rcwa permutation{\nobreakspace}\mbox{\texttt{\mdseries\slshape g}}. 



 A tame element $g${\nobreakspace}$\in${\nobreakspace}RCWA($R$) permutes a partition of{\nobreakspace}$R$ into finitely many residue classes on all of which it is affine. Given a tame
group $G${\nobreakspace}$<${\nobreakspace}RCWA($R$), there is a common such partition for all elements of{\nobreakspace}$G$. We call the mentioned partitions \emph{respected partitions} of{\nobreakspace}$g$ or{\nobreakspace}$G$, respectively. 

 An rcwa group or an rcwa permutation has a respected partition if and only if
it is tame. This holds either by definition or by Theorem{\nobreakspace}2.5.8
in{\nobreakspace}\cite{Kohl05}, depending on how one introduces the notion of tameness. 

 \index{RespectsPartition@\texttt{RespectsPartition}!for an rcwa group} \index{RespectsPartition@\texttt{RespectsPartition}!for an rcwa permutation} There is an operation \texttt{RespectsPartition(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape P}})} / \texttt{RespectsPartition(\mbox{\texttt{\mdseries\slshape g}},\mbox{\texttt{\mdseries\slshape P}})}, which tests whether \mbox{\texttt{\mdseries\slshape G}} or{\nobreakspace}\mbox{\texttt{\mdseries\slshape g}} respects a given partition{\nobreakspace}\mbox{\texttt{\mdseries\slshape P}}. The permutation induced by \mbox{\texttt{\mdseries\slshape g}} on{\nobreakspace}\texttt{P} can be computed efficiently by \texttt{PermutationOpNC(\mbox{\texttt{\mdseries\slshape g}},P,OnPoints)}. \index{PermutationOpNC@\texttt{PermutationOpNC}!g, P, OnPoints} 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(ClassTransposition(0,4,1,6),ClassShift(0,2));|
  <rcwa group over Z with 2 generators>
  !gapprompt@gap>| !gapinput@IsTame(G);|
  true
  !gapprompt@gap>| !gapinput@Size(G);|
  infinity
  !gapprompt@gap>| !gapinput@P := RespectedPartition(G);|
  [ 0(4), 2(4), 1(6), 3(6), 5(6) ]
  
\end{Verbatim}
 }

 
\subsection{\textcolor{Chapter }{ ActionOnRespectedPartition \& KernelOfActionOnRespectedPartition }}\logpage{[ 3, 4, 2 ]}
\hyperdef{L}{X831ADC1584DE6113}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ActionOnRespectedPartition({\mdseries\slshape G})\index{ActionOnRespectedPartition@\texttt{ActionOnRespectedPartition}!for a tame rcwa group}
\label{ActionOnRespectedPartition:for a tame rcwa group}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{KernelOfActionOnRespectedPartition({\mdseries\slshape G})\index{KernelOfActionOnRespectedPartition@\texttt{KernelOfActionOnRespectedPartition}!for a tame rcwa group}
\label{KernelOfActionOnRespectedPartition:for a tame rcwa group}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RankOfKernelOfActionOnRespectedPartition({\mdseries\slshape G})\index{RankOfKernelOfActionOnRespectedPartition@\texttt{Rank}\-\texttt{Of}\-\texttt{Kernel}\-\texttt{Of}\-\texttt{Action}\-\texttt{On}\-\texttt{Respected}\-\texttt{Partition}!for a tame rcwa group}
\label{RankOfKernelOfActionOnRespectedPartition:for a tame rcwa group}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 the action of the tame rcwa group{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} on \texttt{RespectedPartition(\mbox{\texttt{\mdseries\slshape G}})}, the kernel of this action or the rank of the latter, respectively. 



 The method for \texttt{KernelOfActionOnRespectedPartition} uses the package \textsf{Polycyclic}{\nobreakspace}\cite{Polycyclic}. The rank of the largest free abelian subgroup of the kernel of the action
of{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} on its stored respected partition is \texttt{RankOfKernelOfActionOnRespectedPartition(\mbox{\texttt{\mdseries\slshape G}})}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(ClassTransposition(0,4,1,6),ClassShift(0,2));;|
  !gapprompt@gap>| !gapinput@H := ActionOnRespectedPartition(G);|
  Group([ (1,3), (1,2) ])
  !gapprompt@gap>| !gapinput@H = Action(G,P);|
  true
  !gapprompt@gap>| !gapinput@Size(H);|
  6
  !gapprompt@gap>| !gapinput@K := KernelOfActionOnRespectedPartition(G);|
  <rcwa group over Z with 3 generators>
  !gapprompt@gap>| !gapinput@RankOfKernelOfActionOnRespectedPartition(G);|
  3
  !gapprompt@gap>| !gapinput@Index(G,K);|
  6
  !gapprompt@gap>| !gapinput@List(GeneratorsOfGroup(K),Factorization);|
  [ [ ClassShift( 0(4) ) ], [ ClassShift( 2(4) ) ], [ ClassShift( 1(6) ) ] ]
  !gapprompt@gap>| !gapinput@Image(IsomorphismPcpGroup(K));|
  Pcp-group with orders [ 0, 0, 0 ]
  
\end{Verbatim}
 }

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

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

  
\section{\textcolor{Chapter }{Generating pseudo\texttt{\symbol{45}}random elements of RCWA(R) and CT(R)}}\label{sec:Random}
\logpage{[ 3, 5, 0 ]}
\hyperdef{L}{X81941A247942FB99}{}
{
  \index{Random@\texttt{Random}!RCWA(R)} \index{Random@\texttt{Random}!CT(R)} There are methods for the operation \texttt{Random} for RCWA($R$) and CT($R$). These methods are designed to be suitable for generating interesting
examples. No particular distribution is guaranteed. 
\begin{Verbatim}[commandchars=!@B,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>B !gapinput@elm := Random(RCWA(Integers));;B
  !gapprompt@gap>B !gapinput@Display(elm);B
  
  Rcwa permutation of Z with modulus 180
  
          /
          | 6n+12     if n in 2(10) U 4(10) U 6(10) U 8(10)
          | 3n+3      if n in 1(20) U 5(20) U 9(20) U 17(20)
          | 6n+10     if n in 0(10)
          | (n+1)/2   if n in 15(60) U 27(60) U 39(60) U 51(60)
          | (n+7)/2   if n in 19(60) U 31(60) U 43(60) U 55(60)
          | 3n+1      if n in 13(20)
          | (-n+17)/6 if n in 23(180) U 35(180) U 59(180) U 71(180) U 
   n |-> <                    95(180) U 131(180) U 143(180) U 179(180)
          | (-n-1)/6  if n in 11(180) U 47(180) U 83(180) U 155(180)
          | (-n+7)/2  if n in 3(60)
          | (n+3)/2   if n in 7(60)
          | (n-17)/6  if n in 107(180)
          | (-n+11)/6 if n in 119(180)
          | (-n+29)/6 if n in 167(180)
          |
          java.lang.NullPointerException
  
\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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Factorization(elm);|
  [ ClassTransposition(0,2,3,4), ClassTransposition(1,2,4,6), ClassShift(0,2), 
    ClassShift(1,3), ClassReflection(2,5), ClassReflection(1,3), 
    ClassReflection(1,2) ]
  
\end{Verbatim}
 }

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

\subsection{\textcolor{Chapter }{IsRcwaGroup}}
\logpage{[ 3, 6, 1 ]}\nobreak
\hyperdef{L}{X84AFBB997B694A3D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsRcwaGroup({\mdseries\slshape G})\index{IsRcwaGroup@\texttt{IsRcwaGroup}}
\label{IsRcwaGroup}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsRcwaGroupOverZ({\mdseries\slshape G})\index{IsRcwaGroupOverZ@\texttt{IsRcwaGroupOverZ}}
\label{IsRcwaGroupOverZ}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsRcwaGroupOverZ{\textunderscore}pi({\mdseries\slshape G})\index{IsRcwaGroupOverZ{\textunderscore}pi@\texttt{IsRcwaGroupOverZ{\textunderscore}pi}}
\label{IsRcwaGroupOverZuScorepi}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsRcwaGroupOverGFqx({\mdseries\slshape G})\index{IsRcwaGroupOverGFqx@\texttt{IsRcwaGroupOverGFqx}}
\label{IsRcwaGroupOverGFqx}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} if \mbox{\texttt{\mdseries\slshape G}} is an rcwa group, an rcwa group over the ring of integers, an rcwa group over
a semilocalization of the ring of integers or an rcwa group over a polynomial
ring in one variable over a finite field, respectively, and \texttt{false} otherwise. 



 \index{IsRcwaGroupOverZOrZ_pi@\texttt{IsRcwaGroupOverZOrZ{\textunderscore}pi}} Often the same methods can be used for rcwa groups over the ring of integers
and over its semilocalizations. For this reason there is a category \texttt{IsRcwaGroupOverZOrZ{\textunderscore}pi} which is the union of \texttt{IsRcwaGroupOverZ} and \texttt{IsRcwaGroupOverZ{\textunderscore}pi}. 

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

 }

  }

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

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



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

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

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

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

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

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



 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ShortOrbits(M,[-5..5],20);|
  [ [ -5, -4, 1, 2, 7, 8 ], [ -3, -2, 1, 2, 5, 6 ], [ -1 .. 4 ] ]
  !gapprompt@gap>| !gapinput@Print(Action(M,last[1]),"\n");|
  Monoid( [ Transformation( [ 2, 3, 4, 3, 6, 3 ] ), 
    Transformation( [ 4, 5, 4, 3, 4, 1 ] ) ] )
  !gapprompt@gap>| !gapinput@orbs := ShortOrbits(N,[0..10],100);|
  [ [ -5, -4, -3, -1, 0, 1, 2, 3, 5, 6 ], 
    [ -11, -10, -9, -7, -6, -5, -4, -3, -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 
        11, 12 ], 
    [ -17, -16, -15, -13, -12, -11, -10, -9, -7, -6, -5, -4, -3, -1, 0, 1, 
        2, 3, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 17, 18 ] ]
  !gapprompt@gap>| !gapinput@quots := List(orbs,orb->Action(N,orb));;|
  !gapprompt@gap>| !gapinput@List(quots,Size);|
  [ 268, 332, 366 ]
  
\end{Verbatim}
 }

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



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

  }

  }

       
\chapter{\textcolor{Chapter }{ Residue\texttt{\symbol{45}}Class\texttt{\symbol{45}}Wise Affine Mappings,
Groups and Monoids over ${\ensuremath{\mathbb Z}}^2$ }}\label{ch:ZxZ}
\logpage{[ 5, 0, 0 ]}
\hyperdef{L}{X788EB00B82897762}{}
{
   This chapter describes how to compute with
residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine mappings
of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ and with groups and monoids formed by them. 

 The rings on which we have defined
residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine mappings so
far have all been principal ideal domains, and it has been crucial that all
nontrivial principal ideals had finite index. However, the rings ${\ensuremath{\mathbb Z}}^d$, $d > 1$ are not principal ideal domains. Furthermore, their principal ideals have
infinite index. Therefore as moduli of
residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine mappings we
can only use lattices of full rank, for these are precisely the ideals of ${\ensuremath{\mathbb Z}}^d$ of finite index. However, on the other hand we can also be more permissive and
look at ${\ensuremath{\mathbb Z}}^d$ not as a ring, but rather as a free {\ensuremath{\mathbb
Z}}\texttt{\symbol{45}}module. The consequence of this is that then an affine
mapping of ${\ensuremath{\mathbb Z}}^d$ is not just given by $v \mapsto (av+b)/c$ for some $a, b, c \in {\ensuremath{\mathbb Z}}^d$, but rather by $v \mapsto (vA+b)/c$, where $A \in {\ensuremath{\mathbb Z}}^{d \times d}$. Also for technical reasons concerning the implementation in \textsf{GAP}, looking at ${\ensuremath{\mathbb Z}}^d$ as a free {\ensuremath{\mathbb Z}}\texttt{\symbol{45}}module is preferable
\texttt{\symbol{45}}\texttt{\symbol{45}} in \textsf{GAP}, \texttt{Integers\texttt{\symbol{94}}d} is not a ring, and multiplying lists of integers means forming their scalar
product.  
\section{\textcolor{Chapter }{ The definition of residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise
affine mappings of ${\ensuremath{\mathbb Z}}^d$ }}\label{sec:DefinitionOfRcwaMappingsOfZxZ}
\logpage{[ 5, 1, 0 ]}
\hyperdef{L}{X781907CA785CC7AC}{}
{
  \index{rcwa mapping@rcwa mapping!of Z x Z, definition} Let $d \in {\ensuremath{\mathbb N}}$. We call a mapping $f: {\ensuremath{\mathbb Z}}^d \rightarrow {\ensuremath{\mathbb Z}}^d$ \emph{residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine} if there is a lattice $L = {\ensuremath{\mathbb Z}}^d M$ where $M \in {\ensuremath{\mathbb Z}}^{d \times d}$ is a matrix of full rank, such that the restrictions of $f$ to the residue classes $r + L \in {\ensuremath{\mathbb Z}}^d/L$ are all affine. This means that for any residue class $r + L \in {\ensuremath{\mathbb Z}}^d/L$, there is a matrix $A_{r+L} \in {\ensuremath{\mathbb Z}}^{d \times d}$, a vector $b_{r+L} \in {\ensuremath{\mathbb Z}}^d$ and a positive integer $c_{r+L}$ such that the restriction of{\nobreakspace}$f$ to $r + L$ is given by $f|_{r + L}: \ r + L \ \rightarrow \ {\ensuremath{\mathbb Z}}^d, \ \ v java.lang.NullPointerException
\mapsto \ (v \cdot A_{r+L} + b_{r+L})/c_{r+L}$. For reasons of uniqueness, we assume that $L$ is chosen maximal with respect to inclusion, and that no prime factor of $c_{r+L}$ divides all coefficients of $A_{r+L}$ and{\nobreakspace}$b_{r+L}$. 

 \index{rcwa mapping@rcwa mapping!modulus} \index{rcwa mapping@rcwa mapping!class-wise translating} \index{class-wise translating@class\texttt{\symbol{45}}wise translating!definition} \index{prime set@prime set!definition} We call the lattice $L$ the \emph{modulus} of $f$, written Mod($f$). Further we define the \emph{prime set} of{\nobreakspace}$f$ as the set of all primes which divide the determinant of at least one of the
coefficients $A_{r+L}$ or which divide the determinant of{\nobreakspace}$M$, and we call the mapping{\nobreakspace}$f$ \emph{class\texttt{\symbol{45}}wise translating} if all coefficients{\nobreakspace}$A_{r+L}$ are identity matrices and all coefficients{\nobreakspace}$c_{r+L}$ are equal to{\nobreakspace}1. 

 For the sake of simplicity, we identify a lattice with the Hermite normal form
of the matrix by whose rows it is spanned. }

  
\section{\textcolor{Chapter }{ Entering residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine
mappings of ${\ensuremath{\mathbb Z}}^2$ }}\label{sec:EnteringRcwaMappingsOfZxZ}
\logpage{[ 5, 2, 0 ]}
\hyperdef{L}{X7A39FCF08030AB9B}{}
{
  Residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine mappings of ${\ensuremath{\mathbb Z}}^2$ can be entered using the general constructor \texttt{RcwaMapping} (\ref{RcwaMapping:by ring, modulus and list of coefficients}) or the more specialized functions \texttt{ClassTransposition} (\ref{ClassTransposition:r1, m1, r2, m2}), \texttt{ClassRotation} (\ref{ClassRotation:cl, u}) and \texttt{ClassShift} (\ref{ClassShift:cl}). The arguments differ only slightly. 
\subsection{\textcolor{Chapter }{ RcwaMapping (the general constructor; methods for ${\ensuremath{\mathbb Z}}^2$) }}\logpage{[ 5, 2, 1 ]}
\hyperdef{L}{X790649618012C606}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RcwaMapping({\mdseries\slshape R, L, coeffs})\index{RcwaMapping@\texttt{RcwaMapping}!by ring = Z x Z, modulus and coefficients}
\label{RcwaMapping:by ring = Z x Z, modulus and coefficients}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RcwaMapping({\mdseries\slshape P1, P2})\index{RcwaMapping@\texttt{RcwaMapping}!by two partitions of Z x Z into residue classes}
\label{RcwaMapping:by two partitions of Z x Z into residue classes}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RcwaMapping({\mdseries\slshape cycles})\index{RcwaMapping@\texttt{RcwaMapping}!of Z x Z, by residue class cycles}
\label{RcwaMapping:of Z x Z, by residue class cycles}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RcwaMapping({\mdseries\slshape f, g})\index{RcwaMapping@\texttt{RcwaMapping}!of Z x Z, by projections to coordinates}
\label{RcwaMapping:of Z x Z, by projections to coordinates}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 an rcwa mapping of ${\ensuremath{\mathbb Z}}^2$. 



 The above methods return 
\begin{description}
\item[{(a)}]  the rcwa mapping of \texttt{\mbox{\texttt{\mdseries\slshape R}} = Integers\texttt{\symbol{94}}2} with modulus{\nobreakspace}\mbox{\texttt{\mdseries\slshape L}} and coefficients \mbox{\texttt{\mdseries\slshape coeffs}}, 
\item[{(b)}]  an rcwa permutation which induces a bijection between the partitions \mbox{\texttt{\mdseries\slshape P1}} and \mbox{\texttt{\mdseries\slshape P2}} of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ into residue classes and which is affine on the elements of \mbox{\texttt{\mdseries\slshape P1}}, 
\item[{(c)}]  an rcwa permutation with ``residue class cycles'' given by a list \mbox{\texttt{\mdseries\slshape cycles}} of lists of pairwise disjoint residue classes of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ each of which it permutes cyclically, and 
\item[{(d)}]  the rcwa mapping of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ whose projections to the coordinates are given by \mbox{\texttt{\mdseries\slshape f}} and{\nobreakspace}\mbox{\texttt{\mdseries\slshape g}}, 
\end{description}
 respectively. 

 The modulus of an rcwa mapping of ${\ensuremath{\mathbb Z}}^2$ is a lattice of full rank. It is represented by a matrix \mbox{\texttt{\mdseries\slshape L}} in Hermite normal form, whose rows are the spanning vectors. 

 A coefficient list for an rcwa mapping of ${\ensuremath{\mathbb Z}}^2$ with modulus{\nobreakspace}\mbox{\texttt{\mdseries\slshape L}} consists of $|\det(\mbox{\texttt{\mdseries\slshape L}})|$ coefficient triples \texttt{[}$A_{r+{\ensuremath{\mathbb Z}}^2\mbox{\texttt{\mdseries\slshape L}}}$, $b_{r+{\ensuremath{\mathbb Z}}^2\mbox{\texttt{\mdseries\slshape L}}}$, $c_{r+{\ensuremath{\mathbb Z}}^2\mbox{\texttt{\mdseries\slshape L}}}$\texttt{]}. The entries $A_{r+{\ensuremath{\mathbb Z}}^2\mbox{\texttt{\mdseries\slshape L}}}$ are $2 \times 2$ integer matrices, the $b_{r+{\ensuremath{\mathbb Z}}^2\mbox{\texttt{\mdseries\slshape L}}}$ are elements of ${\ensuremath{\mathbb Z}}^2$, i.e. lists of two integers, and the $c_{r+{\ensuremath{\mathbb Z}}^2\mbox{\texttt{\mdseries\slshape L}}}$ are integers. The ordering of the coefficient triples is determined by the
ordering of the representatives of the residue classes $r+{\ensuremath{\mathbb Z}}^2\mbox{\texttt{\mdseries\slshape L}}$ in the sorted list returned by \texttt{AllResidues(Integers\texttt{\symbol{94}}2,\mbox{\texttt{\mdseries\slshape L}})}. 

 The methods for the operation \texttt{RcwaMapping} perform a number of argument checks, which can be skipped by using \texttt{RcwaMappingNC} instead. 

 Last but not least, regarding Method{\nobreakspace}(d) it should be mentioned
that only very special rcwa mappings of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ have projections to coordinates. 
\begin{Verbatim}[commandchars=!@E,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>E !gapinput@R := Integers^2;;E
  !gapprompt@gap>E !gapinput@twice := RcwaMapping(R,[[1,0],[0,1]],E
  !gapprompt@>E !gapinput@                          [[[[2,0],[0,2]],[0,0],1]]);       # method (a)E
  Rcwa mapping of Z^2: (m,n) -> (2m,2n)
  !gapprompt@gap>E !gapinput@[4,5]^twice;E
  [ 8, 10 ]
  !gapprompt@gap>E !gapinput@twice1 := RcwaMapping(R,[[1,0],[0,1]],E
  !gapprompt@>E !gapinput@                           [[[[2,0],[0,1]],[0,0],1]]);      # method (a)E
  Rcwa mapping of Z^2: (m,n) -> (2m,n)
  !gapprompt@gap>E !gapinput@[4,5]^twice1;E
  [ 8, 5 ]
  !gapprompt@gap>E !gapinput@Image(twice1);E
  (0,0)+(2,0)Z+(0,1)Z
  !gapprompt@gap>E !gapinput@hyperbolic := RcwaMapping(R,[[1,0],[0,2]],E
  !gapprompt@>E !gapinput@                               [[[[4,0],[0,1]],[0, 0],2],E
  !gapprompt@>E !gapinput@                                [[[4,0],[0,1]],[2,-1],2]]); # method (a)E
  <rcwa mapping of Z^2 with modulus (1,0)Z+(0,2)Z>
  !gapprompt@gap>E !gapinput@IsBijective(hyperbolic);E
  true
  !gapprompt@gap>E !gapinput@Display(hyperbolic);E
  
  Rcwa permutation of Z^2 with modulus (1,0)Z+(0,2)Z
  
              /
              | (2m,n/2)       if (m,n) in (0,0)+(1,0)Z+(0,2)Z
   (m,n) |-> <  (2m+1,(n-1)/2) if (m,n) in (0,1)+(1,0)Z+(0,2)Z
              |
              java.lang.NullPointerException
  
  !gapprompt@gap>E !gapinput@Trajectory(hyperbolic,[0,10000],20);E
  [ [ 0, 10000 ], [ 0, 5000 ], [ 0, 2500 ], [ 0, 1250 ], [ 0, 625 ], 
    [ 1, 312 ], [ 2, 156 ], [ 4, 78 ], [ 8, 39 ], [ 17, 19 ], [ 35, 9 ], 
    [ 71, 4 ], [ 142, 2 ], [ 284, 1 ], [ 569, 0 ], [ 1138, 0 ], 
    [ 2276, 0 ], [ 4552, 0 ], [ 9104, 0 ], [ 18208, 0 ] ]
  !gapprompt@gap>E !gapinput@P1 := AllResidueClassesModulo(R,[[2,1],[0,2]]);E
  [ (0,0)+(2,1)Z+(0,2)Z, (0,1)+(2,1)Z+(0,2)Z, (1,0)+(2,1)Z+(0,2)Z,
    (1,1)+(2,1)Z+(0,2)Z ]
  !gapprompt@gap>E !gapinput@P2 := AllResidueClassesModulo(R,[[1,0],[0,4]]);E
  [ (0,0)+(1,0)Z+(0,4)Z, (0,1)+(1,0)Z+(0,4)Z, (0,2)+(1,0)Z+(0,4)Z,
    (0,3)+(1,0)Z+(0,4)Z ]
  !gapprompt@gap>E !gapinput@g := RcwaMapping(P1,P2);                                 # method (b)E
  <rcwa permutation of Z^2 with modulus (2,1)Z+(0,2)Z>
  !gapprompt@gap>E !gapinput@P1^g = P2;E
  true
  !gapprompt@gap>E !gapinput@Display(g:AsTable);E
  
  Rcwa permutation of Z^2 with modulus (2,1)Z+(0,2)Z
  
     [m,n] mod (2,1)Z+(0,2)Z   |              Image of [m,n]
  -----------------------------+-------------------------------------------
   [0,0]                       | [m/2,-m+2n]
   [0,1]                       | [m/2,-m+2n-1]
   [1,0]                       | [(m-1)/2,-m+2n+3]
   [1,1]                       | [(m-1)/2,-m+2n+2]
  
  !gapprompt@gap>E !gapinput@classes := List([[[0,0],[[2,1],[0,2]]],[[1,0],[[2,1],[0,4]]],E
  !gapprompt@>E !gapinput@                    [[1,1],[[4,2],[0,4]]]],ResidueClass);E
  [ (0,0)+(2,1)Z+(0,2)Z, (1,0)+(2,1)Z+(0,4)Z, (1,1)+(4,2)Z+(0,4)Z ]
  !gapprompt@gap>E !gapinput@g := RcwaMapping([classes]);                             # method (c)E
  <rcwa permutation of Z^2 with modulus (4,2)Z+(0,4)Z, of order 3>
  !gapprompt@gap>E !gapinput@Permutation(g,classes);E
  (1,2,3)
  !gapprompt@gap>E !gapinput@Support(g);E
  (0,0)+(2,1)Z+(0,2)Z U (1,0)+(2,1)Z+(0,4)Z U (1,1)+(4,2)Z+(0,4)Z
  !gapprompt@gap>E !gapinput@Display(g);E
  
  Rcwa permutation of Z^2 with modulus (4,2)Z+(0,4)Z, of order 3
  
              /
              | (m+1,(-m+4n)/2)   if (m,n) in (0,0)+(2,1)Z+(0,2)Z
              | (2m-1,(m+2n+1)/2) if (m,n) in (1,0)+(2,1)Z+(0,4)Z
   (m,n) |-> <  ((m-1)/2,(n-1)/2) if (m,n) in (1,1)+(4,2)Z+(0,4)Z
              | (m,n)             otherwise
              |
              java.lang.NullPointerException
  
  !gapprompt@gap>E !gapinput@g := RcwaMapping(ClassTransposition(0,2,1,2),E
  !gapprompt@>E !gapinput@                    ClassReflection(0,2));                  # method (d)E
  <rcwa mapping of Z^2 with modulus (2,0)Z+(0,2)Z>
  !gapprompt@gap>E !gapinput@Display(g);E
  
  Rcwa mapping of Z^2 with modulus (2,0)Z+(0,2)Z
  
              /
              | (m+1,-n) if (m,n) in (0,0)+(2,0)Z+(0,2)Z
              | (m+1,n)  if (m,n) in (0,1)+(2,0)Z+(0,2)Z
   (m,n) |-> <  (m-1,-n) if (m,n) in (1,0)+(2,0)Z+(0,2)Z
              | (m-1,n)  if (m,n) in (1,1)+(2,0)Z+(0,2)Z
              |
              java.lang.NullPointerException
  
  !gapprompt@gap>E !gapinput@g^2;E
  IdentityMapping( ( Integers^2 ) )
  !gapprompt@gap>E !gapinput@List(ProjectionsToCoordinates(g),Factorization);E
  [ [ ( 0(2), 1(2) ) ], [ ClassReflection( 0(2) ) ] ]
  
\end{Verbatim}
 }

 
\subsection{\textcolor{Chapter }{ ClassTransposition (for ${\ensuremath{\mathbb Z}}^2$) }}\logpage{[ 5, 2, 2 ]}
\hyperdef{L}{X7B450EE17B465E02}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ClassTransposition({\mdseries\slshape r1, L1, r2, L2})\index{ClassTransposition@\texttt{ClassTransposition}!r1, L1, r2, L2 (for Z x Z)}
\label{ClassTransposition:r1, L1, r2, L2 (for Z x Z)}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ClassTransposition({\mdseries\slshape cl1, cl2})\index{ClassTransposition@\texttt{ClassTransposition}!cl1, cl2 (for Z x Z)}
\label{ClassTransposition:cl1, cl2 (for Z x Z)}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the class transposition $\tau_{r_1+{\ensuremath{\mathbb Z}}^2L_1,r_2+{\ensuremath{\mathbb Z}}^2L_2}$. 



 Let $d \in {\ensuremath{\mathbb N}}$, and let $L_1, L_2 \in {\ensuremath{\mathbb Z}}^{d \times d}$ be matrices of full rank which are in Hermite normal form. Further let $r_1 + {\ensuremath{\mathbb Z}}^d L_1$ and $r_2 + {\ensuremath{\mathbb Z}}^d L_2$ be disjoint residue classes, and assume that the representatives $r_1$ and $r_2$ are reduced modulo{\nobreakspace}${\ensuremath{\mathbb Z}}^d L_1$ and{\nobreakspace}${\ensuremath{\mathbb Z}}^d L_2$, respectively. Then we define the \emph{class transposition} $\tau_{r_1+{\ensuremath{\mathbb Z}}^d L_1, r_2+{\ensuremath{\mathbb Z}}^d L_2}
\in {\rm Sym}({\ensuremath{\mathbb Z}}^d)$ as the involution which interchanges $r_1 + k L_1$ and $r_2 + k L_2$ for all $k \in {\ensuremath{\mathbb Z}}^d$. 

 The class transposition $\tau_{r_1+{\ensuremath{\mathbb Z}}^d L_1, r_2+{\ensuremath{\mathbb Z}}^d L_2}$ interchanges the residue classes $r_1+{\ensuremath{\mathbb Z}}^d L_1$ and $r_2+{\ensuremath{\mathbb Z}}^d L_2$, and fixes the complement of their union pointwise. The set of all class
transpositions of{\nobreakspace}${\ensuremath{\mathbb Z}}^d$ generates the simple group CT(${\ensuremath{\mathbb Z}}^d$) (cf.{\nobreakspace}\cite{Kohl13}). 

 \index{TransposedClasses@\texttt{TransposedClasses}!of a class transposition of Z x Z} In the four\texttt{\symbol{45}}argument form, the arguments \mbox{\texttt{\mdseries\slshape r1}}, \mbox{\texttt{\mdseries\slshape L1}}, \mbox{\texttt{\mdseries\slshape r2}} and{\nobreakspace}\mbox{\texttt{\mdseries\slshape L2}} stand for $r_1$, $L_1$, $r_2$ and{\nobreakspace}$L_2$, respectively. In the two\texttt{\symbol{45}}argument form, the arguments \mbox{\texttt{\mdseries\slshape cl1}} and{\nobreakspace}\mbox{\texttt{\mdseries\slshape cl2}} stand for the residue classes $r_1+{\ensuremath{\mathbb Z}}^2 L_1$ and{\nobreakspace}$r_2+{\ensuremath{\mathbb Z}}^2 L_2$, respectively. Enclosing the argument list in list brackets is permitted. The
residue classes $r_1+{\ensuremath{\mathbb Z}}^2 L_1$ and $r_2+{\ensuremath{\mathbb Z}}^2 L_2$ are stored as an attribute \texttt{TransposedClasses}. 

 \index{SplittedClassTransposition@\texttt{SplittedClassTransposition}!for a class transposition of Z x Z} There is also a method for \texttt{SplittedClassTransposition} available for class transpositions of ${\ensuremath{\mathbb Z}}^2$. This method takes as first argument the class transposition, and as second
argument a list of two integers. These integers are the numbers of parts into
which the class transposition is to be sliced in each dimension. Note that the
product of the returned class transpositions is not always equal to the class
transposition passed as first argument. However this equality holds if the
first entry of the second argument is{\nobreakspace}1. 

 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@ct := ClassTransposition([0,0],[[2,1],[0,2]],[1,0],[[2,1],[0,4]]);A
  ( (0,0)+(2,1)Z+(0,2)Z, (1,0)+(2,1)Z+(0,4)Z )
  !gapprompt@gap>A !gapinput@Display(ct);A
  
  Rcwa permutation of Z^2 with modulus (2,1)Z+(0,4)Z, of order 2
  
              /
              | (m+1,(-m+4n)/2)  if (m,n) in (0,0)+(2,1)Z+(0,2)Z
   (m,n) |-> <  (m-1,(m+2n-1)/4) if (m,n) in (1,0)+(2,1)Z+(0,4)Z
              | (m,n)            otherwise
              java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@TransposedClasses(ct);A
  [ (0,0)+(2,1)Z+(0,2)Z, (1,0)+(2,1)Z+(0,4)Z ]
  !gapprompt@gap>A !gapinput@ct = ClassTransposition(last);A
  true
  !gapprompt@gap>A !gapinput@SplittedClassTransposition(ct,[1,2]);A
  [ ( (0,0)+(2,1)Z+(0,4)Z, (1,0)+(2,1)Z+(0,8)Z ), 
    ( (0,2)+(2,1)Z+(0,4)Z, (1,4)+(2,1)Z+(0,8)Z ) ]
  !gapprompt@gap>A !gapinput@Product(last) = ct;A
  true
  !gapprompt@gap>A !gapinput@SplittedClassTransposition(ct,[2,1]);A
  [ ( (0,0)+(4,0)Z+(0,2)Z, (1,0)+(4,2)Z+(0,4)Z ), 
    ( (2,1)+(4,0)Z+(0,2)Z, (3,1)+(4,2)Z+(0,4)Z ) ]
  !gapprompt@gap>A !gapinput@Product(last) = ct;A
  false
  
\end{Verbatim}
 }

 
\subsection{\textcolor{Chapter }{ ClassRotation (for ${\ensuremath{\mathbb Z}}^2$) }}\logpage{[ 5, 2, 3 ]}
\hyperdef{L}{X828438127DDAEBB4}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ClassRotation({\mdseries\slshape r, L, u})\index{ClassRotation@\texttt{ClassRotation}!r, L, u; for Z x Z}
\label{ClassRotation:r, L, u; for Z x Z}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ClassRotation({\mdseries\slshape cl, u})\index{ClassRotation@\texttt{ClassRotation}!cl, u; for Z x Z}
\label{ClassRotation:cl, u; for Z x Z}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the class rotation $\rho_{r(m),u}$. 



 Let $d \in {\ensuremath{\mathbb N}}$. Given a residue class $r+{\ensuremath{\mathbb Z}}^dL$ and a matrix $u \in {\rm GL}(d,{\ensuremath{\mathbb Z}})$, the \emph{class rotation} $\rho_{r+{\ensuremath{\mathbb Z}}^dL,u}$ is the rcwa mapping which maps $v \in r+{\ensuremath{\mathbb Z}}^dL$ to $vu + r(1-u)$ and which fixes ${\ensuremath{\mathbb Z}}^d \setminus r+{\ensuremath{\mathbb Z}}^dL$ pointwise. \index{RotationFactor@\texttt{RotationFactor}!of a class rotation of Z x Z} In the two\texttt{\symbol{45}}argument form, the argument{\nobreakspace}\mbox{\texttt{\mdseries\slshape cl}} stands for the residue class{\nobreakspace}$r+{\ensuremath{\mathbb Z}}^dL$. Enclosing the argument list in list brackets is permitted. The argument \mbox{\texttt{\mdseries\slshape u}} is stored as an attribute \texttt{RotationFactor}. 
\begin{Verbatim}[commandchars=!@B,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>B !gapinput@interchange := ClassRotation([0,0],[[1,0],[0,1]],[[0,1],[1,0]]);B
  ClassRotation( Z^2, [ [ 0, 1 ], [ 1, 0 ] ] )
  !gapprompt@gap>B !gapinput@Display(interchange);B
  Rcwa permutation of Z^2: (m,n) -> (n,m)
  !gapprompt@gap>B !gapinput@classes := AllResidueClassesModulo(Integers^2,[[2,1],[0,3]]);B
  [ (0,0)+(2,1)Z+(0,3)Z, (0,1)+(2,1)Z+(0,3)Z, (0,2)+(2,1)Z+(0,3)Z, 
    (1,0)+(2,1)Z+(0,3)Z, (1,1)+(2,1)Z+(0,3)Z, (1,2)+(2,1)Z+(0,3)Z ]
  !gapprompt@gap>B !gapinput@transvection := ClassRotation(classes[5],[[1,1],[0,1]]);B
  ClassRotation((1,1)+(2,1)Z+(0,3)Z,[[1,1],[0,1]])
  !gapprompt@gap>B !gapinput@Display(transvection);B
  
  Tame rcwa permutation of Z^2 with modulus (2,1)Z+(0,3)Z, of order infinity
  
              /
              | (m,(3m+2n-3)/2) if (m,n) in (1,1)+(2,1)Z+(0,3)Z
   (m,n) |-> <  (m,n)           otherwise
              |
              java.lang.NullPointerException
  
\end{Verbatim}
 }

 
\subsection{\textcolor{Chapter }{ ClassShift (for ${\ensuremath{\mathbb Z}}^2$) }}\logpage{[ 5, 2, 4 ]}
\hyperdef{L}{X7A14A8F48247E651}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ClassShift({\mdseries\slshape r, L, k})\index{ClassShift@\texttt{ClassShift}!r, L, k; for Z x Z}
\label{ClassShift:r, L, k; for Z x Z}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ClassShift({\mdseries\slshape cl, k})\index{ClassShift@\texttt{ClassShift}!cl, k; for Z x Z}
\label{ClassShift:cl, k; for Z x Z}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the class shift $\nu_{r+{\ensuremath{\mathbb Z}}^dL,k}$. 



 Let $d \in {\ensuremath{\mathbb N}}$. Given a residue class $r+{\ensuremath{\mathbb Z}}^dL$ and an integer $k \in \{1, \dots, d\}$, the \emph{class shift} $\nu_{r+{\ensuremath{\mathbb Z}}^dL,k}$ is the rcwa mapping which maps $v \in r+{\ensuremath{\mathbb Z}}^dL$ to $v + L_k$ and which fixes ${\ensuremath{\mathbb Z}}^d \setminus r+{\ensuremath{\mathbb Z}}^dL$ pointwise. Here $L_k$ denotes the $k$th row of{\nobreakspace}$L$. 

 In the two\texttt{\symbol{45}}argument form, the argument{\nobreakspace}\mbox{\texttt{\mdseries\slshape cl}} stands for the residue class{\nobreakspace}$r+{\ensuremath{\mathbb Z}}^dL$. Enclosing the argument list in list brackets is permitted. 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@shift1 := ClassShift([0,0],[[1,0],[0,1]],1);A
  ClassShift( Z^2, 1 )
  !gapprompt@gap>A !gapinput@Display(shift1);A
  Tame rcwa permutation of Z^2: (m,n) -> (m+1,n)
  !gapprompt@gap>A !gapinput@s := ClassShift(ResidueClass([1,1],[[2,1],[0,2]]),2);A
  ClassShift((1,1)+(2,1)Z+(0,2)Z,2)
  !gapprompt@gap>A !gapinput@Display(s);A
  
  Tame rcwa permutation of Z^2 with modulus (2,1)Z+(0,2)Z, of order infinity
  
              /
              | (m,n+2) if (m,n) in (1,1)+(2,1)Z+(0,2)Z
   (m,n) |-> <  (m,n)   if (m,n) in (0,0)+(2,0)Z+(0,1)Z U 
              |                     (1,0)+(2,1)Z+(0,2)Z
              java.lang.NullPointerException
  
\end{Verbatim}
 }

 \index{IsClassTransposition@\texttt{IsClassTransposition}!for an rcwa mapping of Z x Z} \index{IsClassRotation@\texttt{IsClassRotation}!for an rcwa mapping of Z x Z} \index{IsClassShift@\texttt{IsClassShift}!for an rcwa mapping of Z x Z} As for other rings, class transpositions, class rotations and class shifts
of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ have the distinguishing properties \texttt{IsClassTransposition}, \texttt{IsClassRotation} and \texttt{IsClassShift}. }

  
\section{\textcolor{Chapter }{ Methods for residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine
mappings of ${\ensuremath{\mathbb Z}}^2$ }}\label{sec:MethodsForRcwaMappingsOfZxZ}
\logpage{[ 5, 3, 0 ]}
\hyperdef{L}{X8531E39785FFF8A7}{}
{
  There are methods available for rcwa mappings of ${\ensuremath{\mathbb Z}}^2$ for the following general operations: \index{View@\texttt{View}!for an rcwa mapping of Z x Z} \index{Display@\texttt{Display}!for an rcwa mapping of Z x Z} \index{Print@\texttt{Print}!for an rcwa mapping of Z x Z} \index{String@\texttt{String}!for an rcwa mapping of Z x Z} \index{LaTeXStringRcwaMapping@\texttt{LaTeXStringRcwaMapping}!for an rcwa mapping of Z x Z} \index{LaTeXAndXDVI@\texttt{LaTeXAndXDVI}!for an rcwa mapping of Z x Z} \index{Modulus@\texttt{Modulus}!of an rcwa mapping of Z x Z} \index{Coefficients@\texttt{Coefficients}!of an rcwa mapping of Z x Z} \index{Support@\texttt{Support}!of an rcwa mapping of Z x Z} \index{MovedPoints@\texttt{MovedPoints}!of an rcwa mapping of Z x Z} \index{Order@\texttt{Order}!of an rcwa mapping of Z x Z} \index{Multiplier@\texttt{Multiplier}!of an rcwa mapping of Z x Z} \index{Divisor@\texttt{Divisor}!of an rcwa mapping of Z x Z} \index{PrimeSet@\texttt{PrimeSet}!of an rcwa mapping of Z x Z} \index{One@\texttt{One}!for an rcwa mapping of Z x Z} \index{Zero@\texttt{Zero}!for an rcwa mapping of Z x Z} \index{IsInjective@\texttt{IsInjective}!for an rcwa mapping of Z x Z} \index{IsSurjective@\texttt{IsSurjective}!for an rcwa mapping of Z x Z} \index{IsBijective@\texttt{IsBijective}!for an rcwa mapping of Z x Z} \index{IsTame@\texttt{IsTame}!for an rcwa mapping of Z x Z} \index{IsIntegral@\texttt{IsIntegral}!for an rcwa mapping of Z x Z} \index{IsBalanced@\texttt{IsBalanced}!for an rcwa mapping of Z x Z} \index{IsClassWiseOrderPreserving@\texttt{IsClassWiseOrderPreserving}!for an rcwa mapping of Z x Z} \index{IsOne@\texttt{IsOne}!for an rcwa mapping of Z x Z} \index{IsZero@\texttt{IsZero}!for an rcwa mapping of Z x Z} \index{Trajectory@\texttt{Trajectory}!for rcwa mappings of Z x Z} \index{ShortCycles@\texttt{ShortCycles}!for rcwa perm. of Z x Z, set of points and max. length} \index{Multpk@\texttt{Multpk}!for rcwa mapping of Z x Z, prime and exponent} \index{ClassWiseOrderPreservingOn@\texttt{ClassWiseOrderPreservingOn}!for rcwa mappings of Z x Z} \index{ClassWiseOrderReversingOn@\texttt{ClassWiseOrderReversingOn}!for rcwa mappings of Z x Z} \index{ClassWiseConstantOn@\texttt{ClassWiseConstantOn}!for rcwa mappings of Z x Z} 
\begin{description}
\item[{ Output }]  \texttt{View}, \texttt{Display}, \texttt{Print}, \texttt{String}, \texttt{LaTeXStringRcwaMapping}, \texttt{LaTeXAndXDVI}. 
\item[{ Access to components }]  \texttt{Modulus}, \texttt{Coefficients}. 
\item[{ Attributes }]  \texttt{Support} / \texttt{MovedPoints}, \texttt{Order}, \texttt{Multiplier}, \texttt{Divisor}, \texttt{PrimeSet}, \texttt{One}, \texttt{Zero}. 
\item[{ Properties }]  \texttt{IsInjective}, \texttt{IsSurjective}, \texttt{IsBijective}, \texttt{IsTame}, \texttt{IsIntegral}, \texttt{IsBalanced}, \texttt{IsClassWiseOrderPreserving}, \texttt{IsOne}, \texttt{IsZero}. 
\item[{ Action on ${\ensuremath{\mathbb Z}}^d$ }]  \texttt{\texttt{\symbol{94}}} (for points / finite sets / residue class unions), \texttt{Trajectory}, \texttt{ShortCycles}, \texttt{Multpk}, \texttt{ClassWiseOrderPreservingOn}, \texttt{ClassWiseOrderReversingOn}, \texttt{ClassWiseConstantOn}. 
\item[{ Arithmetical operations }]  \texttt{=}, \texttt{*} (multiplication / composition and multiplication by a $2 \times 2$ matrix or an integer), \texttt{\texttt{\symbol{94}}} (exponentiation and conjugation), \texttt{Inverse}, \texttt{+} (addition of a constant). 
\end{description}
 The above operations are documented either in the \textsf{GAP} Reference Manual or earlier in this manual. The operations which are special
for rcwa mappings of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ are described in the sequel. 

 

\subsection{\textcolor{Chapter }{ProjectionsToCoordinates (for an rcwa mapping of Z x Z)}}
\logpage{[ 5, 3, 1 ]}\nobreak
\hyperdef{L}{X8408B7837C9EED36}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ProjectionsToCoordinates({\mdseries\slshape f})\index{ProjectionsToCoordinates@\texttt{ProjectionsToCoordinates}!for an rcwa mapping of Z x Z}
\label{ProjectionsToCoordinates:for an rcwa mapping of Z x Z}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 the projections of the rcwa mapping \mbox{\texttt{\mdseries\slshape f}} of ${\ensuremath{\mathbb Z}}^2$ to the coordinates if such projections exist, and \texttt{fail} otherwise. 



 An rcwa mapping can be projected to the first / second coordinate if and only
if the first / second coordinate of the image of a point depends only on the
first / second coordinate of the preimage. Note that this is a very strong and
restrictive condition. 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@f := RcwaMapping(ClassTransposition(0,2,1,2),ClassReflection(0,2));;A
  !gapprompt@gap>A !gapinput@Display(f);A
  
  Rcwa mapping of Z^2 with modulus (2,0)Z+(0,2)Z
  
              /
              | (m+1,-n) if (m,n) in (0,0)+(2,0)Z+(0,2)Z
              | (m+1,n)  if (m,n) in (0,1)+(2,0)Z+(0,2)Z
   (m,n) |-> <  (m-1,-n) if (m,n) in (1,0)+(2,0)Z+(0,2)Z
              | (m-1,n)  if (m,n) in (1,1)+(2,0)Z+(0,2)Z
              |
              java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@List(ProjectionsToCoordinates(f),Factorization);A
  [ [ ( 0(2), 1(2) ) ], [ ClassReflection( 0(2) ) ] ]
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{ Methods for residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine
groups and \texttt{\symbol{45}}monoids over ${\ensuremath{\mathbb Z}}^2$ }}\label{sec:MethodsForRcwaGroupsOverZxZ}
\logpage{[ 5, 4, 0 ]}
\hyperdef{L}{X83A1752F7BE9CE85}{}
{
  \index{Rcwa@\texttt{Rcwa}!the monoid formed by all rcwa permutations of Z x Z} \index{RCWA@\texttt{RCWA}!the group formed by all rcwa permutations of Z x Z} \index{CT@\texttt{CT}!the group generated by all class transpositions of Z x Z} Residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine groups over ${\ensuremath{\mathbb Z}}^2$ can be entered by \texttt{Group}, \texttt{GroupByGenerators} and \texttt{GroupWithGenerators}, like any groups in \textsf{GAP}. Likewise, residue\texttt{\symbol{45}}class\texttt{\symbol{45}}wise affine
monoids over ${\ensuremath{\mathbb Z}}^2$ can be entered by \texttt{Monoid} and \texttt{MonoidByGenerators}. The groups RCWA(${\ensuremath{\mathbb Z}}^2$) and CT(${\ensuremath{\mathbb Z}}^2$) are entered as \texttt{RCWA(Integers\texttt{\symbol{94}}2)} and \texttt{CT(Integers\texttt{\symbol{94}}2)}, respectively. The monoid Rcwa(${\ensuremath{\mathbb Z}}^2$) is entered as \texttt{Rcwa(Integers\texttt{\symbol{94}}2)}. 

 \index{Size@\texttt{Size}!for an rcwa group over Z x Z} \index{IsIntegral@\texttt{IsIntegral}!for an rcwa group over Z x Z} \index{IsClassWiseTranslating@\texttt{IsClassWiseTranslating}!for an rcwa group over Z x Z} \index{IsTame@\texttt{IsTame}!for an rcwa group over Z x Z} \index{Modulus@\texttt{Modulus}!of an rcwa group over Z x Z} \index{Multiplier@\texttt{Multiplier}!of an rcwa group over Z x Z} \index{Divisor@\texttt{Divisor}!of an rcwa group over Z x Z} There are methods provided for the operations \texttt{Size}, \texttt{IsIntegral}, \texttt{IsClassWiseTranslating}, \texttt{IsTame}, \texttt{Modulus}, \texttt{Multiplier} and \texttt{Divisor}. 

 There are methods for \texttt{IsomorphismRcwaGroup} (\ref{IsomorphismRcwaGroup:for a group, over a given ring}) which embed the groups SL(2,{\ensuremath{\mathbb Z}}) and
GL(2,{\ensuremath{\mathbb Z}}) into RCWA(${\ensuremath{\mathbb Z}}^2$) in such a way that the support of the image is a specified residue class: 
\subsection{\textcolor{Chapter }{ IsomorphismRcwaGroup (Embeddings of SL(2,{\ensuremath{\mathbb Z}}) and
GL(2,{\ensuremath{\mathbb Z}})) }}\logpage{[ 5, 4, 1 ]}
\hyperdef{L}{X79A8F9AD7E839862}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsomorphismRcwaGroup({\mdseries\slshape sl2z, cl})\index{IsomorphismRcwaGroup@\texttt{IsomorphismRcwaGroup}!for SL(2,Z) and a residue class}
\label{IsomorphismRcwaGroup:for SL(2,Z) and a residue class}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsomorphismRcwaGroup({\mdseries\slshape gl2z, cl})\index{IsomorphismRcwaGroup@\texttt{IsomorphismRcwaGroup}!for GL(2,Z) and a residue class}
\label{IsomorphismRcwaGroup:for GL(2,Z) and a residue class}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 a monomorphism from \mbox{\texttt{\mdseries\slshape sl2z}} respectively \mbox{\texttt{\mdseries\slshape gl2z}} to{\nobreakspace}RCWA(${\ensuremath{\mathbb Z}}^2$), such that the support of the image is the residue class{\nobreakspace}\mbox{\texttt{\mdseries\slshape cl}} and the generators are affine on{\nobreakspace}\mbox{\texttt{\mdseries\slshape cl}}. 



 
\begin{Verbatim}[commandchars=!@B,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>B !gapinput@sl := SL(2,Integers);B
  SL(2,Integers)
  !gapprompt@gap>B !gapinput@phi := IsomorphismRcwaGroup(sl,ResidueClass([1,0],[[2,2],[0,3]]));B
  [ [ [ 0, 1 ], [ -1, 0 ] ], [ [ 1, 1 ], [ 0, 1 ] ] ] -> 
  [ ClassRotation((1,0)+(2,2)Z+(0,3)Z,[[0,1],[-1,0]]), 
    ClassRotation((1,0)+(2,2)Z+(0,3)Z,[[1,1],[0,1]]) ]
  !gapprompt@gap>B !gapinput@Support(Image(phi));B
  (1,0)+(2,2)Z+(0,3)Z
  !gapprompt@gap>B !gapinput@gl := GL(2,Integers);B
  GL(2,Integers)
  !gapprompt@gap>B !gapinput@phi := IsomorphismRcwaGroup(gl,ResidueClass([1,0],[[2,2],[0,3]]));B
  [ [ [ 0, 1 ], [ 1, 0 ] ], [ [ -1, 0 ], [ 0, 1 ] ], 
    [ [ 1, 1 ], [ 0, 1 ] ] ] -> 
  [ ClassRotation((1,0)+(2,2)Z+(0,3)Z,[[0,1],[1,0]]), 
    ClassRotation((1,0)+(2,2)Z+(0,3)Z,[[-1,0],[0,1]]), 
    ClassRotation((1,0)+(2,2)Z+(0,3)Z,[[1,1],[0,1]]) ]
  !gapprompt@gap>B !gapinput@[[-47,-37],[61,48]]^phi;B
  ClassRotation((1,0)+(2,2)Z+(0,3)Z,[[-47,-37],[61,48]])
  !gapprompt@gap>B !gapinput@Display(last:AsTable);B
  
  Rcwa permutation of Z^2 with modulus (2,2)Z+(0,3)Z, of order 6
  
     [m,n] mod (2,2)Z+(0,3)Z   |              Image of [m,n]
  -----------------------------+-------------------------------------------
   [0,0] [0,1] [0,2] [1,1]     |
   [1,2]                       | [m,n]
   [1,0]                       | [(-263m+122n+266)/3,(-1147m+532n+1147)/6]
  
\end{Verbatim}
 }

 \index{DrawOrbitPicture@\texttt{DrawOrbitPicture}!for rcwa groups over Z x Z} The function \texttt{DrawOrbitPicture} (\ref{DrawOrbitPicture:G, p0, bound, h, w, colored, palette, filename}) can also be used to depict orbits under the action of rcwa groups
over{\nobreakspace}${\ensuremath{\mathbb Z}}^2$. Further there is a function which depicts residue class unions
of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ and partitions of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ into such: 
\subsection{\textcolor{Chapter }{ DrawGrid }}\logpage{[ 5, 4, 2 ]}
\hyperdef{L}{X812135EB87527F01}{}
{
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DrawGrid({\mdseries\slshape U, yrange, xrange, filename})\index{DrawGrid@\texttt{DrawGrid}!U, yrange, xrange, filename}
\label{DrawGrid:U, yrange, xrange, filename}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DrawGrid({\mdseries\slshape P, yrange, xrange, filename})\index{DrawGrid@\texttt{DrawGrid}!P, yrange, xrange, filename}
\label{DrawGrid:P, yrange, xrange, filename}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing. 



 This function depicts the residue class union \mbox{\texttt{\mdseries\slshape U}} of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ or the partition{\nobreakspace}\mbox{\texttt{\mdseries\slshape P}} of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ into residue class unions, respectively. The arguments \mbox{\texttt{\mdseries\slshape yrange}} and \mbox{\texttt{\mdseries\slshape xrange}} are the coordinate ranges of the rectangular snippet to be drawn, and the
argument \mbox{\texttt{\mdseries\slshape filename}} is the name, i.e. the full path name, of the output file. If the first
argument is a residue class union, the output picture is
black\texttt{\symbol{45}}and\texttt{\symbol{45}}white, where black pixels
represent members of{\nobreakspace}\mbox{\texttt{\mdseries\slshape U}} and white pixels represent non\texttt{\symbol{45}}members. If the first
argument is a partition of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ into residue class unions, the produced picture is colored, and different
colors are used to denote membership in different parts. }

 }

  }

       
\chapter{\textcolor{Chapter }{ Databases of Residue\texttt{\symbol{45}}Class\texttt{\symbol{45}}Wise Affine
Groups and \texttt{\symbol{45}}Mappings }}\label{ch:Databases}
\logpage{[ 6, 0, 0 ]}
\hyperdef{L}{X81BA344979567342}{}
{
  The \textsf{RCWA} package contains a number of databases of rcwa groups and rcwa mappings. They
can be loaded into a \textsf{GAP} session by the functions described in this chapter.  
\section{\textcolor{Chapter }{The collection of examples}}\label{sec:Examples}
\logpage{[ 6, 1, 0 ]}
\hyperdef{L}{X86CCBF017A746F50}{}
{
  

\subsection{\textcolor{Chapter }{LoadRCWAExamples}}
\logpage{[ 6, 1, 1 ]}\nobreak
\hyperdef{L}{X8714254784AFD64B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LoadRCWAExamples({\mdseries\slshape })\index{LoadRCWAExamples@\texttt{LoadRCWAExamples}}
\label{LoadRCWAExamples}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the name of the variable to which the record containing the collection of
examples of rcwa groups and \texttt{\symbol{45}}mappings loaded from the file \texttt{pkg/rcwa/examples/examples.g} got bound. 



 The components of the examples record are records which contain the individual
groups and mappings. A detailed description of some of the examples can be
found in Chapter{\nobreakspace}\ref{ch:Examples}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@LoadRCWAExamples();|
  "RCWAExamples"                                
  !gapprompt@gap>| !gapinput@Set(RecNames(RCWAExamples));|
  [ "AbelianGroupOverPolynomialRing", "Basics", "CT3Z", "CTPZ", 
    "CheckingForSolvability", "ClassSwitches", 
    "ClassTranspositionProducts", "ClassTranspositionsAsCommutators", 
    "CollatzFactorizationOld", "CollatzMapping", "CollatzlikePerms", 
    "CoprimeMultDiv", "F2_PSL2Z", "Farkas", "FiniteQuotients", 
    "FiniteVsDenseCycles", "GF2xFiniteCycles", "GrigorchukQuotients", 
    "Hexagon", "HicksMullenYucasZavislak", "HigmanThompson", 
    "LongCyclesOfPrimeLength", "MatthewsLeigh", 
    "MaybeInfinitelyPresentedGroup", "ModuliOfPowers", 
    "OddNumberOfGens_FiniteOrder", "Semilocals", 
    "SlowlyContractingMappings", "Syl3_S9", "SymmetrizingCollatzTree", 
    "TameGroupByCommsOfWildPerms", "Venturini", "ZxZ" ]
  !gapprompt@gap>| !gapinput@AssignGlobals(RCWAExamples.CollatzMapping);|
  The following global variables have been assigned:
  [ "T", "T5", "T5m", "T5p", "Tm", "Tp" ]
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{Databases of rcwa groups}}\label{sec:DatabasesOfRcwaGroups}
\logpage{[ 6, 2, 0 ]}
\hyperdef{L}{X85DD85DF87DE47C9}{}
{
  

\subsection{\textcolor{Chapter }{LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions (small database)}}
\logpage{[ 6, 2, 1 ]}\nobreak
\hyperdef{L}{X793E2C5C7FC935B8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions({\mdseries\slshape })\index{LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions@\texttt{Load}\-\texttt{Database}\-\texttt{Of}\-\texttt{Groups}\-\texttt{Generated}\-\texttt{By3}\-\texttt{Class}\-\texttt{Transpositions}!small database}
\label{LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions:small database}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the name of the variable to which the record containing the database of all
groups generated by 3 class transpositions which interchange residue classes
with moduli $\leq 6$ got bound. 



 The database record has at least the following components (the index \texttt{i} is always an integer in the range \texttt{[1..52394]}, and the term ``indices'' always refers to list indices in that range): 
\begin{description}
\item[{\texttt{cts}}]  The list of all 69 class transpositions which interchange residue classes with
moduli $\leq 6$. 
\item[{\texttt{grps}}]  The list of the 52394 groups \texttt{\symbol{45}}\texttt{\symbol{45}} 21948
finite and 30446 infinite ones. 
\item[{\texttt{sizes}}]  The list of group orders \texttt{\symbol{45}}\texttt{\symbol{45}} it is \texttt{Size(grps[i]) = sizes[i]}. 
\item[{\texttt{mods}}]  The list of moduli of the groups \texttt{\symbol{45}}\texttt{\symbol{45}} it
is \texttt{Mod(grps[i]) = mods[i]}. 
\item[{\texttt{equalityclasses}}]  A list of lists of indices \texttt{i} of groups which are known to be equal, i.e. if \texttt{i} and \texttt{j} lie in the same list, then \texttt{grps[i] = grps[j]}. 
\item[{\texttt{samegroups}}]  A list of lists, where \texttt{samegroups[i]} is a list of indices of groups which are known to be equal to \texttt{grps[i]}. 
\item[{\texttt{conjugacyclasses}}]  A list of lists of indices of groups which are known to be conjugate in
RCWA({\ensuremath{\mathbb Z}}). 
\item[{\texttt{subgroups}}]  A list of lists, where \texttt{subgroups[i]} is a list of indices of groups which are known to be proper subgroups of \texttt{grps[i]}. 
\item[{\texttt{supergroups}}]  A list of lists, where \texttt{supergroups[i]} is a list of indices of groups which are known to be proper supergroups of \texttt{grps[i]}. 
\item[{\texttt{chains}}]  A list of lists, where each list contains the indices of the groups in a
descending chain of subgroups. 
\item[{\texttt{respectedpartitions}}]  The list of shortest respected partitions. If \texttt{grps[i]} is finite, then \texttt{respectedpartitions[i]} is a list of pairs (residue, modulus) for the residue classes in the shortest
respected partition \texttt{grps[i]}. If \texttt{grps[i]} is infinite, then \texttt{respectedpartitions[i] = fail}. 
\item[{\texttt{partitionlengths}}]  The list of lengths of shortest respected partitions. If the group \texttt{grps[i]} is finite, then \texttt{partitionlengths[i]} is the length of the shortest respected partition of \texttt{grps[i]}. If \texttt{grps[i]} is infinite, then \texttt{partitionlengths[i] = 0}. 
\item[{\texttt{degrees}}]  The list of permutation degrees, i.e. numbers of moved points, in the action
of the finite groups on their shortest respected partitions. If there is no
respected partition, i.e. if \texttt{grps[i]} is infinite, then \texttt{degrees[i] = 0}. 
\item[{\texttt{orbitlengths}}]  The list of lists of orbit lengths in the action of the finite groups on their
shortest respected partitions. If \texttt{grps[i]} is infinite, then \texttt{orbitlengths[i] = fail}. 
\item[{\texttt{permgroupgens}}]  The list of lists of generators of the isomorphic permutation groups induced
by the finite groups on their shortest respected partitions. If \texttt{grps[i]} is infinite, then \texttt{permgroupgens[i] = fail}. 
\item[{\texttt{stabilize{\textunderscore}digitsum{\textunderscore}base2{\textunderscore}mod2}}]  The list of indices of groups which stabilize the digit sum in base 2
modulo{\nobreakspace}2. 
\item[{\texttt{stabilize{\textunderscore}digitsum{\textunderscore}base2{\textunderscore}mod3}}]  The list of indices of groups which stabilize the digit sum in base 2
modulo{\nobreakspace}3. 
\item[{\texttt{stabilize{\textunderscore}digitsum{\textunderscore}base3{\textunderscore}mod2}}]  The list of indices of groups which stabilize the digit sum in base 3
modulo{\nobreakspace}2. 
\item[{\texttt{freeproductcandidates}}]  A list of indices of groups which may be isomorphic to the free product of 3
copies of the cyclic group of order{\nobreakspace}2. 
\item[{\texttt{freeproductlikes}}]  A list of indices of groups which are not isomorphic to the free product of 3
copies of the cyclic group of order{\nobreakspace}2, but where the shortest
relation indicating this is relatively long. 
\item[{\texttt{abc{\textunderscore}torsion}}]  A list of pairs (index, order of product of generators) for all infinite
groups for which the product of the generators has finite order. 
\item[{\texttt{cyclist}}]  A list described in the comments in \texttt{rcwa/data/3ctsgroups6/spheresizecycles.g}. 
\item[{\texttt{finiteorbits}}]  A record described in the comments in \texttt{rcwa/data/3ctsgroups6/finite\texttt{\symbol{45}}orbits.g}. 
\item[{\texttt{intransitivemodulo}}]  For every modulus \texttt{m} from 1 to 60, \texttt{intransitivemodulo[m]} is the list of indices of groups none of whose orbits on {\ensuremath{\mathbb
Z}} has nontrivial intersection with all residue classes modulo{\nobreakspace}\texttt{m}. 
\item[{\texttt{trsstatus}}]  A list of strings which describe what is known about whether the groups \texttt{grps[i]} act transitively on the nonnegative integers in their support, or how the
computation has failed. 
\item[{\texttt{orbitgrowthtype}}]  A list of integers and lists of integers which encode what has been observed
heuristically on the growth of the orbits of the groups \texttt{grps[i]} on{\nobreakspace}{\ensuremath{\mathbb Z}}. 
\end{description}
 Note that the database contains an entry for every unordered
3\texttt{\symbol{45}}tuple of distinct class transpositions in \texttt{cts}, which means that it contains multiple copies of equal groups
\texttt{\symbol{45}}\texttt{\symbol{45}} cf. the components \texttt{equalityclasses} and \texttt{samegroups} described above. 

 To mention an example, the group \texttt{grps[44132]} might be called the ``Collatz group'' \texttt{\symbol{45}}\texttt{\symbol{45}} its action on the set of positive
integers which are not multiples of 6 is transitive if and only if the Collatz
conjecture holds. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions();|
  "3CTsGroups6"
  !gapprompt@gap>| !gapinput@AssignGlobals(3CTsGroups6); # for convenience|
  The following global variables have been assigned:
  [ "3CTsGroupsWithGivenOrbit", "Id3CTsGroup", 
    "ProbablyFixesDigitSumsModulo", "ProbablyStabilizesDigitSumsModulo", 
    "TriangleTypes", "abc_torsion", "chains", "conjugacyclasses", "cts", 
    "cyclist", "degrees", "epifromfpgroupto_ct23z", 
    "epifromfpgrouptocollatzgroup_c", "epifromfpgrouptocollatzgroup_t", 
    "equalityclasses", "finiteorbits", "freeproductcandidates", 
    "freeproductlikes", "groups", "grps", "intransitivemodulo", 
    "minwordlengthcoprimemultdiv", "minwordlengthnonbalanced", "mods", 
    "orbitgrowthtype", "orbitlengths", "partitionlengths", "permgroupgens",
    "redundant_generator", "refinementseqlngs", "respectedpartitions", 
    "samegroups", "shortresidueclassorbitlengths", "sizes", "sizespos", 
    "sizesset", "spheresizebound_12", "spheresizebound_24", 
    "spheresizebound_4", "spheresizebound_6", 
    "stabilize_digitsum_base2_mod2", "stabilize_digitsum_base2_mod3", 
    "stabilize_digitsum_base3_mod2", "subgroups", "supergroups", 
    "trsstatus", "trsstatuspos", "trsstatusset" ]
  !gapprompt@gap>| !gapinput@grps[44132]; # the "3n+1 group"|
  <(2(3),4(6)),(1(3),2(6)),(1(2),4(6))>
  !gapprompt@gap>| !gapinput@trsstatus[44132]; # deciding this would solve the 3n+1 problem|
  "exceeded memory bound"
  !gapprompt@gap>| !gapinput@Length(Set(sizes));|
  1066
  !gapprompt@gap>| !gapinput@Maximum(Filtered(sizes,IsInt)); # order of largest finite group stored|
  7165033589793852697531456980706732548435609645091822296777976465116824959java.lang.NullPointerException
  2135499174617837911754921014138184155204934961004073853323458315539461543java.lang.NullPointerException
  4480515260818409913846161473536000000000000000000000000000000000000000000java.lang.NullPointerException
  000000
  !gapprompt@gap>| !gapinput@PrintFactorsInt(last);                                    |
  2^200*3^103*5^48*7^28*11^16*13^13*17^8*19^6*23^6*29
  !gapprompt@gap>| !gapinput@Positions(sizes,last);                               |
  [ 33814, 36548 ]
  !gapprompt@gap>| !gapinput@grps{last};|
  [ <(1(5),4(5)),(0(3),1(6)),(3(4),0(6))>, 
    <(0(5),3(5)),(2(3),4(6)),(0(4),5(6))> ]
  !gapprompt@gap>| !gapinput@samegroups[1];    |
  [ 1, 2, 68 ]
  !gapprompt@gap>| !gapinput@grps[1] = grps[68];|
  true
  !gapprompt@gap>| !gapinput@Maximum(mods);|
  77760
  !gapprompt@gap>| !gapinput@Positions(mods,last);|
  [ 26311, 26313, 26452, 26453, 26455, 26456, 26457, 26459, 26461, 26462, 
    27781, 27784, 27785, 27786, 27788, 27789, 27790, 27791, 27829, 27832, 
    30523, 30524, 30525, 30526, 30529, 30530, 30532, 30534, 32924, 32927, 
    32931, 32933 ]
  !gapprompt@gap>| !gapinput@Set(sizes{last});     |
  [ 45509262704640000 ]
  !gapprompt@gap>| !gapinput@Collected(mods);|
  [ [ 0, 30446 ], [ 3, 1 ], [ 4, 37 ], [ 5, 120 ], [ 6, 1450 ], [ 8, 18 ], 
    [ 10, 45 ], [ 12, 3143 ], [ 15, 165 ], [ 18, 484 ], [ 20, 528 ], 
    [ 24, 1339 ], [ 30, 2751 ], [ 36, 2064 ], [ 40, 26 ], [ 48, 515 ], 
    [ 60, 2322 ], [ 72, 2054 ], [ 80, 44 ], [ 90, 108 ], [ 96, 108 ], 
    [ 108, 114 ], [ 120, 782 ], [ 144, 310 ], [ 160, 26 ], [ 180, 206 ], 
    [ 192, 6 ], [ 216, 72 ], [ 240, 304 ], [ 270, 228 ], [ 288, 14 ], 
    [ 360, 84 ], [ 432, 36 ], [ 480, 218 ], [ 540, 18 ], [ 720, 120 ], 
    [ 810, 112 ], [ 864, 8 ], [ 960, 94 ], [ 1080, 488 ], [ 1620, 44 ], 
    [ 1920, 38 ], [ 2160, 506 ], [ 3240, 34 ], [ 3840, 12 ], 
    [ 4320, 218 ], [ 4860, 16 ], [ 6480, 282 ], [ 7680, 10 ], 
    [ 8640, 16 ], [ 12960, 120 ], [ 14580, 2 ], [ 25920, 34 ], 
    [ 30720, 2 ], [ 38880, 12 ], [ 51840, 8 ], [ 77760, 32 ] ]
  !gapprompt@gap>| !gapinput@Collected(trsstatus);|
  [ [ "> 1 orbit (mod m)", 593 ], 
    [ "Mod(U DecreasingOn) exceeded <maxmod>", 23 ], 
    [ "U DecreasingOn stable and exceeded memory bound", 11 ], 
    [ "U DecreasingOn stable for <maxeq> steps", 5753 ], 
    [ "exceeded memory bound", 497 ], [ "finite", 21948 ], 
    [ "intransitive, but finitely many orbits", 8 ], 
    [ "seemingly only finite orbits (long)", 1227 ], 
    [ "seemingly only finite orbits (medium)", 2501 ], 
    [ "seemingly only finite orbits (short)", 4816 ], 
    [ "seemingly only finite orbits (very long)", 230 ], 
    [ "seemingly only finite orbits (very long, very unclear)", 76 ], 
    [ "seemingly only finite orbits (very short)", 208 ], 
    [ "there are infinite orbits which have exponential sphere size growth"
          , 2934 ], 
    [ "there are infinite orbits which have linear sphere size growth", 
        10881 ],
    [ "there are infinite orbits which have unclear sphere size growth", 
        86 ], [ "transitive", 562 ], 
    [ "transitive up to one finite orbit", 40 ] ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions (both databases)}}
\logpage{[ 6, 2, 2 ]}\nobreak
\hyperdef{L}{X7A77F7D57B08E4A5}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions({\mdseries\slshape max{\textunderscore}m})\index{LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions@\texttt{Load}\-\texttt{Database}\-\texttt{Of}\-\texttt{Groups}\-\texttt{Generated}\-\texttt{By3}\-\texttt{Class}\-\texttt{Transpositions}!both databases}
\label{LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions:both databases}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the name of the variable to which the record containing the database of all
groups generated by 3 class transpositions which interchange residue classes
with moduli less than or equal to \mbox{\texttt{\mdseries\slshape max{\textunderscore}m}} got bound, where \mbox{\texttt{\mdseries\slshape max{\textunderscore}m}} is either 6 or{\nobreakspace}9. 



 If \mbox{\texttt{\mdseries\slshape max{\textunderscore}m}} is 6, this is equivalent to the call of the function without argument
described above. If \mbox{\texttt{\mdseries\slshape max{\textunderscore}m}} is 9, the function returns a record with at least the following components (in
the sequel, the indices \texttt{i {\textgreater} j {\textgreater} k} are always integers in the range \texttt{[1..264]}): 
\begin{description}
\item[{\texttt{cts}}]  The list of all 264 class transpositions which interchange residue classes
with moduli $\leq 9$. 
\item[{\texttt{mods}}]  The list of moduli of the groups, i.e. \texttt{Mod(Group(cts\texttt{\symbol{123}}[i,j,k]\texttt{\symbol{125}})) =
mods[i][j][k]}. 
\item[{\texttt{partlengths}}]  The list of lengths of shortest respected partitions of the groups in the
database, i.e. \texttt{Length(RespectedPartition(Group(cts\texttt{\symbol{123}}[i,j,k]\texttt{\symbol{125}})))} \texttt{=} \texttt{partlengths[i][j][k]}. 
\item[{\texttt{sizes}}]  The list of orders of the groups, i.e. \texttt{Size(Group(cts\texttt{\symbol{123}}[i,j,k]\texttt{\symbol{125}}))} \texttt{=} \texttt{sizes[i][j][k]}. 
\item[{\texttt{All3CTs9Indices}}]  A selector function which takes as argument a function \mbox{\texttt{\mdseries\slshape func}} of three arguments \mbox{\texttt{\mdseries\slshape i}}, \mbox{\texttt{\mdseries\slshape j}} and \mbox{\texttt{\mdseries\slshape k}}. It returns a list of all triples of indices \texttt{[\mbox{\texttt{\mdseries\slshape i}},\mbox{\texttt{\mdseries\slshape j}},\mbox{\texttt{\mdseries\slshape k}}]} where $264 \geq i > j > k \geq 1$ for which \mbox{\texttt{\mdseries\slshape func}} returns \texttt{true}. 
\item[{\texttt{All3CTs9Groups}}]  A selector function which takes as argument a function \mbox{\texttt{\mdseries\slshape func}} of three arguments \mbox{\texttt{\mdseries\slshape i}}, \mbox{\texttt{\mdseries\slshape j}} and \mbox{\texttt{\mdseries\slshape k}}. It returns a list of all groups \texttt{Group(cts\texttt{\symbol{123}}[\mbox{\texttt{\mdseries\slshape i}},\mbox{\texttt{\mdseries\slshape j}},\mbox{\texttt{\mdseries\slshape k}}]\texttt{\symbol{125}})} from the database for which \texttt{\mbox{\texttt{\mdseries\slshape func}}(\mbox{\texttt{\mdseries\slshape i}},\mbox{\texttt{\mdseries\slshape j}},\mbox{\texttt{\mdseries\slshape k}})} returns \texttt{true}. 
\end{description}
 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions(9);|
  "3CTsGroups9"
  !gapprompt@gap>| !gapinput@AssignGlobals(3CTsGroups9);|
  The following global variables have been assigned:
  [ "All3CTs9Groups", "All3CTs9Indices", "cts", "mods", "partlengths", 
    "sizes" ]
  !gapprompt@gap>| !gapinput@PrintFactorsInt(Maximum(Filtered(Flat(sizes),n->n<>infinity)));|
  2^1283*3^673*5^305*7^193*11^98*13^84*17^50*19^41*23^25*29^13*31^4
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{LoadDatabaseOfGroupsGeneratedBy4ClassTranspositions}}
\logpage{[ 6, 2, 3 ]}\nobreak
\hyperdef{L}{X792C90B48692D0D7}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LoadDatabaseOfGroupsGeneratedBy4ClassTranspositions({\mdseries\slshape })\index{LoadDatabaseOfGroupsGeneratedBy4ClassTranspositions@\texttt{Load}\-\texttt{Database}\-\texttt{Of}\-\texttt{Groups}\-\texttt{Generated}\-\texttt{By4}\-\texttt{Class}\-\texttt{Transpositions}}
\label{LoadDatabaseOfGroupsGeneratedBy4ClassTranspositions}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the name of the variable to which the record containing the database of all
groups generated by 4 class transpositions which interchange residue classes
with moduli $\leq 6$ for which all subgroups generated by 3 out of the 4 generators are finite got
bound. 



 The record has at least the following components (the index \texttt{i} is always an integer in the range \texttt{[1..140947]}, and the term ``indices'' always refers to list indices in that range): 
\begin{description}
\item[{\texttt{cts}}]  The list of all 69 class transpositions which interchange residue classes with
moduli $\leq 6$. 
\item[{\texttt{grps4{\textunderscore}3finite}}]  The list of all 140947 groups in the database. 
\item[{\texttt{grps4{\textunderscore}3finitepos}}]  The list obtained from \texttt{grps4{\textunderscore}3finite} by replacing every group by the list of positions of its generators in the
list \texttt{cts}. 
\item[{\texttt{sizes4}}]  The list of group orders \texttt{\symbol{45}}\texttt{\symbol{45}} it is \texttt{Size(grps4{\textunderscore}3finite[i]) = sizes4[i]}. 
\item[{\texttt{mods4}}]  The list of moduli of the groups \texttt{\symbol{45}}\texttt{\symbol{45}} it
is \texttt{Mod(grps4{\textunderscore}3finite[i]) = mods4[i]}. 
\item[{\texttt{conjugacyclasses4cts}}]  A list of lists of indices of groups which are known to be conjugate in
RCWA({\ensuremath{\mathbb Z}}). 
\item[{\texttt{grps4{\textunderscore}3finite{\textunderscore}reps}}]  Tentative conjugacy class representatives from the list \texttt{grps4{\textunderscore}3finite} \texttt{\symbol{45}}\texttt{\symbol{45}} \emph{tentative} in the sense that likely some of the groups in the list are still conjugate. 
\end{description}
 Note that the database contains an entry for every suitable unordered
4\texttt{\symbol{45}}tuple of distinct class transpositions in \texttt{cts}, which means that it contains multiple copies of equal groups. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@LoadDatabaseOfGroupsGeneratedBy4ClassTranspositions(); |
  "4CTsGroups6"
  !gapprompt@gap>| !gapinput@AssignGlobals(4CTsGroups6);|
  The following global variables have been assigned:
  [ "conjugacyclasses4cts", "cts", "grps4_3finite", "grps4_3finite_reps", 
    "grps4_3finitepos", "mods4", "sizes4", "sizes4pos", "sizes4set" ]
  !gapprompt@gap>| !gapinput@Length(grps4_3finite);|
  140947
  !gapprompt@gap>| !gapinput@Length(sizes4);|
  140947
  !gapprompt@gap>| !gapinput@Size(grps4_3finite[1]);|
  518400
  !gapprompt@gap>| !gapinput@sizes4[1];|
  518400
  !gapprompt@gap>| !gapinput@Maximum(Filtered(sizes4,IsInt));|
  <integer 420...000 (3852 digits)>
  !gapprompt@gap>| !gapinput@Modulus(grps4_3finite[1]);|
  12
  !gapprompt@gap>| !gapinput@mods4[1];|
  12
  !gapprompt@gap>| !gapinput@Length(Set(sizes4));|
  7339
  !gapprompt@gap>| !gapinput@Length(Set(mods4));|
  91
  !gapprompt@gap>| !gapinput@conjugacyclasses4cts{[1..4]};|
  [ [ 1, 23, 563, 867 ], [ 2, 859 ], [ 3, 622 ], [ 4, 16, 868, 873 ] ]
  !gapprompt@gap>| !gapinput@grps4_3finite[1] = grps4_3finite[23];|
  true
  !gapprompt@gap>| !gapinput@grps4_3finite[4] = grps4_3finite[16];|
  false
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{Databases of rcwa mappings}}\label{sec:DatabasesOfRcwaMappings}
\logpage{[ 6, 3, 0 ]}
\hyperdef{L}{X78A1A8E587C7FFD5}{}
{
  

\subsection{\textcolor{Chapter }{LoadDatabaseOfProductsOf2ClassTranspositions}}
\logpage{[ 6, 3, 1 ]}\nobreak
\hyperdef{L}{X843E94467A1BB86C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LoadDatabaseOfProductsOf2ClassTranspositions({\mdseries\slshape })\index{LoadDatabaseOfProductsOf2ClassTranspositions@\texttt{Load}\-\texttt{Database}\-\texttt{Of}\-\texttt{Products}\-\texttt{Of2}\-\texttt{Class}\-\texttt{Transpositions}}
\label{LoadDatabaseOfProductsOf2ClassTranspositions}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the name of the variable to which the record containing the database of
products of 2 class transpositions got bound. 



 There are 69 class transpositions which interchange residue classes with
moduli $\leq 6$, thus there is a total of $(69 \cdot 68)/2 = 2346$ unordered pairs of distinct such class transpositions. Looking at
intersection\texttt{\symbol{45}} and subset relations between the 4 involved
residue classes, we can distinguish 17 different ``intersection types'' (or 18, together with the trivial case of equal class transpositions). The
intersection type does not fully determine the cycle structure of the product.
\texttt{\symbol{45}}\texttt{\symbol{45}} In total, we can distinguish 88
different cycle types of products of 2 class transpositions which interchange
residue classes with moduli $\leq 6$. 

 The components of the database record are a list \texttt{CTPairs} of all 2346 pairs of distinct class transpositions which interchange residue
classes with moduli $\leq 6$, functions \texttt{CTPairsIntersectionTypes}, \texttt{CTPairIntersectionType} and \texttt{CTPairProductType}, as well as data lists \texttt{OrdersMatrix}, \texttt{CTPairsProductClassification}, \texttt{CTPairsProductType}, \texttt{CTProds12} and \texttt{CTProds32}. \texttt{\symbol{45}}\texttt{\symbol{45}} For the description of these
components, see the file \texttt{pkg/rcwa/data/ctproducts/ctprodclass.g}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@LoadDatabaseOfProductsOf2ClassTranspositions();|
  "CTProducts"
  !gapprompt@gap>| !gapinput@Set(RecNames(CTProducts));|
  [ "CTPairIntersectionType", "CTPairProductType", "CTPairs", 
    "CTPairsIntersectionTypes", "CTPairsProductClassification", 
    "CTPairsProductType", "CTProds12", "CTProds32", "OrdersMatrix" ]
  !gapprompt@gap>| !gapinput@Length(CTProducts.CTPairs);|
  2346
  !gapprompt@gap>| !gapinput@Collected(List(CTProducts.CTPairsProductType,l->l[2])); # order stats|
  [ [ 2, 165 ], [ 3, 255 ], [ 4, 173 ], [ 6, 693 ], [ 10, 2 ], 
    [ 12, 345 ], [ 15, 4 ], [ 20, 10 ], [ 30, 120 ], [ 60, 44 ], 
    [ infinity, 535 ] ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{LoadDatabaseOfNonbalancedProductsOfClassTranspositions}}
\logpage{[ 6, 3, 2 ]}\nobreak
\hyperdef{L}{X85B492697ACC4A54}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LoadDatabaseOfNonbalancedProductsOfClassTranspositions({\mdseries\slshape })\index{LoadDatabaseOfNonbalancedProductsOfClassTranspositions@\texttt{Load}\-\texttt{Database}\-\texttt{Of}\-\texttt{Nonbalanced}\-\texttt{Products}\-\texttt{Of}\-\texttt{Class}\-\texttt{Transpositions}}
\label{LoadDatabaseOfNonbalancedProductsOfClassTranspositions}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the name of the variable to which the record containing the database of
non\texttt{\symbol{45}}balanced products of class transpositions got bound. 



 This database contains a list of the 24 pairs of class transpositions which
interchange residue classes with moduli $\leq 6$ and whose product is not balanced, as well as a list of all 36 essentially
distinct triples of such class transpositions whose product has coprime
multiplier and divisor. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@LoadDatabaseOfNonbalancedProductsOfClassTranspositions();|
  "CTProductsNB"
  !gapprompt@gap>| !gapinput@Set(RecNames(CTProductsNB));|
  [ "PairsOfCTsWhoseProductIsNotBalanced", 
    "TriplesOfCTsWhoseProductHasCoprimeMultiplierAndDivisor" ]
  !gapprompt@gap>| !gapinput@CTProductsNB.PairsOfCTsWhoseProductIsNotBalanced;|
  [ [ ( 1(2), 2(4) ), ( 2(4), 3(6) ) ], [ ( 1(2), 2(4) ), ( 2(4), 5(6) ) ], 
    [ ( 1(2), 2(4) ), ( 2(4), 1(6) ) ], [ ( 1(2), 0(4) ), ( 0(4), 1(6) ) ], 
    [ ( 1(2), 0(4) ), ( 0(4), 3(6) ) ], [ ( 1(2), 0(4) ), ( 0(4), 5(6) ) ], 
    [ ( 0(2), 1(4) ), ( 1(4), 2(6) ) ], [ ( 0(2), 1(4) ), ( 1(4), 4(6) ) ], 
    [ ( 0(2), 1(4) ), ( 1(4), 0(6) ) ], [ ( 0(2), 3(4) ), ( 3(4), 4(6) ) ], 
    [ ( 0(2), 3(4) ), ( 3(4), 2(6) ) ], [ ( 0(2), 3(4) ), ( 3(4), 0(6) ) ], 
    [ ( 1(2), 2(6) ), ( 3(4), 2(6) ) ], [ ( 1(2), 2(6) ), ( 1(4), 2(6) ) ], 
    [ ( 1(2), 4(6) ), ( 3(4), 4(6) ) ], [ ( 1(2), 4(6) ), ( 1(4), 4(6) ) ], 
    [ ( 1(2), 0(6) ), ( 1(4), 0(6) ) ], [ ( 1(2), 0(6) ), ( 3(4), 0(6) ) ], 
    [ ( 0(2), 1(6) ), ( 2(4), 1(6) ) ], [ ( 0(2), 1(6) ), ( 0(4), 1(6) ) ], 
    [ ( 0(2), 3(6) ), ( 2(4), 3(6) ) ], [ ( 0(2), 3(6) ), ( 0(4), 3(6) ) ], 
    [ ( 0(2), 5(6) ), ( 2(4), 5(6) ) ], [ ( 0(2), 5(6) ), ( 0(4), 5(6) ) ] 
   ]
  
\end{Verbatim}
 }

 }

  }

       
\chapter{\textcolor{Chapter }{Examples}}\label{ch:Examples}
\logpage{[ 7, 0, 0 ]}
\hyperdef{L}{X7A489A5D79DA9E5C}{}
{
  This chapter discusses a number of examples of rcwa mappings and
\texttt{\symbol{45}}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 difficulty or interest. 

 \index{LoadRCWAExamples@\texttt{LoadRCWAExamples}} \index{AssignGlobals@\texttt{AssignGlobals}} The rcwa mappings, rcwa groups and other objects defined in this chapter can
be found in the file \texttt{pkg/rcwa/examples/examples.g}. This file can be read into the current \textsf{GAP} session by the function \texttt{LoadRCWAExamples} (\ref{LoadRCWAExamples}) which takes no arguments and returns the name of a variable which the record
containing the examples got assigned to. The global variable assignments made
in a section of this chapter can be made by applying the function \texttt{AssignGlobals} to the respective component of the examples record. The component names are
given at the end of the corresponding sections. 

 The discussions of the examples are typically far from being exhaustive. 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
\texttt{\symbol{45}}\texttt{\symbol{45}} have fun!  
\section{\textcolor{Chapter }{ Thompson's group V }}\label{sec:ThompsonsGroupV}
\logpage{[ 7, 1, 0 ]}
\hyperdef{L}{X84A058CF7C65A908}{}
{
  Thompson's group V, also known as Higman\texttt{\symbol{45}}Thompson group, is
a finitely presented infinite simple group. This group has been found by
Graham Higman, cf.{\nobreakspace}\cite{Higman74}. We show that the group 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group(List([[0,2,1,4],[0,4,1,4],[1,4,2,4],[2,4,3,4]],|
  !gapprompt@>| !gapinput@                   ClassTransposition));|
  <(0(2),1(4)),(0(4),1(4)),(1(4),2(4)),(2(4),3(4))>
  
\end{Verbatim}
 is isomorphic to Thompson's group V. This isomorphism has been pointed out by
John P. McDermott. We take a slightly different set of generators: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@k := ClassTransposition(0,2,1,2);;|
  !gapprompt@gap>| !gapinput@l := ClassTransposition(1,2,2,4);;|
  !gapprompt@gap>| !gapinput@m := ClassTransposition(0,2,1,4);;|
  !gapprompt@gap>| !gapinput@n := ClassTransposition(1,4,2,4);;|
  !gapprompt@gap>| !gapinput@H := Group(k,l,m,n);|
  <(0(2),1(2)),(1(2),2(4)),(0(2),1(4)),(1(4),2(4))>
  !gapprompt@gap>| !gapinput@G = H; # k, l, m and n generate G as well|
  true
  
\end{Verbatim}
 Now we verify that our four generators satisfy the relations given on
page{\nobreakspace}50 in{\nobreakspace}\cite{Higman74}, when we read \texttt{k} as{\nobreakspace}$\kappa$, \texttt{l} as{\nobreakspace}$\lambda$, \texttt{m} as{\nobreakspace}$\mu$ and \texttt{n} as{\nobreakspace}$\nu$: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@HigmanThompsonRels :=|
  !gapprompt@>| !gapinput@[ k^2, l^2, m^2, n^2,                           # (1) in Higman's book|
  !gapprompt@>| !gapinput@  l*k*m*k*l*n*k*n*m*k*l*k*m,                    # (2)        "|
  !gapprompt@>| !gapinput@  k*n*l*k*m*n*k*l*n*m*n*l*n*m,                  # (3)        "|
  !gapprompt@>| !gapinput@  (l*k*m*k*l*n)^3, (m*k*l*k*m*n)^3,             # (4)        "|
  !gapprompt@>| !gapinput@  (l*n*m)^2*k*(m*n*l)^2*k,                      # (5)        "|
  !gapprompt@>| !gapinput@  (l*n*m*n)^5,                                  # (6)        "|
  !gapprompt@>| !gapinput@  (l*k*n*k*l*n)^3*k*n*k*(m*k*n*k*m*n)^3*k*n*k*n,# (7)        "|
  !gapprompt@>| !gapinput@  ((l*k*m*n)^2*(m*k*l*n)^2)^3,                  # (8)        "|
  !gapprompt@>| !gapinput@  (l*n*l*k*m*k*m*n*l*n*m*k*m*k)^4,              # (9)        "|
  !gapprompt@>| !gapinput@  (m*n*m*k*l*k*l*n*m*n*l*k*l*k)^4,              #(10)        "|
  !gapprompt@>| !gapinput@  (l*m*k*l*k*m*l*k*n*k)^2,                      #(11)        "|
  !gapprompt@>| !gapinput@  (m*l*k*m*k*l*m*k*n*k)^2 ];                    #(12)        "|
  [ IdentityMapping( Integers ), IdentityMapping( Integers ), 
    IdentityMapping( Integers ), IdentityMapping( Integers ), 
    IdentityMapping( Integers ), IdentityMapping( Integers ), 
    IdentityMapping( Integers ), IdentityMapping( Integers ), 
    IdentityMapping( Integers ), IdentityMapping( Integers ), 
    IdentityMapping( Integers ), IdentityMapping( Integers ), 
    IdentityMapping( Integers ), IdentityMapping( Integers ), 
    IdentityMapping( Integers ), IdentityMapping( Integers ) ]
  
\end{Verbatim}
 We conclude that our group is an homomorphic image of Thompson's group V. But
since Thompson's group V is simple and our group is not trivial, this means
indeed that the two groups are isomorphic. 

 In fact it is straightforward to show that \texttt{G} is the group \texttt{CT([2],Integers)} which is generated by the set of all class transpositions which interchange
residue classes modulo powers of{\nobreakspace}2. First we check that \texttt{G} contains all 11 class transpositions which interchange residue classes modulo
2 or{\nobreakspace}4: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@S := Filtered(List(ClassPairs(4),ClassTransposition),|
  !gapprompt@>| !gapinput@                 ct->Mod(ct) in [2,4]);|
  [ ( 0(2), 1(2) ), ( 0(2), 1(4) ), ( 0(2), 3(4) ), ( 0(4), 1(4) ), 
    ( 0(4), 2(4) ), ( 0(4), 3(4) ), ( 1(2), 0(4) ), ( 1(2), 2(4) ), 
    ( 1(4), 2(4) ), ( 1(4), 3(4) ), ( 2(4), 3(4) ) ]
  !gapprompt@gap>| !gapinput@IsSubset(G,S);|
  true
  
\end{Verbatim}
 Then we give a function which takes a class transposition $\tau \in {\rm CT}_\emptyset({\ensuremath{\mathbb Z}})$, and which returns a factorization of an element $\gamma$ satisfying $\tau^\gamma \in S$ into $g_1 := \tau_{0(2),1(4)} \in S$, $g_2 := \tau_{0(2),3(4)} \in S$, $g_3 := \tau_{1(2),0(4)} \in S$, $g_4 := \tau_{1(2),2(4)} \in S$, $h_1 := \tau_{0(4),1(4)} \in S$ and $h_2 := \tau_{1(4),2(4)} \in S$: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=GAP code]
  
  ReducingConjugator := function ( tau )
  
    local  w, F, g1, g2, g3, g4, h1, h2, h, cls, cl, r;
  
    g1 := ClassTransposition(0,2,1,4); h1 := ClassTransposition(0,4,1,4);
    g2 := ClassTransposition(0,2,3,4); h2 := ClassTransposition(1,4,2,4);
    g3 := ClassTransposition(1,2,0,4);
    g4 := ClassTransposition(1,2,2,4);
  
    F := FreeGroup("g1","g2","g3","g4","h1","h2");
  
    w := One(F); if Mod(tau) <= 4 then return w; fi;
  
    # Before we can reduce the moduli of the interchanged residue classes,
    # we must make sure that both of them have at least modulus 4.
    cls := TransposedClasses(tau);
    if Mod(cls[1]) = 2 then
      if Residue(cls[1]) = 0 then
        if Residue(cls[2]) mod 4 = 1 then tau := tau^g2; w := w * F.2;
                                     else tau := tau^g1; w := w * F.1; fi;
      else
        if Residue(cls[2]) mod 4 = 0 then tau := tau^g4; w := w * F.4;
                                     else tau := tau^g3; w := w * F.3; fi;
      fi;
    fi;
  
    while Mod(tau) > 4 do # Now we can successively reduce the moduli.
      if not ForAny(AllResidueClassesModulo(2),
                    cl -> IsEmpty(Intersection(cl,Support(tau))))
      then
        cls := TransposedClasses(tau);
        h := Filtered([h1,h2],
               hi->Length(Filtered(cls,cl->IsSubset(Support(hi),cl)))=1);
        h := h[1]; tau := tau^h;
        if h = h1 then w := w * F.5; else w := w * F.6; fi;
      fi;
      cl := TransposedClasses(tau)[2]; # class with larger modulus
      r  := Residue(cl);
      if   r mod 4 = 1 then tau := tau^g1; w := w * F.1;
      elif r mod 4 = 3 then tau := tau^g2; w := w * F.2;
      elif r mod 4 = 0 then tau := tau^g3; w := w * F.3;
      elif r mod 4 = 2 then tau := tau^g4; w := w * F.4; fi;
    od;
  
    return w;
  end;
  
\end{Verbatim}
 After assigning \texttt{g1}, \texttt{g2}, \texttt{g3}, \texttt{g4}, \texttt{h1} and{\nobreakspace}\texttt{h2} appropriately, we obtain for example: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ReducingConjugator(ClassTransposition(3,16,34,256));|
  h2*g1*h1*g1*h1*g1*h1*g1*h2*g2*h2*g4*h2*g4*h2*g3
  !gapprompt@gap>| !gapinput@gamma := h2*g1*h1*g1*h1*g1*h1*g1*h2*g2*h2*g4*h2*g4*h2*g3;|
  <rcwa permutation of Z with modulus 256>
  !gapprompt@gap>| !gapinput@ct := ClassTransposition(3,16,34,256)^gamma;;|
  !gapprompt@gap>| !gapinput@IsClassTransposition(ct);;|
  !gapprompt@gap>| !gapinput@ct;|
  ClassTransposition(1,4,2,4)
  
\end{Verbatim}
 Thompson's group V can also be embedded in a natural way into CT(GF(2)[x]): 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@x := Indeterminate(GF(2));; SetName(x,"x");|
  !gapprompt@gap>| !gapinput@R := PolynomialRing(GF(2),1);;|
  !gapprompt@gap>| !gapinput@k := ClassTransposition(0,x,1,x);;|
  !gapprompt@gap>| !gapinput@l := ClassTransposition(1,x,x,x^2);;|
  !gapprompt@gap>| !gapinput@m := ClassTransposition(0,x,1,x^2);;|
  !gapprompt@gap>| !gapinput@n := ClassTransposition(1,x^2,x,x^2);;|
  !gapprompt@gap>| !gapinput@G := Group(k,l,m,n);|
  <rcwa group over GF(2)[x] with 4 generators>
  
\end{Verbatim}
 The correctness of this representation can likewise be verified by simply
checking the defining relations given above. 

 Enter \texttt{AssignGlobals(LoadRCWAExamples().HigmanThompson);} in order to assign the global variables defined in this section. }

  
\section{\textcolor{Chapter }{ Factoring Collatz' permutation of the integers }}\label{sec:FactoringTheCollatzPermutation}
\logpage{[ 7, 2, 0 ]}
\hyperdef{L}{X86C2BAE3876985A6}{}
{
  In 1932, Lothar Collatz mentioned in his notebook the following permutation of
the integers: 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@Collatz := RcwaMapping([[2,0,3],[4,-1,3],[4,1,3]]);;A
  !gapprompt@gap>A !gapinput@Display(Collatz);A
  
  Rcwa mapping of Z with modulus 3
  
          /
          | 2n/3     if n in 0(3)
   n |-> <  (4n-1)/3 if n in 1(3)
          | (4n+1)/3 if n in 2(3)
          java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@ShortCycles(Collatz,[-50..50],50); # There are some finite cycles:A
  [ [ 0 ], [ -1 ], [ 1 ], [ 2, 3 ], [ -2, -3 ], [ 4, 5, 7, 9, 6 ], 
    [ -4, -5, -7, -9, -6 ], 
    [ 44, 59, 79, 105, 70, 93, 62, 83, 111, 74, 99, 66 ], 
    [ -44, -59, -79, -105, -70, -93, -62, -83, -111, -74, -99, -66 ] ]
  
\end{Verbatim}
 The cycle structure of Collatz' permutation has not been completely determined
yet. In particular it is not known whether the cycle
containing{\nobreakspace}8 is finite or infinite. Nevertheless, the
factorization routine included in this package can determine a factorization
of this permutation into class transpositions, i.e. involutions interchanging
two disjoint residue classes: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Collatz in CT(Integers);  # `Collatz' lies in the simple group CT(Z).|
  true
  !gapprompt@gap>| !gapinput@Length(Factorization(Collatz));|
  212
  
\end{Verbatim}
 Setting the Info level of \texttt{InfoRCWA} equal to{\nobreakspace}2 (simply issue \texttt{RCWAInfo(2);}) causes the factorization routine to display detailed information on the
progress of the factoring process. For reasons of saving space, this is not
done in this manual. 

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

 Enter \texttt{AssignGlobals(LoadRCWAExamples().CollatzlikePerms);} in order to assign the global variables defined in this section. }

  
\section{\textcolor{Chapter }{ The $3n+1$ group }}\label{sec:3nplus1Group}
\logpage{[ 7, 3, 0 ]}
\hyperdef{L}{X811919107D5DAAC1}{}
{
  The following group acts transitively on the set of positive integers for
which the $3n+1$ conjecture holds and which are not divisible by 6: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@a := ClassTransposition(1,2,4,6);;|
  !gapprompt@gap>| !gapinput@b := ClassTransposition(1,3,2,6);;|
  !gapprompt@gap>| !gapinput@c := ClassTransposition(2,3,4,6);;|
  !gapprompt@gap>| !gapinput@G := Group(a,b,c);|
  <(1(2),4(6)),(1(3),2(6)),(2(3),4(6))>
  !gapprompt@gap>| !gapinput@LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions();|
  "3CTsGroups6"
  !gapprompt@gap>| !gapinput@3CTsGroups6.Id3CTsGroup(G,3CTsGroups6.grps); # 'catalogue number' of G|
  44132
  
\end{Verbatim}
 To see this, consider the action of $G$ on the ``$3n+1$ tree''. The vertices of this tree are the positive integers for which the $3n+1$ conjecture holds, and for every vertex $n$ there is an edge from $n$ to $T(n)$, where $T$ denotes the Collatz mapping 
  
\[
  T: \ \ \mathbb{Z} \longrightarrow \mathbb{Z}, \ \ \ java.lang.NullPointerException
    n \ \longmapsto java.lang.NullPointerException
    \begin{cases}
      \frac{n}{2}    & \text{if} \ \ n \ \ \text{is even}, \\
      \frac{3n+1}{2} & \text{if} \ \ n \ \ \text{is odd}
    \end{cases}
  \]

   (cf. Chapter{\nobreakspace}\ref{ch:AboutRCWA}). It is easy to check that for every vertex $n$, either $a$, $b$ or $c$ maps $n$ to $T(n)$, and that the other two generators either fix $n$ or map it to one of its preimages under{\nobreakspace}$T$. So the $3n+1$ conjecture is equivalent to the assertion that the group $G$ acts transitively on $\mathbb{N} \setminus 0(6)$. First let's have a look at balls of small radius about 1 under the action of $G$ \texttt{\symbol{45}}\texttt{\symbol{45}} these consist of those numbers whose
trajectory under $T$ reaches 1 quickly: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Ball(G,1,5,OnPoints);|
  [ 1, 2, 4, 5, 8, 10, 16, 32, 64 ]
  !gapprompt@gap>| !gapinput@Ball(G,1,10,OnPoints);|
  [ 1, 2, 3, 4, 5, 8, 10, 13, 16, 20, 21, 26, 32, 40, 52, 53, 64, 80, 85, 
    128, 160, 170, 256, 320, 340, 341, 512, 1024, 2048 ]
  !gapprompt@gap>| !gapinput@Ball(G,1,15,OnPoints);|
  [ 1, 2, 3, 4, 5, 7, 8, 10, 11, 13, 16, 17, 20, 21, 22, 23, 26, 32, 34, 
    35, 40, 44, 45, 46, 52, 53, 64, 68, 69, 70, 75, 80, 85, 104, 106, 113, 
    128, 136, 140, 141, 151, 160, 170, 208, 212, 213, 226, 227, 256, 272, 
    277, 280, 301, 302, 320, 340, 341, 416, 424, 452, 453, 454, 512, 640, 
    680, 682, 832, 848, 853, 904, 908, 909, 1024, 1280, 1360, 1364, 1365, 
    1664, 1696, 1706, 1808, 1813, 1816, 2048, 2560, 2720, 2728, 4096, 
    5120, 5440, 5456, 5461, 8192, 10240, 10880, 10912, 10922, 16384, 
    32768, 65536 ]
  !gapprompt@gap>| !gapinput@Ball(G,1,15,OnPoints:Spheres);|
  [ [ 1 ], [ 2, 4 ], [ 8 ], [ 16 ], [ 5, 32 ], [ 10, 64 ], 
    [ 3, 20, 21, 128 ], [ 40, 256 ], [ 13, 80, 85, 512 ], 
    [ 26, 160, 170, 1024 ], [ 52, 53, 320, 340, 341, 2048 ], 
    [ 17, 104, 106, 113, 640, 680, 682, 4096 ], 
    [ 34, 35, 208, 212, 213, 226, 227, 1280, 1360, 1364, 1365, 8192 ], 
    [ 11, 68, 69, 70, 75, 416, 424, 452, 453, 454, 2560, 2720, 2728, 16384 
       ], 
    [ 22, 23, 136, 140, 141, 151, 832, 848, 853, 904, 908, 909, 5120, 
        5440, 5456, 5461, 32768 ], 
    [ 7, 44, 45, 46, 272, 277, 280, 301, 302, 1664, 1696, 1706, 1808, 
        1813, 1816, 10240, 10880, 10912, 10922, 65536 ] ]
  !gapprompt@gap>| !gapinput@List(Ball(G,1,50,OnPoints:Spheres),Length);|
  [ 1, 2, 1, 1, 2, 2, 4, 2, 4, 4, 6, 8, 12, 14, 17, 20, 26, 32, 43, 52, 
    66, 81, 104, 133, 170, 211, 271, 335, 424, 542, 686, 873, 1096, 1376, 
    1730, 2205, 2794, 3522, 4429, 5611, 7100, 8978, 11343, 14296, 18058, 
    22828, 28924, 36532, 46146, 58399, 73713 ]
  !gapprompt@gap>| !gapinput@FloatQuotientsList(last);|
  [ 2., 0.5, 1., 2., 1., 2., 0.5, 2., 1., 1.5, 1.33333, 1.5, 1.16667, 
    1.21429, 1.17647, 1.3, 1.23077, 1.34375, 1.2093, 1.26923, 1.22727, 
    1.28395, 1.27885, 1.2782, 1.24118, 1.28436, 1.23616, 1.26567, 1.2783, 
    1.26568, 1.27259, 1.25544, 1.25547, 1.25727, 1.27457, 1.26712, 
    1.26056, 1.25752, 1.26688, 1.26537, 1.26451, 1.26342, 1.26034, 
    1.26315, 1.26415, 1.26704, 1.26303, 1.26317, 1.26553, 1.26223 ]
  !gapprompt@gap>| !gapinput@Difference(Filtered([1..100],n->n mod 6 <> 0),Ball(G,1,40,OnPoints));|
  [ 27, 31, 41, 47, 55, 62, 63, 71, 73, 82, 83, 91, 94, 95, 97 ]
  !gapprompt@gap>| !gapinput@T := RcwaMapping([[1,0,2],[3,1,2]]);;|
  !gapprompt@gap>| !gapinput@List(last2,n->Length(Trajectory(T,n,[1])));|
  [ 71, 68, 70, 67, 72, 69, 69, 66, 74, 71, 71, 60, 68, 68, 76 ]
  
\end{Verbatim}
 It is convenient to define an epimorphism from the free group of rank 3 to $G$: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@F := FreeGroup("a","b","c");|
  <free group on the generators [ a, b, c ]>
  !gapprompt@gap>| !gapinput@phi := EpimorphismByGenerators(F,G);|
  [ a, b, c ] -> [ ( 1(2), 4(6) ), ( 1(3), 2(6) ), ( 2(3), 4(6) ) ]
  
\end{Verbatim}
 We can compute balls about 1 in $G$: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@B := Ball(G,One(G),7:Spheres);;|
  !gapprompt@gap>| !gapinput@List(B,Length);|
  [ 1, 3, 6, 12, 24, 48, 96, 192 ]
  !gapprompt@gap>| !gapinput@List(B[3],Order);|
  [ 12, infinity, infinity, infinity, infinity, 12 ]
  !gapprompt@gap>| !gapinput@List(B[3],g->PreImagesRepresentative(phi,g));|
  [ b*a, c*b, c*a, b*c, a*c, a*b ]
  !gapprompt@gap>| !gapinput@g := a*b;; Order(g);;|
  !gapprompt@gap>| !gapinput@Display(g);|
  
  Rcwa permutation of Z with modulus 18, of order 12
  
  ( 1(6), 8(36), 4(18), 2(12) ) ( 3(6), 20(36), 10(18) )
  ( 5(6), 32(36), 16(18) )
  
  
\end{Verbatim}
 Spending some more time to compute \texttt{B := Ball(G,One(G),12:Spheres);;}, one can check that $(ab)^{12}$ is the shortest word in the generators of $G$ which does not represent the identity in the free product of 3 cyclic groups
of order 2, but which represents the identity in $G$. However, the group $G$ has elements of other finite orders as well
\texttt{\symbol{45}}\texttt{\symbol{45}} for example: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@g := (b*a)^3*b*c;; Order(g);;|
  !gapprompt@gap>| !gapinput@Display(g);|
  
  Rcwa permutation of Z with modulus 36, of order 105
  
  ( 8(9), 16(18), 64(72), 256(288), 85(96), 128(144), 32(36) )
  ( 7(12), 11(18), 22(36) ) ( 5(18), 10(36), 40(144), 13(48), 
    20(72) ) ( 1(24), 2(36), 4(72) ) ( 14(36), 28(72), 112(288), 
    37(96), 56(144) )
  
  !gapprompt@gap>| !gapinput@Order(a*c*b*a*b*c*a*c);|
  60
  
\end{Verbatim}
 With some more efforts, one finds that e.g. $(abc)^2c^b$ has order 616, that $(abc)^2b$ has order 2310, that $(ab)^2a^ca^bc$ has order 27720, and that $a(c(ab)^2)^2$ has order 65520. Of course $G$ has many elements of infinite order as well. Some of them have infinite
cycles, like e.g. 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@g := b*c;;A
  !gapprompt@gap>A !gapinput@Display(g);A
  
  Rcwa permutation of Z with modulus 12
  
          /
          | 4n  if n in 1(3)
          | 2n  if n in 5(6)
   n |-> <  n/2 if n in 2(12)
          | n/4 if n in 8(12)
          | n   if n in 0(3)
          java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@Sinks(g);A
  [ 4(12) ]
  !gapprompt@gap>A !gapinput@Trajectory(g,last[1],10);A
  [ 4(12), 16(48), 64(192), 256(768), 1024(3072), 4096(12288), 
    16384(49152), 65536(196608), 262144(786432), 1048576(3145728) ]
  !gapprompt@gap>A !gapinput@Trajectory(g,4,20);A
  [ 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304, 
    16777216, 67108864, 268435456, 1073741824, 4294967296, 17179869184, 
    68719476736, 274877906944, 1099511627776 ]
  
\end{Verbatim}
 Others seem to have only finite cycles. Some of these appear to have ``on average'' comparatively ``short'' cycles, like e.g. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@g := a*b*a*c*b*c;|
  <rcwa permutation of Z with modulus 144>
  !gapprompt@gap>| !gapinput@cycs := ShortCycles(g,[0..10000],100,10^20);;|
  !gapprompt@gap>| !gapinput@Difference([0..10000],Union(cycs));|
  [  ]
  !gapprompt@gap>| !gapinput@Collected(List(cycs,Length));|
  [ [ 1, 2222 ], [ 3, 1945 ], [ 4, 1111 ], [ 5, 93 ], [ 6, 926 ], 
    [ 7, 31 ], [ 8, 864 ], [ 9, 10 ], [ 10, 289 ], [ 11, 4 ], [ 12, 95 ], 
    [ 13, 1 ], [ 14, 31 ], [ 16, 12 ], [ 18, 4 ], [ 20, 1 ] ]
  
\end{Verbatim}
 If the cycle of $g$ containing some $n \in {\ensuremath{\mathbb Z}}$ is finite and has a certain length $l$, then there is some $m \in {\ensuremath{\mathbb Z}}$ such that for every $k \in {\ensuremath{\mathbb Z}}$ the cycle of $g$ containing $n + km$ has length $l$ as well. Thus, in other words, every finite cycle of $g$ ``belongs to'' a cycle of residue classes. (This is a special property of $g$ which is not shared by every rcwa permutation
\texttt{\symbol{45}}\texttt{\symbol{45}} cf. e.g. Collatz' permutation from
Section{\nobreakspace}\ref{sec:FactoringTheCollatzPermutation}.) We can find some of these infinitely many ``residue class cycles'': 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@cycsrc := ShortResidueClassCycles(g,Mod(g),20);|
  [ [ 0(6) ], [ 3(6), 160(288), 20(36) ], 
    [ 7(18), 352(864), 44(108), 28(72) ], 
    [ 11(18), 544(864), 2896(4608), 362(576), 68(108), 88(144) ], 
    [ 13(18), 640(864), 80(108), 52(72) ], [ 10(36) ], [ 34(36) ], 
    [ 1(54), 64(2592), 8(324), 4(216), 16(1152), 2(144) ], 
    [ 5(54), 256(2592), 1360(13824), 170(1728), 32(324), 40(432), 
        208(2304), 26(288) ], 
    [ 17(54), 832(2592), 4432(13824), 23632(73728), 2954(9216), 554(1728), 
        104(324), 136(432) ], 
    [ 37(54), 1792(2592), 224(324), 148(216), 784(1152), 98(144) ], 
    [ 41(54), 1984(2592), 10576(13824), 1322(1728), 248(324), 328(432), 
        1744(2304), 218(288) ], 
    [ 53(54), 2560(2592), 13648(13824), 72784(73728), 9098(9216), 
        1706(1728), 320(324), 424(432) ], [ 38(72), 58(108), 304(576) ], 
    [ 62(72), 94(108), 496(576) ] ]
  !gapprompt@gap>| !gapinput@List(cycsrc,Length);|
  [ 1, 3, 4, 6, 4, 1, 1, 6, 8, 8, 6, 8, 8, 3, 3 ]
  !gapprompt@gap>| !gapinput@Sum(List(Flat(cycsrc),cl->1/Mod(cl)));|
  97459/110592
  !gapprompt@gap>| !gapinput@Float(last); # about 88% 'coverage'|
  0.881248
  !gapprompt@gap>| !gapinput@cycsrc := ShortResidueClassCycles(g,3*Mod(g),20);|
  [ [ 0(6) ], [ 3(6), 160(288), 20(36) ], 
    [ 7(18), 352(864), 44(108), 28(72) ], 
    [ 11(18), 544(864), 2896(4608), 362(576), 68(108), 88(144) ], 
    [ 13(18), 640(864), 80(108), 52(72) ], [ 10(36) ], [ 34(36) ], 
    [ 1(54), 64(2592), 8(324), 4(216), 16(1152), 2(144) ], 
    [ 5(54), 256(2592), 1360(13824), 170(1728), 32(324), 40(432), 
        208(2304), 26(288) ], 
    [ 17(54), 832(2592), 4432(13824), 23632(73728), 2954(9216), 554(1728), 
        104(324), 136(432) ], 
    [ 37(54), 1792(2592), 224(324), 148(216), 784(1152), 98(144) ], 
    [ 41(54), 1984(2592), 10576(13824), 1322(1728), 248(324), 328(432), 
        1744(2304), 218(288) ], 
    [ 53(54), 2560(2592), 13648(13824), 72784(73728), 9098(9216), 
        1706(1728), 320(324), 424(432) ], [ 38(72), 58(108), 304(576) ], 
    [ 62(72), 94(108), 496(576) ], 
    [ 23(162), 1120(7776), 5968(41472), 746(5184), 140(972), 184(1296), 
        976(6912), 5200(36864), 650(4608), 122(864) ], 
    [ 35(162), 1696(7776), 9040(41472), 48208(221184), 257104(1179648), 
        32138(147456), 6026(27648), 1130(5184), 212(972), 280(1296) ], 
    [ 73(162), 3520(7776), 440(972), 292(648), 1552(3456), 8272(18432), 
        1034(2304), 194(432) ], 
    [ 77(162), 3712(7776), 19792(41472), 2474(5184), 464(972), 616(1296), 
        3280(6912), 17488(36864), 2186(4608), 410(864) ], 
    [ 89(162), 4288(7776), 22864(41472), 121936(221184), 650320(1179648), 
        81290(147456), 15242(27648), 2858(5184), 536(972), 712(1296) ], 
    [ 127(162), 6112(7776), 764(972), 508(648), 2704(3456), 14416(18432), 
        1802(2304), 338(432) ], 
    [ 14(216), 22(324), 112(1728), 592(9216), 74(1152) ], 
    [ 86(216), 130(324), 688(1728), 3664(9216), 458(1152) ] ]
  !gapprompt@gap>| !gapinput@List(cycsrc,Length);|
  [ 1, 3, 4, 6, 4, 1, 1, 6, 8, 8, 6, 8, 8, 3, 3, 10, 10, 8, 10, 10, 8, 5, 
    5 ]
  !gapprompt@gap>| !gapinput@Sum(List(Flat(cycsrc),Density));|
  5097073/5308416
  !gapprompt@gap>| !gapinput@Float(last); # already about 96% 'coverage'|
  0.960187
  
\end{Verbatim}
 There are also some elements of infinite order whose cycles seem to be all
finite, but ``on average'' pretty ``long'' \texttt{\symbol{45}}\texttt{\symbol{45}} e.g. 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@g := (b*a*c)^2*a;;A
  !gapprompt@gap>A !gapinput@Display(g);A
  
  Rcwa permutation of Z with modulus 288
  
          /
          | (16n-1)/3   if n in 1(3)
          | (9n+5)/4    if n in 3(24) U 11(24)
          | (27n+19)/4  if n in 15(24) U 23(24)
          | (3n+1)/4    if n in 5(24)
          | (n-3)/6     if n in 21(24)
          | (27n+29)/8  if n in 9(48) U 41(48)
          | (9n+7)/8    if n in 17(48) U 33(48)
          | (2n-7)/9    if n in 8(36)
   n |-> <  (4n-11)/9   if n in 32(36)
          | (27n+38)/8  if n in 14(48)
          | (3n+2)/8    if n in 26(48)
          | (9n+10)/8   if n in 38(48)
          | (3n+4)/4    if n in 20(72)
          | n/4         if n in 56(72)
          | (9n+14)/16  if n in 2(96)
          | (27n+58)/16 if n in 50(96)
          | n           if n in 0(6)
          java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@List([1..100],n->Length(Cycle(g,n)));A
  [ 6, 1, 6, 6, 6, 1, 194, 6, 216, 26, 26, 1, 26, 194, 65, 26, 26, 1, 216, 
    26, 6, 216, 46, 1, 640, 26, 70, 194, 216, 1, 70, 26, 216, 216, 26, 1, 
    194, 216, 73, 26, 110, 1, 194, 216, 194, 111, 39, 1, 194, 640, 640, 
    194, 26, 1, 171, 194, 204, 640, 216, 1, 111, 70, 91, 26, 194, 1, 216, 
    216, 26, 111, 65, 1, 50, 194, 26, 216, 640, 1, 502, 26, 111, 40, 110, 
    1, 26, 194, 385, 640, 88, 1, 100, 111, 65, 110, 416, 1, 171, 194, 194, 
    640 ]
  !gapprompt@gap>A !gapinput@Length(Cycle(g,25));A
  640
  !gapprompt@gap>A !gapinput@Maximum(Cycle(g,25));A
  323270249684063829
  !gapprompt@gap>A !gapinput@Length(Cycle(g,25855));A
  4751
  !gapprompt@gap>A !gapinput@Maximum(Cycle(g,25855));A
  507359605810239426786254778159924369135184044618585904603866210104085
  !gapprompt@gap>A !gapinput@cycs := ShortCycles(g,[0..50000],10000,10^100);;A
  !gapprompt@gap>A !gapinput@S := [0..50000];;A
  !gapprompt@gap>A !gapinput@for cyc in cycs do S := Difference(S,cyc); od;A
  !gapprompt@gap>A !gapinput@S; # no cycle containing some n in [0..50000] has length > 10000 A
  [  ]
  
\end{Verbatim}
 Taking a look at the lengths of the trajectories of the Collatz mapping $T$ starting at the points in a cycle, we can see how a cycle of $g$ goes ``up and down'' in the $3n+1$ tree: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@List(Cycle(g,25),n->Length(Trajectory(T,n,[1])));|
  [ 17, 21, 25, 29, 33, 31, 35, 34, 32, 33, 37, 41, 45, 44, 42, 39, 43, 
    41, 45, 44, 42, 43, 40, 38, 35, 39, 37, 41, 40, 44, 48, 46, 50, 49, 
    47, 48, 45, 42, 46, 44, 48, 47, 45, 46, 50, 49, 47, 43, 41, 38, 39, 
    36, 34, 30, 27, 31, 29, 33, 32, 30, 31, 35, 33, 37, 36, 40, 39, 43, 
    41, 45, 44, 42, 43, 47, 51, 55, 53, 57, 56, 54, 55, 59, 58, 62, 66, 
    64, 68, 67, 65, 66, 63, 60, 64, 62, 66, 65, 63, 64, 68, 67, 65, 61, 
    59, 56, 52, 49, 53, 51, 55, 54, 52, 53, 57, 55, 59, 58, 56, 57, 54, 
    50, 48, 45, 49, 47, 51, 50, 54, 52, 56, 55, 53, 54, 58, 62, 66, 70, 
    74, 72, 76, 75, 79, 83, 87, 91, 90, 94, 93, 97, 95, 99, 98, 96, 97, 
    94, 91, 88, 85, 89, 87, 91, 90, 88, 89, 86, 84, 81, 85, 83, 87, 86, 
    90, 94, 98, 97, 101, 105, 109, 107, 111, 110, 108, 109, 113, 117, 115, 
    119, 118, 122, 126, 125, 123, 120, 124, 122, 126, 125, 123, 124, 121, 
    119, 116, 117, 114, 111, 115, 113, 117, 116, 114, 115, 119, 123, 122, 
    120, 117, 121, 119, 123, 122, 120, 121, 118, 116, 112, 110, 106, 103, 
    107, 105, 109, 108, 106, 107, 111, 109, 113, 112, 116, 114, 118, 117, 
    115, 116, 113, 110, 111, 108, 104, 102, 99, 103, 101, 105, 104, 108, 
    106, 110, 109, 107, 108, 112, 111, 109, 105, 102, 103, 100, 98, 95, 
    92, 96, 94, 98, 97, 95, 96, 93, 91, 88, 92, 90, 94, 93, 97, 101, 105, 
    109, 108, 106, 103, 107, 105, 109, 108, 106, 107, 104, 102, 99, 103, 
    101, 105, 104, 108, 112, 110, 114, 113, 111, 112, 116, 115, 113, 109, 
    106, 110, 108, 112, 111, 109, 110, 114, 112, 116, 115, 113, 114, 111, 
    107, 105, 102, 103, 100, 98, 95, 99, 97, 101, 100, 104, 103, 107, 105, 
    109, 108, 106, 107, 104, 101, 98, 99, 96, 94, 91, 92, 89, 87, 84, 85, 
    82, 80, 77, 81, 79, 83, 82, 86, 85, 89, 88, 86, 83, 80, 81, 78, 76, 
    73, 74, 71, 68, 72, 70, 74, 73, 71, 72, 76, 80, 79, 83, 87, 91, 90, 
    88, 85, 89, 87, 91, 90, 88, 89, 86, 84, 81, 85, 83, 87, 86, 90, 94, 
    92, 96, 95, 93, 94, 98, 96, 100, 99, 97, 98, 102, 106, 110, 114, 113, 
    111, 108, 112, 110, 114, 113, 111, 112, 109, 107, 104, 108, 106, 110, 
    109, 113, 117, 115, 119, 118, 116, 117, 114, 111, 115, 113, 117, 116, 
    114, 115, 119, 118, 116, 112, 110, 107, 108, 105, 103, 100, 104, 102, 
    106, 105, 109, 108, 112, 110, 114, 113, 111, 112, 116, 115, 113, 109, 
    106, 103, 104, 101, 99, 95, 91, 88, 92, 90, 94, 93, 91, 92, 96, 94, 
    98, 97, 95, 96, 100, 98, 102, 101, 105, 104, 102, 99, 100, 97, 93, 89, 
    87, 84, 85, 82, 80, 77, 74, 78, 76, 80, 79, 77, 78, 75, 73, 69, 67, 
    64, 68, 66, 70, 69, 73, 71, 75, 74, 72, 73, 70, 67, 68, 65, 63, 60, 
    64, 62, 66, 65, 69, 68, 66, 63, 64, 61, 59, 56, 60, 58, 62, 61, 65, 
    64, 62, 59, 60, 57, 55, 51, 48, 49, 46, 44, 40, 37, 34, 35, 32, 28, 
    26, 23, 27, 25, 29, 28, 32, 30, 34, 33, 31, 32, 36, 35, 33, 29, 26, 
    27, 24, 22, 19, 23, 21, 25, 24, 28, 27, 25, 22, 23, 20, 18, 14, 18, 
    22, 20, 24, 23, 21, 22, 19, 16, 20, 18, 22, 21, 19, 20, 24, 23, 21, 
    17, 15, 17, 15, 19, 18, 16 ]
  !gapprompt@gap>| !gapinput@lngs := List(Cycle(g,25855),n->Length(Trajectory(T,n,[1])));;|
  !gapprompt@gap>| !gapinput@Minimum(lngs);|
  55
  !gapprompt@gap>| !gapinput@Maximum(lngs);|
  521
  !gapprompt@gap>| !gapinput@Position(lngs,55);|
  15
  !gapprompt@gap>| !gapinput@Position(lngs,521);|
  2807
  
\end{Verbatim}
 Finally let's have a look at elements of $G$ with small modulus: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@B := RestrictedBall(G,One(G),20,36:Spheres);;|
  !gapprompt@gap>| !gapinput@List(B,Length);|
  [ 1, 3, 6, 12, 4, 6, 6, 4, 4, 4, 6, 6, 3, 3, 2, 0, 0, 0, 0, 0, 0 ]
  !gapprompt@gap>| !gapinput@Sum(last);|
  70
  !gapprompt@gap>| !gapinput@Position(last2,0)-2;|
  14
  
\end{Verbatim}
 So we have 70 elements of modulus 36 or less in $G$ which can be reached from the identity by successive multiplication with
generators without passing elements with mudulus exceeding 36. Further we see
that the longest word in the generators yielding an element with modulus at
most 36 has length{\nobreakspace}14. Now we double our bound on the modulus: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@B := RestrictedBall(G,One(G),100,72:Spheres);;|
  !gapprompt@gap>| !gapinput@List(B,Length);|
  [ 1, 3, 6, 12, 22, 14, 18, 22, 24, 26, 26, 34, 35, 32, 37, 38, 46, 58, 
    65, 73, 82, 91, 93, 96, 110, 121, 114, 117, 146, 138, 148, 168, 174, 
    196, 215, 214, 232, 255, 280, 305, 315, 359, 377, 371, 363, 366, 397, 
    419, 401, 405, 405, 401, 407, 415, 435, 424, 401, 359, 338, 330, 332, 
    281, 278, 271, 269, 254, 255, 257, 258, 258, 233, 215, 202, 185, 154, 
    121, 88, 55, 35, 20, 10, 5, 1, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 
    0, 0, 0, 0, 0 ]
  !gapprompt@gap>| !gapinput@Sum(last);|
  15614
  !gapprompt@gap>| !gapinput@Position(last2,0)-2;|
  83
  !gapprompt@gap>| !gapinput@Collected(List(Flat(B),Modulus));|
  [ [ 1, 1 ], [ 6, 3 ], [ 12, 4 ], [ 18, 2 ], [ 24, 4 ], [ 36, 56 ], 
    [ 48, 4 ], [ 72, 15540 ] ]
  
\end{Verbatim}
 We observe that there are 15540 elements in $G$ with modulus 72 which are ``reachable'' from the identity by successive multiplication with generators without passing
elements with mudulus exceeding 72. Further we see that the longest word in
the generators yielding an element with modulus at most 72 has
length{\nobreakspace}83. 

 It is obvious that many questions regarding the group $G$ remain open. }

  
\section{\textcolor{Chapter }{ A group with huge finite orbits }}\label{sec:GroupWithHugeFiniteOrbits}
\logpage{[ 7, 4, 0 ]}
\hyperdef{L}{X7DCFDC797FF213C5}{}
{
  In this section we investigate a group which has huge finite orbits on
{\ensuremath{\mathbb Z}}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@a := ClassTransposition(0,2,1,2);;|
  !gapprompt@gap>| !gapinput@b := ClassTransposition(0,5,4,5);;|
  !gapprompt@gap>| !gapinput@c := ClassTransposition(1,4,0,6);;|
  !gapprompt@gap>| !gapinput@G := Group(a,b,c);|
  <(0(2),1(2)),(0(5),4(5)),(1(4),0(6))>
  !gapprompt@gap>| !gapinput@LoadDatabaseOfGroupsGeneratedBy3ClassTranspositions();|
  "3CTsGroups6"
  !gapprompt@gap>| !gapinput@3CTsGroups6.Id3CTsGroup(G,3CTsGroups6.grps); # 'catalogue number' of G|
  1284
  
\end{Verbatim}
 We look for orbits of length at most 100 containing an integer in the range \texttt{[0..1000]}: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@orbs := ShortOrbits(G,[0..1000],100);;|
  !gapprompt@gap>| !gapinput@List(orbs,Length);|
  [ 16, 2, 24, 2, 2, 2, 8, 2, 8, 2, 2, 8, 2, 8, 2, 2, 2, 40, 2, 8, 24, 2, 
    8, 2, 2, 8, 2, 24, 8, 2, 56, 2, 2, 2, 8, 2, 8, 2, 2, 8, 2, 8, 2, 2, 2, 
    24, 2, 8, 2, 8, 2, 2, 8, 2, 8, 2, 24, 2, 2, 2, 8, 2, 8, 2, 2, 8, 2, 8, 
    2, 2, 2, 2, 8, 24, 2, 8, 2, 2, 8, 2, 24, 8, 2, 2, 2, 2, 8, 2, 8, 2, 2, 
    8, 2, 8, 2, 2, 2, 24, 2, 8, 2, 8, 2, 2, 8, 2, 8, 2, 24, 2, 2 ]
  !gapprompt@gap>| !gapinput@Collected(last);|
  [ [ 2, 67 ], [ 8, 32 ], [ 16, 1 ], [ 24, 9 ], [ 40, 1 ], [ 56, 1 ] ]
  !gapprompt@gap>| !gapinput@Length(Difference([0..1000],Union(orbs)));|
  491
  
\end{Verbatim}
 So almost half of the integers in the range \texttt{[0..1000]} lie in orbits of length larger than 100. In fact there are much larger orbits.
For example: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@B := Ball(G,32,500,OnPoints:Spheres);; # compute ball about 32|
  !gapprompt@gap>| !gapinput@Position(B,[]); # <> fail -> we have exhausted the orbit|
  354
  !gapprompt@gap>| !gapinput@Sum(List(B,Length)); # the orbit length|
  6296
  !gapprompt@gap>| !gapinput@Maximum(Flat(B)); # the largest integer in the orbit|
  3301636381609509797437679
  !gapprompt@gap>| !gapinput@B := Ball(G,736,5000,OnPoints:Spheres);; # the same for 736 ...|
  !gapprompt@gap>| !gapinput@Position(B,[]);|
  2997
  !gapprompt@gap>| !gapinput@Sum(List(B,Length)); # the orbit length for this time|
  495448
  !gapprompt@gap>| !gapinput@Maximum(Flat(B));|
  2461374276522713949036151811903149785690151467356354652860276957152301465java.lang.NullPointerException
  0546360696627187194849439881973442451686685024708652634593861146709752378java.lang.NullPointerException
  847078493406287854573381920553713155967741550498839
  
\end{Verbatim}
 It seems that the cycles of $abc$ completely traverse all orbits of $G$, with the only exception of the orbit of 0. Let's check this in the above
examples: 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@g := a*b*c;;A
  !gapprompt@gap>A !gapinput@Display(g);A
  
  Rcwa permutation of Z with modulus 60
  
          /
          | n-1       if n in 3(30) U 9(30) U 17(30) U 23(30) U 27(30) U 
          |                   29(30)
          | 3n/2      if n in 0(20) U 12(20) U 16(20)
          | n+1       if n in 2(20) U 6(20) U 10(20)
          | (2n+1)/3  if n in 7(30) U 13(30) U 19(30)
          | n+3       if n in 1(30) U 11(30)
   n |-> <  n-5       if n in 15(30) U 25(30)
          | (3n+12)/2 if n in 4(20)
          | (3n-12)/2 if n in 8(20)
          | n+5       if n in 14(20)
          | n-3       if n in 18(20)
          | (2n-7)/3  if n in 5(30)
          | (2n+9)/3  if n in 21(30)
          java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@Length(Cycle(g,32));A
  6296
  !gapprompt@gap>A !gapinput@Length(Cycle(g,736));A
  495448
  
\end{Verbatim}
 Representatives and lengths of the cycles of $g$ which intersect nontrivially with the range \texttt{[0..1000]} are as follows: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@CycleRepresentativesAndLengths(g,[0..1000]:notify:=50000);|
  n = 736: after 50000 steps, the iterate has 157 binary digits.
  n = 736: after 100000 steps, the iterate has 135 binary digits.
  n = 736: after 150000 steps, the iterate has 131 binary digits.
  n = 736: after 200000 steps, the iterate has 507 binary digits.
  n = 736: after 250000 steps, the iterate has 414 binary digits.
  n = 736: after 300000 steps, the iterate has 457 binary digits.
  n = 736: after 350000 steps, the iterate has 465 binary digits.
  n = 736: after 400000 steps, the iterate has 325 binary digits.
  n = 736: after 450000 steps, the iterate has 534 binary digits.
  n = 896: after 50000 steps, the iterate has 359 binary digits.
  n = 896: after 100000 steps, the iterate has 206 binary digits.
  [ [ 1, 15 ], [ 2, 2 ], [ 16, 24 ], [ 22, 2 ], [ 26, 2 ], [ 32, 6296 ], 
    [ 46, 2 ], [ 52, 8 ], [ 56, 296 ], [ 62, 2 ], [ 76, 8 ], [ 82, 2 ], 
    [ 86, 2 ], [ 92, 8 ], [ 106, 2 ], [ 112, 104 ], [ 116, 8 ], 
    [ 122, 2 ], [ 136, 440 ], [ 142, 2 ], [ 146, 2 ], [ 152, 40 ], 
    [ 166, 2 ], [ 172, 8 ], [ 176, 24 ], [ 182, 2 ], [ 196, 8 ], 
    [ 202, 2 ], [ 206, 2 ], [ 212, 8 ], [ 226, 2 ], [ 232, 24 ], 
    [ 236, 8 ], [ 242, 2 ], [ 256, 56 ], [ 262, 2 ], [ 266, 2 ], 
    [ 272, 408 ], [ 286, 2 ], [ 292, 8 ], [ 296, 104 ], [ 302, 2 ], 
    [ 316, 8 ], [ 322, 2 ], [ 326, 2 ], [ 332, 8 ], [ 346, 2 ], 
    [ 352, 264 ], [ 356, 8 ], [ 362, 2 ], [ 376, 1304 ], [ 382, 2 ], 
    [ 386, 2 ], [ 392, 24 ], [ 406, 2 ], [ 412, 8 ], [ 416, 200 ], 
    [ 422, 2 ], [ 436, 8 ], [ 442, 2 ], [ 446, 2 ], [ 452, 8 ], 
    [ 466, 2 ], [ 472, 104 ], [ 476, 8 ], [ 482, 2 ], [ 496, 24 ], 
    [ 502, 2 ], [ 506, 2 ], [ 512, 696 ], [ 526, 2 ], [ 532, 8 ], 
    [ 536, 3912 ], [ 542, 2 ], [ 556, 8 ], [ 562, 2 ], [ 566, 2 ], 
    [ 572, 8 ], [ 586, 2 ], [ 592, 888 ], [ 596, 8 ], [ 602, 2 ], 
    [ 616, 728 ], [ 622, 2 ], [ 626, 2 ], [ 632, 2776 ], [ 646, 2 ], 
    [ 652, 8 ], [ 656, 24 ], [ 662, 2 ], [ 676, 8 ], [ 682, 2 ], 
    [ 686, 2 ], [ 692, 8 ], [ 706, 2 ], [ 712, 24 ], [ 716, 8 ], 
    [ 722, 2 ], [ 736, 495448 ], [ 742, 2 ], [ 746, 2 ], [ 752, 1272 ], 
    [ 766, 2 ], [ 772, 8 ], [ 776, 376 ], [ 782, 2 ], [ 796, 8 ], 
    [ 802, 2 ], [ 806, 2 ], [ 812, 8 ], [ 826, 2 ], [ 832, 120 ], 
    [ 836, 8 ], [ 842, 2 ], [ 856, 2264 ], [ 862, 2 ], [ 866, 2 ], 
    [ 872, 24 ], [ 886, 2 ], [ 892, 8 ], [ 896, 132760 ], [ 902, 2 ], 
    [ 916, 8 ], [ 922, 2 ], [ 926, 2 ], [ 932, 8 ], [ 946, 2 ], 
    [ 952, 456 ], [ 956, 8 ], [ 962, 2 ], [ 976, 24 ], [ 982, 2 ], 
    [ 986, 2 ], [ 992, 1064 ] ]
  
\end{Verbatim}
 So far the author has checked that all positive integers less than 173176 lie
in finite cycles of $g$. Several of them are longer than 1000000, and the cycle containing 25952 has
length 245719352. Whether the cycle containing 173176 is finite or infinite
has not been checked so far \texttt{\symbol{45}}\texttt{\symbol{45}} in any
case it is longer than 5700000000, and it exceeds $10^{40000}$. Presumably it is finite as well, but checking this may require a lot of
computing time. 

 On the one hand the cycles of $g$ seem to behave ``randomly'', perhaps as if they would ascend or descend from one point to the next by a
certain factor depending on which side a thrown coin falls on.
\texttt{\symbol{45}}\texttt{\symbol{45}} In this ``model'', cycles would be finite with probability 1 since the simple random walk on
{\ensuremath{\mathbb Z}} is recurrent. On the other, there seems to be quite
some structure on them, however little is known so far. 

 First we observe that each orbit under the action of $G$ seems to split into two cycles of $h := abcacb$ of the same length (of course this has been checked for many more orbits than
those shown here): 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@h := a*b*c*a*c*b;|
  <rcwa permutation of Z with modulus 360>
  !gapprompt@gap>| !gapinput@List(CyclesOnFiniteOrbit(G,h,32),Length);|
  [ 3148, 3148 ]
  !gapprompt@gap>| !gapinput@List(CyclesOnFiniteOrbit(G,h,736),Length);|
  [ 247724, 247724 ]
  
\end{Verbatim}
 One cycle seems to contain the points at the odd positions and the other seems
to contain the points at the even positions in the cycle of $g$: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@cycle_g := Cycle(g,32);;|
  !gapprompt@gap>| !gapinput@positions1 := List(Cycle(h,32),n->Position(cycle_g,n));;|
  !gapprompt@gap>| !gapinput@Collected(positions1 mod 2);|
  [ [ 1, 3148 ] ]
  !gapprompt@gap>| !gapinput@positions2 := List(Cycle(h,33),n->Position(cycle_g,n));;|
  !gapprompt@gap>| !gapinput@Collected(positions2 mod 2);|
  [ [ 0, 3148 ] ]
  
\end{Verbatim}
 However the ordering in which these points are traversed looks pretty ``scrambled'': 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@positions1{[1..200]};|
  [ 1, 6271, 6291, 6281, 6285, 6287, 6283, 6289, 6273, 6275, 6277, 6279, 
    6293, 5, 15, 17, 19, 6259, 6261, 6263, 6265, 21, 23, 25, 41, 6227, 
    6229, 6231, 6233, 6235, 6237, 6239, 43, 53, 55, 57, 63, 59, 61, 65, 
    45, 47, 49, 51, 67, 6223, 6221, 69, 6163, 6215, 6205, 6209, 6211, 
    6207, 6213, 6165, 6171, 6177, 6179, 6181, 6183, 6175, 6173, 6185, 
    6189, 6191, 6187, 6193, 6169, 6167, 6195, 6199, 6201, 6197, 6203, 
    6217, 73, 83, 85, 87, 103, 113, 115, 117, 4357, 4361, 4363, 4359, 
    4365, 4371, 4373, 4375, 4377, 4369, 4367, 4379, 119, 121, 123, 125, 
    129, 131, 127, 133, 139, 141, 143, 145, 137, 135, 147, 149, 151, 153, 
    155, 159, 161, 157, 163, 169, 175, 4283, 4281, 177, 4271, 4273, 4275, 
    4277, 181, 4255, 4257, 4259, 4261, 4263, 4265, 4267, 183, 2161, 2163, 
    4195, 4199, 4201, 4197, 4203, 4209, 4211, 4213, 4215, 4207, 4205, 
    4217, 2165, 2167, 2169, 2171, 2175, 2177, 2173, 2179, 2185, 2187, 
    2189, 2191, 2183, 2181, 2193, 2195, 2197, 2199, 2201, 2467, 2469, 
    4117, 4121, 4123, 4119, 4125, 4131, 4133, 4135, 4137, 4129, 4127, 
    4139, 2471, 2473, 2475, 2477, 2487, 2489, 2491, 2507, 2517, 2519, 
    2521, 2537, 3923, 3925, 3941, 3943 ]
  
\end{Verbatim}
 }

  
\section{\textcolor{Chapter }{ A group which acts 4\texttt{\symbol{45}}transitively on the positive integers }}\label{sec:FourTransitiveGroup}
\logpage{[ 7, 5, 0 ]}
\hyperdef{L}{X7968C1DF7EF0BD8E}{}
{
  In this section, we would like to show that the group $G$ generated by the two permutations 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@a := RcwaMapping([[3,0,2],[3,1,4],[3,0,2],[3,-1,4]]);;|
  !gapprompt@gap>| !gapinput@u := RcwaMapping([[3,0,5],[9,1,5],[3,-1,5],[9,-2,5],[9,4,5]]);;|
  !gapprompt@gap>| !gapinput@SetName(a,"a"); SetName(u,"u"); G := Group(a,u);;|
  
\end{Verbatim}
 which we have already investigated in earlier examples acts
4\texttt{\symbol{45}}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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@List([a,a^-1,u,u^-1],DecreasingOn);|
  [ 1(2), 0(3), 0(5) U 2(5), 2(3) ]
  !gapprompt@gap>| !gapinput@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 \texttt{\symbol{45}}\texttt{\symbol{45}}
otherwise the union would be \texttt{Integers}. 
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=Example]
  
  @gapprompt|gap>A @gapinput|List([a,a^-1,u,u^-1,a^2,a^-2,u^2,u^-2],DecreasingOn);A
  [ 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) ]
  @gapprompt|gap>A @gapinput|Union(last); # Still not enough ...A
  Z \ 4(90) U 58(90) U 76(90)
  @gapprompt|gap>A @gapinput|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],A
  @gapprompt|>A @gapinput|        DecreasingOn);A
  [ 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) ]
  @gapprompt|gap>A @gapinput|Union(last); # ... but that's it!A
  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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@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],|
  !gapprompt@>| !gapinput@        f->Maximum(List(Coefficients(f),c->c[2])));|
  [ 1, 1, 4, 2, 7, 7, 56, 28, 25, 17, 17, 11 ]
  !gapprompt@gap>| !gapinput@Maximum(last);|
  56
  
\end{Verbatim}
 Thus this upper bound is 56. The rest is easy
\texttt{\symbol{45}}\texttt{\symbol{45}} all we have to do is to check that
the orbit containing{\nobreakspace}1 contains also all other positive integers
less than or equal to{\nobreakspace}56: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@S := [1];;|
  !gapprompt@gap>| !gapinput@while not IsSubset(S,[1..56]) do|
  !gapprompt@>| !gapinput@     S := Union(S,S^a,S^u,S^(a^-1),S^(u^-1));|
  !gapprompt@>| !gapinput@   od;|
  !gapprompt@gap>| !gapinput@IsSubset(S,[1..56]);|
  true
  
\end{Verbatim}
 Checking 2\texttt{\symbol{45}}transitivity is computationally harder, and in
the sequel we will omit some steps which are in practice needed to find out ``what{\nobreakspace}to{\nobreakspace}do''. The approach taken here is to show that the stabilizer of{\nobreakspace}1
in{\nobreakspace}$G$ acts transitively on the set of positive integers greater
than{\nobreakspace}1. We do this by similar means as used above for showing
the transitivity of the action of $G$ on the positive integers. We start by determining all products of at most 5
generators and their inverses, which stabilize{\nobreakspace}1 (taking at most
4\texttt{\symbol{45}}generator products would not suffice!): 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@gens := [a,u,a^-1,u^-1];;|
  !gapprompt@gap>| !gapinput@tups := Concatenation(List([1..5],k->Tuples([1..4],k)));;|
  !gapprompt@gap>| !gapinput@Length(tups);|
  1364
  !gapprompt@gap>| !gapinput@tups := Filtered(tups,tup->ForAll([[1,3],[3,1],[2,4],[4,2]],|
  !gapprompt@>| !gapinput@                                     l->PositionSublist(tup,l)=fail));;|
  !gapprompt@gap>| !gapinput@Length(tups);|
  484
  !gapprompt@gap>| !gapinput@stab := [];;|
  !gapprompt@gap>| !gapinput@for tup in tups do|
  !gapprompt@>| !gapinput@     n := 1;|
  !gapprompt@>| !gapinput@     for i in tup do n := n^gens[i]; od;|
  !gapprompt@>| !gapinput@     if n = 1 then Add(stab,tup); fi;|
  !gapprompt@>| !gapinput@   od;|
  !gapprompt@gap>| !gapinput@Length(stab);|
  118
  !gapprompt@gap>| !gapinput@stabelm := List(stab,tup->Product(List(tup,i->gens[i])));;|
  !gapprompt@gap>| !gapinput@ForAll(stabelm,elm->1^elm=1); # Check.|
  true
  
\end{Verbatim}
 The resulting products have various different not quite small moduli: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@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 ]
  !gapprompt@gap>| !gapinput@Lcm(last);|
  12597120000
  !gapprompt@gap>| !gapinput@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)}$ \texttt{\symbol{45}} coefficient of the respective mapping are mapped to
smaller integers: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@decs := List(stabelm,DecreasingOn);;|
  !gapprompt@gap>| !gapinput@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 ]
  !gapprompt@gap>| !gapinput@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\texttt{\symbol{45}}by\texttt{\symbol{45}}one in a suitably chosen
order is cheap: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@SortParallel(decs,stabelm,|
  !gapprompt@>| !gapinput@     function(S1,S2)|
  !gapprompt@>| !gapinput@       return First([1..100],k->Factorial(k) mod Modulus(S1)=0)|
  !gapprompt@>| !gapinput@            < First([1..100],k->Factorial(k) mod Modulus(S2)=0);|
  !gapprompt@>| !gapinput@     end);|
  !gapprompt@gap>| !gapinput@S := Integers;;|
  !gapprompt@gap>| !gapinput@for i in [1..Length(decs)] do|
  !gapprompt@>| !gapinput@     S_old := S; S := Difference(S,decs[i]);|
  !gapprompt@>| !gapinput@     if S <> S_old then ViewObj(S); Print("\n"); fi;|
  !gapprompt@>| !gapinput@     if S = [] then maxind := i; break; fi;|
  !gapprompt@>| !gapinput@   od;|
  0(2)
  2(6) U 4(6)
  <union of 19 residue classes (mod 60) (6 classes)>
  <union of 8 residue classes (mod 30)>
  <union of 120 residue classes (mod 720)>
  <union of 112 residue classes (mod 720)>
  <union of 80 residue classes (mod 720)>
  <union of 24 residue classes (mod 720)>
  <union of 16 residue classes (mod 720) (12 classes)>
  <union of 8 residue classes (mod 720)>
  <union of 6 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 204 residue classes (mod 259200)>
  <union of 144 residue classes (mod 259200)>
  <union of 120 residue classes (mod 259200)>
  <union of 84 residue classes (mod 259200)>
  <union of 72 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) (6 classes)>
  <union of 30 residue classes (mod 777600)>
  54004(64800) U 151204(259200) U 216004(259200)
  [  ]
  
\end{Verbatim}
 Similar as above, it remains to check that the ``small'' integers all lie in the orbit containing{\nobreakspace}2. Obviously, it is
sufficient to check that any integer greater than{\nobreakspace}2 is mapped to
a smaller one by some suitably chosen element of the stabilizer under
consideration: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Maximum(List(stabelm{[1..maxind]},|
  !gapprompt@>| !gapinput@                f->Maximum(List(Coefficients(f),c->c[2]))));|
  6581
  !gapprompt@gap>| !gapinput@Filtered([3..6581],n->Minimum(List(stabelm,elm->n^elm))>=n);|
  [ 4 ]
  
\end{Verbatim}
 We have to treat 4 separately: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@1^(u*a*u^2*a^-1*u);|
  1
  !gapprompt@gap>| !gapinput@4^(u*a*u^2*a^-1*u);|
  3
  
\end{Verbatim}
 Now we know that any positive integer greater than{\nobreakspace}1 lies in the
same orbit under the action of the stabilizer of{\nobreakspace}1
in{\nobreakspace}$G$ as{\nobreakspace}2, thus that this stabilizer acts transitively on ${\ensuremath{\mathbb N}} \setminus \{1\}$. But this means that we have established the
2\texttt{\symbol{45}}transitivity of the action of $G$ on{\nobreakspace}{\ensuremath{\mathbb N}}. 

 In the following, we essentially repeat the above steps to show that this
action is indeed 3\texttt{\symbol{45}}transitive: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@tups := Concatenation(List([1..6],k->Tuples([1..4],k)));;|
  !gapprompt@gap>| !gapinput@tups := Filtered(tups,tup->ForAll([[1,3],[3,1],[2,4],[4,2]],|
  !gapprompt@>| !gapinput@                                     l->PositionSublist(tup,l)=fail));;|
  !gapprompt@gap>| !gapinput@stab := [];;|
  !gapprompt@gap>| !gapinput@for tup in tups do|
  !gapprompt@>| !gapinput@     l := [1,2];|
  !gapprompt@>| !gapinput@     for i in tup do l := List(l,n->n^gens[i]); od;|
  !gapprompt@>| !gapinput@     if l = [1,2] then Add(stab,tup); fi;|
  !gapprompt@>| !gapinput@   od;|
  !gapprompt@gap>| !gapinput@Length(stab);|
  212
  !gapprompt@gap>| !gapinput@stabelm := List(stab,tup->Product(List(tup,i->gens[i])));;|
  !gapprompt@gap>| !gapinput@decs := List(stabelm,DecreasingOn);;|
  !gapprompt@gap>| !gapinput@SortParallel(decs,stabelm,function(S1,S2)|
  !gapprompt@>| !gapinput@     return First([1..100],k->Factorial(k) mod Mod(S1)=0)|
  !gapprompt@>| !gapinput@          < First([1..100],k->Factorial(k) mod Mod(S2)=0); end);|
  !gapprompt@gap>| !gapinput@S := Integers;;|
  !gapprompt@gap>| !gapinput@for i in [1..Length(decs)] do|
  !gapprompt@>| !gapinput@     S_old := S; S := Difference(S,decs[i]);|
  !gapprompt@>| !gapinput@     if S <> S_old then ViewObj(S); Print("\n"); fi;|
  !gapprompt@>| !gapinput@     if S = [] then break; fi;|
  !gapprompt@>| !gapinput@   od;|
  Z \ 1(8) U 7(8)
  <union of 424 residue classes (mod 720)>
  <union of 169 residue classes (mod 720)>
  <union of 51 residue classes (mod 720)>
  <union of 45 residue classes (mod 720)>
  <union of 42 residue classes (mod 720)>
  <union of 35 residue classes (mod 720)>
  <union of 30 residue classes (mod 720)>
  <union of 16 residue classes (mod 720) (10 classes)>
  <union of 11 residue classes (mod 720) (7 classes)>
  <union of 8 residue classes (mod 720) (6 classes)>
  148(360) U 238(360) U 4(720) U 454(720)
  238(360) U 4(720) U 148(720) U 454(720)
  <union of 28 residue classes (mod 5760)>
  <union of 24 residue classes (mod 5760)>
  <union of 23 residue classes (mod 5760)>
  <union of 22 residue classes (mod 5760)>
  <union of 20 residue classes (mod 5760) (14 classes)>
  <union of 19 residue classes (mod 5760) (14 classes)>
  <union of 16 residue classes (mod 5760) (12 classes)>
  <union of 112 residue classes (mod 51840)>
  <union of 96 residue classes (mod 51840)>
  <union of 90 residue classes (mod 51840)>
  <union of 51 residue classes (mod 51840)>
  <union of 21 residue classes (mod 51840)>
  <union of 19 residue classes (mod 51840) (15 classes)>
  <union of 16 residue classes (mod 51840) (12 classes)>
  <union of 54 residue classes (mod 259200)>
  <union of 53 residue classes (mod 259200)>
  <union of 50 residue classes (mod 259200)>
  <union of 38 residue classes (mod 259200)>
  <union of 35 residue classes (mod 259200)>
  <union of 32 residue classes (mod 259200)>
  <union of 24 residue classes (mod 259200)>
  <union of 22 residue classes (mod 259200)>
  <union of 20 residue classes (mod 259200) (16 classes)>
  <union of 18 residue classes (mod 259200) (15 classes)>
  <union of 16 residue classes (mod 259200) (13 classes)>
  <union of 15 residue classes (mod 259200) (12 classes)>
  <union of 12 residue classes (mod 259200) (10 classes)>
  <union of 7 residue classes (mod 259200)>
  2164(259200) U 66964(259200) U 228964(259200)
  [  ]
  !gapprompt@gap>| !gapinput@Maximum(List(stabelm,f->Maximum(List(Coefficients(f),c->c[2]))));|
  515816
  !gapprompt@gap>| !gapinput@smallnum := [4..515816];;|
  !gapprompt@gap>| !gapinput@for i in [1..Length(stabelm)] do|
  !gapprompt@>| !gapinput@     smallnum := Filtered(smallnum,n->n^stabelm[i]>=n);|
  !gapprompt@>| !gapinput@   od;|
  !gapprompt@gap>| !gapinput@smallnum;|
  [  ]
  
\end{Verbatim}
 The same for 4\texttt{\symbol{45}}transitivity: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@tups := Concatenation(List([1..8],k->Tuples([1..4],k)));;|
  !gapprompt@gap>| !gapinput@tups := Filtered(tups,tup->ForAll([[1,3],[3,1],[2,4],[4,2]],|
  !gapprompt@>| !gapinput@                                     l->PositionSublist(tup,l)=fail));;|
  !gapprompt@gap>| !gapinput@stab := [];;|
  !gapprompt@gap>| !gapinput@for tup in tups do|
  !gapprompt@>| !gapinput@     l := [1,2,3];|
  !gapprompt@>| !gapinput@     for i in tup do l := List(l,n->n^gens[i]); od;|
  !gapprompt@>| !gapinput@     if l = [1,2,3] then Add(stab,tup); fi;|
  !gapprompt@>| !gapinput@   od;|
  !gapprompt@gap>| !gapinput@Length(stab);|
  528
  !gapprompt@gap>| !gapinput@stabelm := [];;|
  !gapprompt@gap>| !gapinput@for i in [1..Length(stab)] do|
  !gapprompt@>| !gapinput@     elm := One(G);|
  !gapprompt@>| !gapinput@     for j in stab[i] do|
  !gapprompt@>| !gapinput@       if Modulus(elm) > 10000 then elm := fail; break; fi;|
  !gapprompt@>| !gapinput@       elm := elm * gens[j];|
  !gapprompt@>| !gapinput@     od;|
  !gapprompt@>| !gapinput@     if elm <> fail then Add(stabelm,elm); fi;|
  !gapprompt@>| !gapinput@   od;|
  !gapprompt@gap>| !gapinput@Length(stabelm);|
  334
  !gapprompt@gap>| !gapinput@decs := List(stabelm,DecreasingOn);;|
  !gapprompt@gap>| !gapinput@SortParallel(decs,stabelm,|
  !gapprompt@>| !gapinput@     function(S1,S2)|
  !gapprompt@>| !gapinput@       return First([1..100],k->Factorial(k) mod Modulus(S1) = 0)|
  !gapprompt@>| !gapinput@            < First([1..100],k->Factorial(k) mod Modulus(S2) = 0);|
  !gapprompt@>| !gapinput@     end);|
  !gapprompt@gap>| !gapinput@S := Integers;;|
  !gapprompt@gap>| !gapinput@for i in [1..Length(decs)] do|
  !gapprompt@>| !gapinput@     S_old := S; S := Difference(S,decs[i]);|
  !gapprompt@>| !gapinput@     if S <> S_old then ViewObj(S); Print("\n"); fi;|
  !gapprompt@>| !gapinput@     if S = [] then maxind := i; break; fi;|
  !gapprompt@>| !gapinput@   od;|
  Z \ 1(8) U 7(8)
  <union of 24 residue classes (mod 72)>
  <union of 22 residue classes (mod 72)>
  <union of 17 residue classes (mod 72) (9 classes)>
  4(18)
  <union of 28 residue classes (mod 576)>
  <union of 26 residue classes (mod 576)>
  <union of 21 residue classes (mod 576)>
  <union of 20 residue classes (mod 576) (7 classes)>
  <union of 18 residue classes (mod 576) (8 classes)>
  <union of 16 residue classes (mod 576) (6 classes)>
  <union of 15 residue classes (mod 576) (6 classes)>
  <union of 120 residue classes (mod 5184)>
  <union of 45 residue classes (mod 5184)>
  <union of 30 residue classes (mod 5184)>
  <union of 28 residue classes (mod 5184)>
  <union of 6 residue classes (mod 1296)>
  <union of 116 residue classes (mod 32400)>
  <union of 104 residue classes (mod 32400)>
  <union of 92 residue classes (mod 32400)>
  <union of 84 residue classes (mod 32400)>
  <union of 80 residue classes (mod 32400)>
  <union of 210 residue classes (mod 129600)>
  <union of 189 residue classes (mod 129600)>
  <union of 160 residue classes (mod 129600)>
  <union of 136 residue classes (mod 129600)>
  <union of 133 residue classes (mod 129600)>
  <union of 122 residue classes (mod 129600)>
  <union of 114 residue classes (mod 129600)>
  <union of 106 residue classes (mod 129600)>
  <union of 104 residue classes (mod 129600)>
  <union of 100 residue classes (mod 129600)>
  <union of 96 residue classes (mod 129600)>
  <union of 60 residue classes (mod 129600)>
  <union of 52 residue classes (mod 129600)>
  <union of 48 residue classes (mod 129600)>
  <union of 40 residue classes (mod 129600)>
  <union of 36 residue classes (mod 129600)>
  <union of 32 residue classes (mod 129600)>
  <union of 24 residue classes (mod 129600)>
  <union of 16 residue classes (mod 129600) (10 classes)>
  <union of 12 residue classes (mod 129600)>
  <union of 10 residue classes (mod 129600)>
  <union of 8 residue classes (mod 129600)>
  <union of 6 residue classes (mod 129600)>
  57406(129600) U 63076(129600) U 115006(129600) U 120676(129600)
  57406(129600) U 115006(129600) U 192676(259200) U 250276(259200)
  <union of 15 residue classes (mod 777600) (6 classes)>
  <union of 9 residue classes (mod 777600) (6 classes)>
  <union of 30 residue classes (mod 3110400)>
  <union of 26 residue classes (mod 3110400)>
  <union of 22 residue classes (mod 3110400)>
  <union of 19 residue classes (mod 3110400) (10 classes)>
  <union of 14 residue classes (mod 3110400) (8 classes)>
  705406(777600) U 2007076(3110400) U 2649406(3110400) U 2784676(3110400)
  <union of 14 residue classes (mod 9331200) (8 classes)>
  1483006(2332800) U 2649406(9331200) U 2784676(9331200) U 5117476(9331200)
  <union of 16 residue classes (mod 27993600) (6 classes)>
  2784676(9331200) U 5117476(9331200)
  [  ]
  !gapprompt@gap>| !gapinput@Maximum(List(stabelm{[1..maxind]},|
  !gapprompt@>| !gapinput@                f->Maximum(List(Coefficients(f),c->c[2]))));|
  37387
  !gapprompt@gap>| !gapinput@smallnum := [5..37387];;|
  !gapprompt@gap>| !gapinput@for i in [1..maxind] do|
  !gapprompt@>| !gapinput@     smallnum := Filtered(smallnum,n->n^stabelm[i]>=n);|
  !gapprompt@>| !gapinput@   od;|
  !gapprompt@gap>| !gapinput@smallnum;|
  [  ]
  
\end{Verbatim}
 There is even some evidence that the degree of transitivity of the action of $G$ on the positive integers is higher than{\nobreakspace}4: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@phi := EpimorphismFromFreeGroup(G);|
  [ a, u ] -> [ a, u ]
  !gapprompt@gap>| !gapinput@F := Source(phi);|
  <free group on the generators [ a, u ]>
  !gapprompt@gap>| !gapinput@List([5..20],|
  !gapprompt@>| !gapinput@        n->RepresentativeActionPreImage(G,[1,2,3,4,5],|
  !gapprompt@>| !gapinput@                                          [1,2,3,4,n],OnTuples,F));|
  [ <identity ...>, a^-3*u^4*a*u^-2*a^2, a^-1*(a^-1*u)^4*a^-1*u^-1*a, 
    a^4*u^-2*a^-4, a^-1*u^-4*a, (u^2*a^-1)^2*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^2*(a*u^2)^2, (a*u^-4)^2*a^-2, 
    u^-2*a*u^2*a*u^-2, u^-4*a^2*u^2 ]
  
\end{Verbatim}
 Enter \texttt{AssignGlobals(LoadRCWAExamples().CollatzlikePerms);} in order to assign the global variables defined in this section. }

  
\section{\textcolor{Chapter }{ A group which acts 3\texttt{\symbol{45}}transitively, but not
4\texttt{\symbol{45}}transitively on {\ensuremath{\mathbb Z}} }}\label{sec:ThreeButNotFourTransitiveGroup}
\logpage{[ 7, 6, 0 ]}
\hyperdef{L}{X85C529088050BEA3}{}
{
  In this section, we would like to show that the group $G$ generated by the two permutations $n \mapsto n + 1$ and $\tau_{1(2),0(4)}$ acts 3\texttt{\symbol{45}}transitively, but not
4\texttt{\symbol{45}}transitively on the set of integers. 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@G := Group(ClassShift(0,1),ClassTransposition(1,2,0,4));A
  <rcwa group over Z with 2 generators>
  !gapprompt@gap>A !gapinput@IsTame(G);A
  false
  !gapprompt@gap>A !gapinput@(G.1^-2*G.2)^3*(G.1^2*G.2)^3; # G <> the free product C_infty * C_2.A
  IdentityMapping( Integers )
  !gapprompt@gap>A !gapinput@Display(G:CycleNotation:=false);A
  
  Wild rcwa group over Z, generated by
  
  [
  Tame rcwa permutation of Z: n -> n + 1
  
  Rcwa permutation of Z with modulus 4, of order 2
  
          /
          | 2n-2    if n in 1(2)
   n |-> <  (n+2)/2 if n in 0(4)
          | n       if n in 2(4)
          java.lang.NullPointerException
  
  ]
  
\end{Verbatim}
 This group acts transitively on{\nobreakspace}{\ensuremath{\mathbb 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\texttt{\symbol{45}}transitively. We
essentially proceed as in the example in the previous section, by checking
that the stabilizer of{\nobreakspace}0 acts transitively on ${\ensuremath{\mathbb Z}} \setminus \{0\}$. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@gens := [ClassShift(0,1)^-1,ClassTransposition(1,2,0,4),|
  !gapprompt@>| !gapinput@            ClassShift(0,1)];;|
  !gapprompt@gap>| !gapinput@tups := Concatenation(List([1..6],k->Tuples([-1,0,1],k)));;|
  !gapprompt@gap>| !gapinput@tups := Filtered(tups,tup->ForAll([[0,0],[-1,1],[1,-1]],|
  !gapprompt@>| !gapinput@                                     l->PositionSublist(tup,l)=fail));;|
  !gapprompt@gap>| !gapinput@Length(tups);|
  189
  !gapprompt@gap>| !gapinput@stab := [];;|
  !gapprompt@gap>| !gapinput@for tup in tups do|
  !gapprompt@>| !gapinput@     n := 0;|
  !gapprompt@>| !gapinput@     for i in tup do n := n^gens[i+2]; od;|
  !gapprompt@>| !gapinput@     if n = 0 then Add(stab,tup); fi;|
  !gapprompt@>| !gapinput@   od;|
  !gapprompt@gap>| !gapinput@stabelm := List(stab,tup->Product(List(tup,i->gens[i+2])));;|
  !gapprompt@gap>| !gapinput@Collected(List(stabelm,Modulus));|
  [ [ 4, 6 ], [ 8, 4 ], [ 16, 3 ] ]
  !gapprompt@gap>| !gapinput@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) ]
  !gapprompt@gap>| !gapinput@Union(decs);|
  Integers
  
\end{Verbatim}
 Similar as in the previous section, it remains to check that the integers with ``small'' absolute value all lie in the orbit containing{\nobreakspace}1 under the
action of the stabilizer of{\nobreakspace}0: 
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=Example]
  
  @gapprompt|gap>B @gapinput|Maximum(List(stabelm,f->Maximum(List(Coefficients(f),B
  @gapprompt|>B @gapinput|                                        c->AbsInt(c[2])))));B
  21
  @gapprompt|gap>B @gapinput|S := [1];;B
  @gapprompt|gap>B @gapinput|for elm in stabelm do S := Union(S,S^elm,S^(elm^-1)); od;B
  @gapprompt|gap>B @gapinput|IsSubset(S,Difference([-21..21],[0])); # Not yet ..B
  false
  @gapprompt|gap>B @gapinput|for elm in stabelm do S := Union(S,S^elm,S^(elm^-1)); od;B
  @gapprompt|gap>B @gapinput|IsSubset(S,Difference([-21..21],[0])); # ... but now!B
  true
  
\end{Verbatim}
 Now we have to check for 3\texttt{\symbol{45}}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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@tups := Concatenation(List([1..10],k->Tuples([-1,0,1],k)));;|
  !gapprompt@gap>| !gapinput@tups := Filtered(tups,tup->ForAll([[0,0],[-1,1],[1,-1]],|
  !gapprompt@>| !gapinput@                                     l->PositionSublist(tup,l)=fail));;|
  !gapprompt@gap>| !gapinput@Length(tups);|
  3069
  !gapprompt@gap>| !gapinput@stab := [];;|
  !gapprompt@gap>| !gapinput@for tup in tups do|
  !gapprompt@>| !gapinput@     l := [0,1];|
  !gapprompt@>| !gapinput@     for i in tup do l := List(l,n->n^gens[i+2]); od;|
  !gapprompt@>| !gapinput@     if l = [0,1] then Add(stab,tup); fi;|
  !gapprompt@>| !gapinput@   od;|
  !gapprompt@gap>| !gapinput@Length(stab);|
  10
  !gapprompt@gap>| !gapinput@stabelm := List(stab,tup->Product(List(tup,i->gens[i+2])));;|
  !gapprompt@gap>| !gapinput@Maximum(List(stabelm,Modulus));|
  8
  !gapprompt@gap>| !gapinput@Maximum(List(stabelm,|
  !gapprompt@>| !gapinput@                f->Maximum(List(Coefficients(f),c->AbsInt(c[2])))));|
  8
  !gapprompt@gap>| !gapinput@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 ] ]
  !gapprompt@gap>| !gapinput@Union(decsp);|
  [ 9 .. 16 ]
  !gapprompt@gap>| !gapinput@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 ] ]
  !gapprompt@gap>| !gapinput@Union(decsm);|
  [ -16 .. -9 ]
  !gapprompt@gap>| !gapinput@S := [2];;|
  !gapprompt@gap>| !gapinput@for elm in stabelm do S := Union(S,S^elm,S^(elm^-1)); od;|
  !gapprompt@gap>| !gapinput@IsSubset(S,Difference([-8..8],[0,1]));|
  true
  
\end{Verbatim}
 At this point we have established 3\texttt{\symbol{45}}transitivity. It
remains to check that the group $G$ does not act 4\texttt{\symbol{45}}transitively. We do this by checking that it
is not transitive on 4\texttt{\symbol{45}}tuples (mod{\nobreakspace}4). Since $n${\nobreakspace}mod{\nobreakspace}8 determines the image of $n$ under a generator of $G$ (mod{\nobreakspace}4), it suffices to compute (mod{\nobreakspace}8): 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@orb := [[0,1,2,3]];;|
  !gapprompt@gap>| !gapinput@extend := function ()|
  !gapprompt@>| !gapinput@     local gen;|
  !gapprompt@>| !gapinput@     for gen in gens do|
  !gapprompt@>| !gapinput@       orb := Union(orb,List(orb,l->List(l,n->n^gen) mod 8));|
  !gapprompt@>| !gapinput@     od;|
  !gapprompt@>| !gapinput@   end;;|
  !gapprompt@gap>| !gapinput@repeat|
  !gapprompt@>| !gapinput@     old := ShallowCopy(orb);|
  !gapprompt@>| !gapinput@     extend(); Print(Length(orb),"\n");|
  !gapprompt@>| !gapinput@   until orb = old;|
  7
  27
  97
  279
  573
  916
  1185
  1313
  1341
  1344
  1344
  !gapprompt@gap>| !gapinput@Length(Set(List(orb,l->l mod 4)));|
  120
  !gapprompt@gap>| !gapinput@last < 4^4;|
  true
  
\end{Verbatim}
 This shows that $G$ acts not 4\texttt{\symbol{45}}transitively
on{\nobreakspace}{\ensuremath{\mathbb Z}}. The corresponding calculation for
3\texttt{\symbol{45}}tuples looks as follows: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@orb := [[0,1,2]];;|
  !gapprompt@gap>| !gapinput@repeat|
  !gapprompt@>| !gapinput@     old := ShallowCopy(orb);|
  !gapprompt@>| !gapinput@     extend(); Print(Length(orb),"\n");|
  !gapprompt@>| !gapinput@   until orb = old;|
  7
  27
  84
  207
  363
  459
  503
  512
  512
  !gapprompt@gap>| !gapinput@Length(Set(List(orb,l->l mod 4)));|
  64
  !gapprompt@gap>| !gapinput@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$\texttt{\symbol{45}}transitivity. }

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

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

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

 Enter \texttt{AssignGlobals(LoadRCWAExamples().SlowlyContractingMappings);} in order to assign the global variables defined in this section. }

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

 Enter \texttt{AssignGlobals(LoadRCWAExamples().CollatzMapping);} in order to assign the global variables defined in this section. }

  
\section{\textcolor{Chapter }{Two examples by Matthews and Leigh}}\label{sec:MatthewsLeighExamples}
\logpage{[ 7, 9, 0 ]}
\hyperdef{L}{X7E8CD9B67ED78735}{}
{
  In \cite{MatthewsLeigh87}, K.{\nobreakspace}R.{\nobreakspace}Matthews and
G.{\nobreakspace}M.{\nobreakspace}Leigh have shown that two trajectories of
the following (surjective, but not injective) mappings are acyclic
(mod{\nobreakspace}$x$) and divergent: 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@x := Indeterminate(GF(4),1);; SetName(x,"x");A
  !gapprompt@gap>A !gapinput@R := PolynomialRing(GF(2),1);A
  GF(2)[x]
  !gapprompt@gap>A !gapinput@ML1 := RcwaMapping(R,x,[[1,0,x],[(x+1)^3,1,x]]*One(R));;A
  !gapprompt@gap>A !gapinput@ML2 := RcwaMapping(R,x,[[1,0,x],[(x+1)^2,1,x]]*One(R));;A
  !gapprompt@gap>A !gapinput@Display(ML1);A
  
  Rcwa mapping of GF(2)[x] with modulus x
  
          /
          | P/x                     if P in 0(x)
   P |-> <  ((x^3+x^2+x+1)*P + 1)/x if P in 1(x)
          |
          java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@Display(ML2);A
  
  Rcwa mapping of GF(2)[x] with modulus x
  
          /
          | P/x               if P in 0(x)
   P |-> <  ((x^2+1)*P + 1)/x if P in 1(x)
          |
          java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@List([ML1,ML2],IsSurjective);A
  [ true, true ]
  !gapprompt@gap>A !gapinput@List([ML1,ML2],IsInjective);A
  [ false, false ]
  !gapprompt@gap>A !gapinput@traj1 := Trajectory(ML1,One(R),16);A
  [ 1, x^2+x+1, x^4+x^2+x, x^3+x+1, x^5+x^4+x^2, x^4+x^3+x, x^3+x^2+1, 
    x^5+x^2+1, x^7+x^6+x^5+x^3+1, x^9+x^7+x^6+x^5+x^3+x+1, 
    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+1, x^11+x^8+x^7+x^6+x^4+x+1, 
    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 ]
  !gapprompt@gap>A !gapinput@traj2 := Trajectory(ML2,(x^3+x+1)*One(R),16);A
  [ x^3+x+1, x^4+x+1, x^5+x^3+x^2+x+1, x^6+x^3+1, x^7+x^5+x^4+x^2+x, 
    x^6+x^4+x^3+x+1, x^7+x^4+x^3+x+1, x^8+x^6+x^5+x^4+x^3+x+1, 
    x^9+x^6+x^3+x+1, x^10+x^8+x^7+x^5+x^4+x+1, 
    x^11+x^8+x^7+x^5+x^4+x^3+x^2+x+1, x^12+x^10+x^9+x^8+x^7+x^5+1, 
    x^13+x^10+x^7+x^4+x, x^12+x^9+x^6+x^3+1, 
    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+1 ]
  
\end{Verbatim}
 The pattern which Matthews and Leigh used to show the divergence of the above
trajectories can be recognized easily by looking at the corresponding Markov
chains with the two states 0{\nobreakspace}mod{\nobreakspace}$x$ and 1{\nobreakspace}mod{\nobreakspace}$x$: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@traj1modx := Trajectory(ML1,One(R),400,x);;|
  !gapprompt@gap>| !gapinput@traj2modx := Trajectory(ML2,(x^3+x+1)*One(R),600,x);;|
  !gapprompt@gap>| !gapinput@List(traj1modx{[1..150]},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 ]
  !gapprompt@gap>| !gapinput@List(traj2modx{[1..150]},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 ]
  
\end{Verbatim}
 What is important here are the lengths of the intervals between two changes
from one state to the other: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ChangePoints := l->Filtered([1..Length(l)-1],pos->l[pos]<>l[pos+1]);;|
  !gapprompt@gap>| !gapinput@Diffs := l->List([1..Length(l)-1],pos->l[pos+1]-l[pos]);;|
  !gapprompt@gap>| !gapinput@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 ]
  !gapprompt@gap>| !gapinput@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 ]
  !gapprompt@gap>| !gapinput@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. 

 Enter \texttt{AssignGlobals(LoadRCWAExamples().MatthewsLeigh);} in order to assign the global variables defined in this section. }

  
\section{\textcolor{Chapter }{Orders of commutators}}\label{sec:OrdersOfCommutators}
\logpage{[ 7, 10, 0 ]}
\hyperdef{L}{X854E9F65817E4F63}{}
{
  We enter some wild rcwa permutation: 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@u := RcwaMapping([[3,0,5],[9,1,5],[3,-1,5],[9,-2,5],[9,4,5]]);;A
  !gapprompt@gap>A !gapinput@IsTame(u);;A
  !gapprompt@gap>A !gapinput@Display(u);A
  
  Wild rcwa permutation of Z with modulus 5
  
          /
          | 3n/5     if n in 0(5)
          | (9n+1)/5 if n in 1(5)
   n |-> <  (3n-1)/5 if n in 2(5)
          | (9n-2)/5 if n in 3(5)
          | (9n+4)/5 if n in 4(5)
          java.lang.NullPointerException
  
\end{Verbatim}
 We would like to compute the order of $[u,n \mapsto n + k]$ and $[u^2,n \mapsto n + k]$ for different values of{\nobreakspace}$k$: 
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=Example]
  
  @gapprompt|gap>A @gapinput|nu := ClassShift(0,1);; # n -> n + 1A
  @gapprompt|gap>A @gapinput|l := Filtered([0..100],k->IsTame(Comm(u,nu^k)));A
  [ 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 ]
  @gapprompt|gap>A @gapinput|List(l,k->Order(Comm(u,nu^k)));A
  [ 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 ]
  @gapprompt|gap>A @gapinput|u2 := u^2;A
  <wild rcwa permutation of Z with modulus 25>
  @gapprompt|gap>A @gapinput|Filtered([1..16],k->IsTame(Comm(u2,nu^k))); # k<15->[u^2,nu^k] wild!A
  [ 15 ]
  @gapprompt|gap>A @gapinput|Order(Comm(u2,nu^15));A
  infinity
  @gapprompt|gap>A @gapinput|u2nu17 := Comm(u2,nu^17);A
  <rcwa permutation of Z with modulus 81>
  @gapprompt|gap>A @gapinput|cycs := ShortCycles(u2nu17,[-100..100],100);;A
  @gapprompt|gap>A @gapinput|List(cycs,Length);A
  [ 72, 73, 72, 72, 72, 73, 72, 72, 73, 72, 72, 73, 72, 72, 73, 72, 72, 
    73, 72, 72, 73, 72, 72 ]
  @gapprompt|gap>A @gapinput|Lcm(last);A
  5256
  @gapprompt|gap>A @gapinput|u2nu17^5256; # This element has indeed order 2^3*3^2*73 = 5256.A
  IdentityMapping( Integers )
  @gapprompt|gap>A @gapinput|u2nu18 := Comm(u2,nu^18);A
  <rcwa permutation of Z with modulus 81>
  @gapprompt|gap>A @gapinput|cycs := ShortCycles(u2nu18,[-100..100],100);;A
  @gapprompt|gap>A @gapinput|List(cycs,Length);A
  [ 21, 22, 22, 22, 21, 22, 22, 21, 22, 22, 21, 22, 21, 22, 22, 21, 22, 
    22, 21, 22, 22, 21, 22 ]
  @gapprompt|gap>A @gapinput|Lcm(last);A
  462
  @gapprompt|gap>A @gapinput|u2nu18^462; # This is an element of order 2*3*7*11 = 462.A
  IdentityMapping( Integers )
  @gapprompt|gap>A @gapinput|List([Comm(u2,nu^20),Comm(u2,nu^25),Comm(u2,nu^30)],Order);A
  [ 29, 9, 15 ]
  
\end{Verbatim}
 We observe that our commutators have various different orders, and that the
prime factors of these orders are not all ``very small''. 

 Enter \texttt{AssignGlobals(LoadRCWAExamples().CollatzlikePerms);} in order to assign the global variables defined in this section. }

  
\section{\textcolor{Chapter }{ An infinite subgroup of CT(GF(2)[x]) with many torsion elements }}\label{sec:OddNumberOfGens_FiniteOrder}
\logpage{[ 7, 11, 0 ]}
\hyperdef{L}{X7F085B867D799293}{}
{
  In this section, we have a look at the following subgroup of CT(GF(2)[x]): 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@x := Indeterminate(GF(2));; SetName(x,"x");A
  !gapprompt@gap>A !gapinput@R := PolynomialRing(GF(2),1);A
  GF(2)[x]
  !gapprompt@gap>A !gapinput@a := ClassTransposition(0,x,1,x);;A
  !gapprompt@gap>A !gapinput@b := ClassTransposition(0,x^2+1,1,x^2+1);;A
  !gapprompt@gap>A !gapinput@c := ClassTransposition(1,x,0,x^2+x);;A
  !gapprompt@gap>A !gapinput@G := Group(a,b,c);A
  <rcwa group over GF(2)[x] with 3 generators>
  !gapprompt@gap>A !gapinput@Display(G);A
  
  Rcwa group over GF(2)[x], generated by
  
  [
  Rcwa permutation of GF(2)[x]: P -> P + Z(2)^0
  
  Rcwa permutation of GF(2)[x] with modulus x^2+1, of order 2
  
          /
          | P + 1 if P in 0(x^2+1) U 1(x^2+1)
   P |-> <  P     if P in x(x^2+1) U x+1(x^2+1)
          |
          java.lang.NullPointerException
  
  
  Rcwa permutation of GF(2)[x] with modulus x^2+x, of order 2
  
          /
          | (x+1)*P + x+1   if P in 1(x)
   P |-> <  (P + x+1)/(x+1) if P in 0(x^2+x)
          | P               if P in x(x^2+x)
          java.lang.NullPointerException
  
  ]
  
\end{Verbatim}
 We can easily find 2 normal subgroups of{\nobreakspace}\texttt{G}: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@N1 := Subgroup(G,[a*b,a*c]);|
  <rcwa group over GF(2)[x] with 2 generators>
  !gapprompt@gap>| !gapinput@IsNormal(G,N1);|
  true
  !gapprompt@gap>| !gapinput@Index(G,N1);|
  2
  !gapprompt@gap>| !gapinput@G/N1;|
  Group([ (1,2), (1,2), (1,2) ])
  !gapprompt@gap>| !gapinput@N2 := Subgroup(G,[a*b*c,a*c]);;|
  !gapprompt@gap>| !gapinput@IsNormal(G,N2);|
  true
  !gapprompt@gap>| !gapinput@IsSubgroup(N1,N2);|
  false
  
\end{Verbatim}
 Products of even numbers of generators of{\nobreakspace}\texttt{G} may have infinite order. For example, we have 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Order(a*b);|
  2
  !gapprompt@gap>| !gapinput@Order(a*c);|
  infinity
  !gapprompt@gap>| !gapinput@Order(b*c);|
  infinity
  
\end{Verbatim}
 We would like to have a look at orders of products of odd numbers of
generators. In order to restrict our considerations to ``essentially different'' products (as far as we can easily do this), we use the following auxiliary
function: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=GAP code]
  
  NormedWords := function ( F, lng )
  
    local  words, gens, tuples, w;
  
    gens   := GeneratorsOfGroup(F);
    tuples := EnumeratorOfTuples([1..3],lng);
    words  := [];
  
    for w in tuples do
      if    (w[1] = 1 or not 1 in w)
        and PositionSublist(w,[1,1]) = fail
        and PositionSublist(w,[2,2]) = fail
        and PositionSublist(w,[3,3]) = fail
        and PositionSublist(w,[2,1]) = fail
        and w[1] < w[lng]
        and w{[1,lng]} <> [1,2]
        and (w{[1..3]} = [1,2,3] or PositionSublist(w,[1,2,3]) = fail)
      then Add(words,w); fi;
    od;
  
    words := List(words,word->Product(List(word,i->gens[i])));
    return words;
  end;
  
\end{Verbatim}
 Now let's compute the possible orders of products of 3, 5, 7 or 9 generators: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@F := FreeGroup("a","b","c");;|
  !gapprompt@gap>| !gapinput@phi := EpimorphismByGenerators(F,G);|
  [ a, b, c ] -> 
  [ ClassTransposition(0,x,1,x), ClassTransposition(0,x^2+1,1,x^2+1), 
    ClassTransposition(1,x,0,x^2+x) ]
  !gapprompt@gap>| !gapinput@B3 := NormedWords(F,3);|
  [ a*b*c ]
  !gapprompt@gap>| !gapinput@B3 := List(B3,g->g^phi);|
  [ <rcwa permutation of GF(2)[x] with modulus x^3+x> ]
  !gapprompt@gap>| !gapinput@List(B3,Order);|
  [ 20 ]
  !gapprompt@gap>| !gapinput@B5 := NormedWords(F,5);|
  [ a*b*c*a*c, a*b*c*b*c ]
  !gapprompt@gap>| !gapinput@B5 := List(B5,g->g^phi);|
  [ <rcwa permutation of GF(2)[x] with modulus x^3+x>, 
    <rcwa permutation of GF(2)[x] with modulus x^4+x^3+x^2+x> ]
  !gapprompt@gap>| !gapinput@List(B5,Order);|
  [ 12, 12 ]
  !gapprompt@gap>| !gapinput@B7 := NormedWords(F,7);|
  [ a*b*c*a*c*a*c, a*b*c*a*c*b*c, a*b*c*b*c*a*c, a*b*c*b*c*b*c ]
  !gapprompt@gap>| !gapinput@B7 := List(B7,g->g^phi);|
  [ <rcwa permutation of GF(2)[x] with modulus x^4+x^3+x^2+x>, 
    <rcwa permutation of GF(2)[x] with modulus x^5+x>, 
    <rcwa permutation of GF(2)[x] with modulus x^4+x^3+x^2+x>, 
    <rcwa permutation of GF(2)[x] with modulus x^5+x> ]
  !gapprompt@gap>| !gapinput@List(B7,Order);|
  [ 12, 12, 12, 30 ]
  !gapprompt@gap>| !gapinput@B9 := NormedWords(F,9);|
  [ a*b*c*a*b*c*a*b*c, a*b*c*a*c*a*c*a*c, a*b*c*a*c*a*c*b*c, a*b*c*a*c*b*c*a*c, 
    a*b*c*a*c*b*c*b*c, a*b*c*b*c*a*c*a*c, a*b*c*b*c*a*c*b*c, a*b*c*b*c*b*c*a*c, 
    a*b*c*b*c*b*c*b*c ]
  !gapprompt@gap>| !gapinput@B9 := List(B9,g->g^phi);;|
  !gapprompt@gap>| !gapinput@List(B9,Order);|
  [ 20, 4, 30, 12, 42, 30, 4, 42, 12 ]
  
\end{Verbatim}
 Enter \texttt{AssignGlobals(LoadRCWAExamples().OddNumberOfGens{\textunderscore}FiniteOrder);} in order to assign the global variables defined in this section. }

  
\section{\textcolor{Chapter }{An abelian rcwa group over a polynomial ring}}\label{sec:AbelianGroupOverPolynomialRing}
\logpage{[ 7, 12, 0 ]}
\hyperdef{L}{X7A8605E680F664BF}{}
{
  We enter a 2\texttt{\symbol{45}}generated abelian wild rcwa group over GF(4)[$x$]: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@x := Indeterminate(GF(4),1);; SetName(x,"x");|
  !gapprompt@gap>| !gapinput@R := PolynomialRing(GF(4),1);|
  GF(2^2)[x]
  !gapprompt@gap>| !gapinput@e := One(GF(4));;|
  !gapprompt@gap>| !gapinput@p := x^2 + x + e;;    q := x^2 + e;;|
  !gapprompt@gap>| !gapinput@r := x^2 + x + Z(4);; s := x^2 + x + Z(4)^2;;|
  !gapprompt@gap>| !gapinput@cg := List( AllResidues(R,x^2), pol -> [ p, p * pol mod q, q ] );;|
  !gapprompt@gap>| !gapinput@ch := List( AllResidues(R,x^2), pol -> [ r, r * pol mod s, s ] );;|
  !gapprompt@gap>| !gapinput@g := RcwaMapping( R, q, cg );|
  <rcwa mapping of GF(2^2)[x] with modulus x^2+1>
  !gapprompt@gap>| !gapinput@h := RcwaMapping( R, s, ch );|
  <rcwa mapping of GF(2^2)[x] with modulus x^2+x+Z(2^2)^2>
  !gapprompt@gap>| !gapinput@List([g,h],IsTame);|
  [ false, false ]
  !gapprompt@gap>| !gapinput@G := Group(g,h);|
  <rcwa group over GF(2^2)[x] with 2 generators>
  !gapprompt@gap>| !gapinput@IsAbelian(G);|
  true
  !gapprompt@gap>| !gapinput@IsTame(G);|
  false
  
\end{Verbatim}
 It is easy to see that all orbits on GF(4)[$x$] under the action of \texttt{G} are finite. 

 Now we compute the action of the group \texttt{G} on one of its orbits, and make some statistics of the orbits of \texttt{G} containing polynomials of degree less than{\nobreakspace}4: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@orb := Orbit(G,x^5);|
  [ x^5, x^5+x^4+x^2+1, 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+1, x^5+x^2+Z(2^2)*x, x^5+x^4+Z(2^2)^2*x+Z(2^2)^2 ]
  !gapprompt@gap>| !gapinput@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) ])
  !gapprompt@gap>| !gapinput@IsAbelian(H); # check ...|
  true
  !gapprompt@gap>| !gapinput@IsCyclic(H);  # H, and therefore also G, is not cyclic|
  false
  !gapprompt@gap>| !gapinput@Exponent(H);|
  8
  !gapprompt@gap>| !gapinput@Collected(List(ShortOrbits(G,AllResidues(R,x^4),100),Length));|
  [ [ 1, 4 ], [ 2, 6 ], [ 4, 12 ], [ 8, 24 ] ]
  
\end{Verbatim}
 Changing the generators a little changes the structure of the group and its
action on the underlying ring a lot: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@cg[1][2] := cg[1][2] + (x^2 + e) * p * q;;|
  !gapprompt@gap>| !gapinput@ch[7][2] := ch[7][2] + x * r * s;;|
  !gapprompt@gap>| !gapinput@g := RcwaMapping( R, q, cg );; h := RcwaMapping( R, s, ch );;|
  !gapprompt@gap>| !gapinput@G := Group(g,h);|
  <rcwa group over GF(2^2)[x] with 2 generators>
  !gapprompt@gap>| !gapinput@IsAbelian(G);|
  false
  !gapprompt@gap>| !gapinput@Support(G);|
  GF(2^2)[x] \ [ 1, Z(2^2), Z(2^2)^2 ]
  !gapprompt@gap>| !gapinput@orb := Orbit(G,Zero(R));;|
  !gapprompt@gap>| !gapinput@Length(orb);|
  87
  !gapprompt@gap>| !gapinput@StructureDescription(Action(G,orb));|
  "A87"
  !gapprompt@gap>| !gapinput@Collected(List(orb,DegreeOfLaurentPolynomial));|
  [ [ -infinity, 1 ], [ 1, 2 ], [ 2, 4 ], [ 3, 16 ], [ 4, 64 ] ]
  !gapprompt@gap>| !gapinput@S := AllResidues(R,x^6);;|
  !gapprompt@gap>| !gapinput@orbs := ShortOrbits(G,S,-1:finite);;|
  !gapprompt@gap>| !gapinput@List(orbs,Length);|
  [ 87, 1, 1, 1, 2, 2, 2, 2, 2, 4, 4, 4, 20, 4, 12, 4, 20, 4, 4, 12, 8, 8, 
    48, 48, 16, 8, 8, 56, 8, 88, 8, 8, 8, 400, 16, 48, 16, 16, 16, 80, 16, 
    16, 16, 96, 32, 192, 32, 16, 16, 416, 16, 48, 16, 16, 880, 16, 16, 16, 
    16, 16, 16, 16, 16, 16, 848, 16, 16, 32, 16, 16, 16, 16, 16, 16, 16 ]
  !gapprompt@gap>| !gapinput@Position(last,880);|
  55
  !gapprompt@gap>| !gapinput@Set(orbs[55],DegreeOfLaurentPolynomial); # all elm's have same degree|
  [ 5 ]
  !gapprompt@gap>| !gapinput@H := Action(G,orbs[55]);;|
  !gapprompt@gap>| !gapinput@IsPrimitive(H,MovedPoints(H));|
  false
  !gapprompt@gap>| !gapinput@List(Blocks(H,MovedPoints(H)),Length);|
  [ 110, 110, 110, 110, 110, 110, 110, 110 ]
  
\end{Verbatim}
 Enter \texttt{AssignGlobals(LoadRCWAExamples().AbelianGroupOverPolynomialRing);} in order to assign the global variables defined in this section. }

  
\section{\textcolor{Chapter }{Checking for solvability}}\label{sec:CheckingForSolvability}
\logpage{[ 7, 13, 0 ]}
\hyperdef{L}{X78DFE4B4821E07A6}{}
{
  Presently there is no general method available for testing wild rcwa groups
for solvability. However, sometimes the question for solvability can be
answered anyway. In the example below, the idea is to find a
subgroup{\nobreakspace}\mbox{\texttt{\mdseries\slshape U}} which acts on a finite set{\nobreakspace}\mbox{\texttt{\mdseries\slshape S}} of integers, and which induces on{\nobreakspace}\mbox{\texttt{\mdseries\slshape S}} a non\texttt{\symbol{45}}solvable finite permutation group: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@a := RcwaMapping([[3,0,2],[3, 1,4],[3,0,2],[3,-1,4]]);;|
  !gapprompt@gap>| !gapinput@b := RcwaMapping([[3,0,2],[3,13,4],[3,0,2],[3,-1,4]]);;|
  !gapprompt@gap>| !gapinput@G := Group(a,b);;|
  !gapprompt@gap>| !gapinput@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 ] ]
  !gapprompt@gap>| !gapinput@S := [ 4, 5, 6, 7, 10, 15 ];;|
  !gapprompt@gap>| !gapinput@Cycle(Comm(a,b),4);|
  [ 4, 7, 10, 15, 5, 6 ]
  !gapprompt@gap>| !gapinput@elm := RepresentativeAction(G,S,Permuted(S,(1,4)),OnTuples);|
  <rcwa permutation of Z with modulus 81>
  !gapprompt@gap>| !gapinput@List(S,n->n^elm);|
  [ 7, 5, 6, 4, 10, 15 ]
  !gapprompt@gap>| !gapinput@U := Group(Comm(a,b),elm);|
  <rcwa group over Z with 2 generators>
  !gapprompt@gap>| !gapinput@Action(U,S);|
  Group([ (1,4,5,6,2,3), (1,4) ])
  !gapprompt@gap>| !gapinput@IsNaturalSymmetricGroup(last);|
  true
  
\end{Verbatim}
 Thus the subgroup \mbox{\texttt{\mdseries\slshape U}} induces on \mbox{\texttt{\mdseries\slshape S}} a natural symmetric group of degree{\nobreakspace}6. Therefore the
group{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} is not solvable. We conclude this example by factoring the group element \mbox{\texttt{\mdseries\slshape elm}} into generators: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@F := FreeGroup("a","b");|
  <free group on the generators [ a, b ]>
  !gapprompt@gap>| !gapinput@RepresentativeActionPreImage(G,S,Permuted(S,(1,4)),OnTuples,F);|
  a^-2*b^-2*a*b*a^-1*b*a*b^-2*a
  !gapprompt@gap>| !gapinput@a^-2*b^-2*a*b*a^-1*b*a*b^-2*a = elm;|
  true
  
\end{Verbatim}
 Enter \texttt{AssignGlobals(LoadRCWAExamples().CheckingForSolvability);} in order to assign the global variables defined in this section. }

  
\section{\textcolor{Chapter }{Some examples over (semi)localizations of the integers}}\label{sec:LocalExample}
\logpage{[ 7, 14, 0 ]}
\hyperdef{L}{X783D54DC7A646273}{}
{
  We start with something one can observe when trying to ``transfer'' an rcwa mapping from the ring of integers to one of its localizations: 
\begin{Verbatim}[commandchars=@|C,fontsize=\small,frame=single,label=Example]
  
  @gapprompt|gap>C @gapinput|a := RcwaMapping([[3,0,2],[3,1,4],[3,0,2],[3,-1,4]]);;C
  @gapprompt|gap>C @gapinput|IsBijective(a);C
  true
  @gapprompt|gap>C @gapinput|a2 := LocalizedRcwaMapping(a,2);C
  <rcwa mapping of Z_( 2 ) with modulus 4>
  @gapprompt|gap>C @gapinput|IsSurjective(a2); # As expectedC
  true
  @gapprompt|gap>C @gapinput|IsInjective(a2); # Why not??C
  false
  @gapprompt|gap>C @gapinput|0^a2;C
  0
  @gapprompt|gap>C @gapinput|(1/3)^a2; # That's the reason!C
  0
  
\end{Verbatim}
 The above can also be explained easily by pointing out that the modulus of the
inverse of \texttt{a} is{\nobreakspace}3, and that 3 is a unit of{\nobreakspace}${\ensuremath{\mathbb Z}}_{(2)}$. Moving to ${\ensuremath{\mathbb Z}}_{(2,3)}$ solves this problem: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@a23 := SemilocalizedRcwaMapping(a,[2,3]);|
  <rcwa mapping of Z_( 2, 3 ) with modulus 4>
  !gapprompt@gap>| !gapinput@IsBijective(a23);|
  true
  
\end{Verbatim}
 We get additional finite cycles, e.g.: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@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 ] ]
  !gapprompt@gap>| !gapinput@List(last,Length);|
  [ 1, 3, 11, 1, 2, 3, 34, 5 ]
  !gapprompt@gap>| !gapinput@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 ] ]
  !gapprompt@gap>| !gapinput@List(last,Length);|
  [ 1, 2, 6, 1, 2, 5 ]
  
\end{Verbatim}
 However the structure of a group with prime set $\mathbb{P}$ remains invariant under the ``transfer'' from {\ensuremath{\mathbb Z}} to{\nobreakspace}${\ensuremath{\mathbb Z}}_{(\mathbb{P})}$. 

 ``Transferring'' a non\texttt{\symbol{45}}invertible rcwa mapping from the ring of integers to
some of its (semi)localizations can also turn it into an invertible one: 
\begin{Verbatim}[commandchars=!@E,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>E !gapinput@v := RcwaMapping([[6,0,1],[1,-7,2],[6,0,1],[1,-1,1],E
  !gapprompt@>E !gapinput@                     [6,0,1],[1, 1,2],[6,0,1],[1,-1,1]]);;E
  !gapprompt@gap>E !gapinput@Display(v);E
  
  Rcwa mapping of Z with modulus 8
  
          /
          | 6n      if n in 0(2)
          | n-1     if n in 3(4)
   n |-> <  (n-7)/2 if n in 1(8)
          | (n+1)/2 if n in 5(8)
          |
          java.lang.NullPointerException
  
  !gapprompt@gap>E !gapinput@IsInjective(v);E
  true
  !gapprompt@gap>E !gapinput@IsSurjective(v);E
  false
  !gapprompt@gap>E !gapinput@Image(v);E
  Z \ 4(12) U 8(12)
  !gapprompt@gap>E !gapinput@Difference(Integers,last);E
  4(12) U 8(12)
  !gapprompt@gap>E !gapinput@v2 := LocalizedRcwaMapping(v,2);E
  <rcwa mapping of Z_( 2 ) with modulus 8>
  !gapprompt@gap>E !gapinput@IsBijective(v2);E
  true
  !gapprompt@gap>E !gapinput@Display(v2^-1);E
  
  Rcwa permutation of Z_( 2 ) with modulus 4
  
          /
          | 1/3 n / 2 if n in 0(4)
          | 2 n + 7   if n in 1(4)
   n |-> <  n + 1     if n in 2(4)
          | 2 n - 1   if n in 3(4)
          |
          java.lang.NullPointerException
  
  !gapprompt@gap>E !gapinput@S := ResidueClass(Z_pi(2),2,0);; l := [S];;E
  !gapprompt@gap>E !gapinput@for i in [1..10] do Add(l,l[Length(l)]^v2); od;E
  !gapprompt@gap>E !gapinput@l; # Visibly v2 is wild ...E
  [ 0(2), 0(4), 0(8), 0(16), 0(32), 0(64), 0(128), 0(256), 0(512),
    0(1024), 0(2048) ]
  !gapprompt@gap>E !gapinput@w2 := RcwaMapping(Z_pi(2),[[1,0,2],[2,-1,1],[1,1,1],[2,-1,1]]);;E
  !gapprompt@gap>E !gapinput@v2w2 := Comm(v2,w2);; v2w2^-1;;E
  !gapprompt@gap>E !gapinput@Display(v2w2);E
  
  Rcwa permutation of Z_( 2 ) with modulus 8
  
          /
          | 3 n   if n in 2(4)
          | n + 4 if n in 1(8)
   n |-> <  n - 4 if n in 5(8)
          | n     if n in 0(4) U 3(4)
          |
          java.lang.NullPointerException
  
\end{Verbatim}
 Again, viewed as an rcwa mapping of the integers the commutator given at the
end of the example would not be surjective. 

 Enter \texttt{AssignGlobals(LoadRCWAExamples().Semilocals);} in order to assign the global variables defined in this section. }

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

  
\section{\textcolor{Chapter }{ The behaviour of the moduli of powers }}\label{sec:ModuliOfPowers}
\logpage{[ 7, 16, 0 ]}
\hyperdef{L}{X78D5DC93845CA6A0}{}
{
  We give some examples of how the series of the moduli of powers of a given
rcwa mapping of the integers can look like. 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@a := RcwaMapping([[3,0,2],[3, 1,4],[3,0,2],[3,-1,4]]);;A
  !gapprompt@gap>A !gapinput@List([0..4],i->Modulus(a^i));A
  [ 1, 4, 16, 64, 256 ]
  !gapprompt@gap>A !gapinput@e1 := RcwaMapping([[1,4,1],[2,0,1],[1,0,2],[2,0,1]]);;A
  !gapprompt@gap>A !gapinput@e2 := RcwaMapping([[1,4,1],[2,0,1],[1,0,2],[1,0,1],A
  !gapprompt@>A !gapinput@                      [1,4,1],[2,0,1],[1,0,1],[1,0,1]]);;A
  !gapprompt@gap>A !gapinput@List([e1,e2],Order);A
  [ infinity, infinity ]
  !gapprompt@gap>A !gapinput@List([1..20],i->Modulus(e1^i));A
  [ 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4 ]
  !gapprompt@gap>A !gapinput@List([1..20],i->Modulus(e2^i));A
  [ 8, 4, 8, 4, 8, 4, 8, 4, 8, 4, 8, 4, 8, 4, 8, 4, 8, 4, 8, 4 ]
  !gapprompt@gap>A !gapinput@Display(e2);A
  
  Rcwa permutation of Z with modulus 8, of order infinity
  
          /
          | n+4 if n in 0(4)
          | 2n  if n in 1(4)
   n |-> <  n/2 if n in 2(8)
          | n   if n in 3(4) U 6(8)
          |
          java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@e2^2 = Restriction(RcwaMapping([[1,2,1]]),RcwaMapping([[4,0,1]]));A
  true
  !gapprompt@gap>A !gapinput@g:=RcwaMapping([[2,2,1],[1, 4,1],[1,0,2],[2,2,1],[1,-4,1],[1,-2,1]]);;A
  !gapprompt@gap>A !gapinput@h:=RcwaMapping([[2,2,1],[1,-2,1],[1,0,2],[2,2,1],[1,-1,1],[1, 1,1]]);;A
  !gapprompt@gap>A !gapinput@List([0..7],i->Modulus(g^i));A
  [ 1, 6, 12, 12, 12, 12, 6, 1 ]
  !gapprompt@gap>A !gapinput@List([1..18],i->Modulus((g^3*h)^i));A
  [ 12, 6, 12, 12, 12, 6, 12, 6, 12, 12, 12, 6, 12, 6, 12, 12, 12, 6 ]
  !gapprompt@gap>A !gapinput@u := RcwaMapping([[3,0,5],[9,1,5],[3,-1,5],[9,-2,5],[9,4,5]]);;A
  !gapprompt@gap>A !gapinput@List([0..3],i->Modulus(u^i));A
  [ 1, 5, 25, 125 ]
  !gapprompt@gap>A !gapinput@v6 := RcwaMapping([[-1,2,1],[1,-1,1],[1,-1,1]]);;A
  !gapprompt@gap>A !gapinput@List([0..6],i->Modulus(v6^i));A
  [ 1, 3, 3, 3, 3, 3, 1 ]
  !gapprompt@gap>A !gapinput@w8 := RcwaMapping([[-1,3,1],[1,-1,1],[1,-1,1],[1,-1,1]]);;A
  !gapprompt@gap>A !gapinput@List([0..8],i->Modulus(w8^i));A
  [ 1, 4, 4, 4, 4, 4, 4, 4, 1 ]
  !gapprompt@gap>A !gapinput@z := RcwaMapping([[2,1,1],[1, 1,1],[2,-1,1],[2, -2,1],A
  !gapprompt@>A !gapinput@                     [1,6,2],[1, 1,1],[1,-6,2],[2,  5,1],A
  !gapprompt@>A !gapinput@                     [1,6,2],[1, 1,1],[1, 1,1],[2, -5,1],A
  !gapprompt@>A !gapinput@                     [1,0,1],[1,-4,1],[1, 0,1],[2,-10,1]]);;A
  !gapprompt@gap>A !gapinput@IsBijective(z);A
  true
  !gapprompt@gap>A !gapinput@List([0..25],i->Modulus(z^i));A
  [ 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 ]
  
\end{Verbatim}
 Enter \texttt{AssignGlobals(LoadRCWAExamples().ModuliOfPowers);} in order to assign the global variables defined in this section. }

  
\section{\textcolor{Chapter }{ Images and preimages under the Collatz mapping }}\label{sec:CollatzImagesAndPreImages}
\logpage{[ 7, 17, 0 ]}
\hyperdef{L}{X855A3CD88459958B}{}
{
  We have a look at the images of the residue class 1(2) under powers of the
Collatz mapping. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@T := RcwaMapping([[1,0,2],[3,1,2]]);;|
  !gapprompt@gap>| !gapinput@S0 := ResidueClass(Integers,2,1);;|
  !gapprompt@gap>| !gapinput@S1 := S0^T;|
  2(3)
  !gapprompt@gap>| !gapinput@S2 := S1^T;|
  1(3) U 8(9)
  !gapprompt@gap>| !gapinput@S3 := S2^T;|
  2(3) U 4(9)
  !gapprompt@gap>| !gapinput@S4 := S3^T;|
  Z \ 0(3) U 5(9)
  !gapprompt@gap>| !gapinput@S5 := S4^T;|
  Z \ 0(3) U 7(9)
  !gapprompt@gap>| !gapinput@S6 := S5^T;|
  Z \ 0(3)
  !gapprompt@gap>| !gapinput@S7 := S6^T;|
  Z \ 0(3)
  
\end{Verbatim}
 Thus the image gets stable after applying the mapping $T$ for the 6th time. Hence $T^6$ maps the residue class 1(2) surjectively onto the union of the residue classes
1(3) and 2(3), which $T$ stabilizes setwise. Now we would like to determine the preimages of 1(3) and
2(3) in 1(2) under $T^6$. The residue class 1(2) has to be the disjoint union of these sets. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@U := Intersection(PreImage(T^6,ResidueClass(Integers,3,1)),S0);|
  <union of 11 residue classes (mod 64)>
  !gapprompt@gap>| !gapinput@V := Intersection(PreImage(T^6,ResidueClass(Integers,3,2)),S0);|
  <union of 21 residue classes (mod 64)>
  !gapprompt@gap>| !gapinput@AsUnionOfFewClasses(U);|
  [ 1(64), 5(64), 7(64), 9(64), 21(64), 23(64), 29(64), 31(64), 49(64), 
    51(64), 59(64) ]
  !gapprompt@gap>| !gapinput@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) ]
  !gapprompt@gap>| !gapinput@Union(U,V) = S0 and Intersection(U,V) = [];  # consistency check|
  true
  
\end{Verbatim}
 The images of the residue class 0(3) under powers of{\nobreakspace}$T$ look as follows: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@S0 := ResidueClass(Integers,3,0);|
  0(3)
  !gapprompt@gap>| !gapinput@S1 := S0^T;|
  0(3) U 5(9)
  !gapprompt@gap>| !gapinput@S2 := S1^T;|
  0(3) U 5(9) U 7(9) U 8(27)
  !gapprompt@gap>| !gapinput@S3 := S2^T;|
  <union of 20 residue classes (mod 27) (6 classes)>
  !gapprompt@gap>| !gapinput@S4 := S3^T;|
  <union of 73 residue classes (mod 81)>
  !gapprompt@gap>| !gapinput@S5 := S4^T;|
  Z \ 10(81) U 37(81)
  !gapprompt@gap>| !gapinput@S6 := S5^T;|
  Integers
  !gapprompt@gap>| !gapinput@S7 := S6^T;|
  Integers
  
\end{Verbatim}
 Thus every integer is the image of a multiple of{\nobreakspace}3
under{\nobreakspace}$T^6$. This means that it would be sufficient to prove the $3n+1$ conjecture for multiples of{\nobreakspace}3. We can obtain the corresponding
result for multiples of{\nobreakspace}5 as follows: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@S := [ResidueClass(Integers,5,0)];|
  [ 0(5) ]
  !gapprompt@gap>| !gapinput@for i in [1..12] do Add(S,S[i]^T); od;|
  !gapprompt@gap>| !gapinput@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)
  !gapprompt@gap>| !gapinput@Union(S[13],ResidueClass(Integers,3,0));|
  Integers
  !gapprompt@gap>| !gapinput@ 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}
 Enter \texttt{AssignGlobals(LoadRCWAExamples().CollatzMapping);} in order to assign the global variables defined in this section. }

  
\section{\textcolor{Chapter }{ An extension of the Collatz mapping T to a permutation of ${\ensuremath{\mathbb Z}}^2$ }}\label{sec:Sigma_T}
\logpage{[ 7, 18, 0 ]}
\hyperdef{L}{X84B6A498838A5509}{}
{
  The Collatz mapping{\nobreakspace}$T$ is surjective, but not injective: 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@T := RcwaMapping([[1,0,2],[3,1,2]]);;A
  !gapprompt@gap>A !gapinput@Display(T);A
  
  Rcwa mapping of Z with modulus 2
  
          /
          | n/2      if n in 0(2)
   n |-> <  (3n+1)/2 if n in 1(2)
          |
          java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@IsInjective(T); IsSurjective(T);A
  false
  true
  !gapprompt@gap>A !gapinput@PreImages(T,2);A
  [ 1, 4 ]
  
\end{Verbatim}
 Often, dealing with rcwa permutations is easier. Indeed the Collatz
mapping{\nobreakspace}$T$ can be extended in natural ways to permutations of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$. For example, the following permutation acts on the second coordinate just
like{\nobreakspace}$T$: 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@Sigma_T := RcwaMapping( Integers^2, [[1,0],[0,6]],A
  !gapprompt@>A !gapinput@                           [[[[2,0],[0,1]],[0,0],2],A
  !gapprompt@>A !gapinput@                            [[[4,0],[0,3]],[2,1],2],A
  !gapprompt@>A !gapinput@                            [[[2,0],[0,1]],[0,0],2],A
  !gapprompt@>A !gapinput@                            [[[4,0],[0,3]],[2,1],2],A
  !gapprompt@>A !gapinput@                            [[[4,0],[0,1]],[0,0],2],A
  !gapprompt@>A !gapinput@                            [[[4,0],[0,3]],[2,1],2]] );A
  <rcwa mapping of Z^2 with modulus (1,0)Z+(0,6)Z>
  !gapprompt@gap>A !gapinput@IsBijective(Sigma_T);A
  true
  !gapprompt@gap>A !gapinput@Display(Sigma_T);A
  
  Rcwa permutation of Z^2 with modulus (1,0)Z+(0,6)Z
  
              /
              | (2m+1,(3n+1)/2) if (m,n) in (0,1)+(1,0)Z+(0,2)Z
              | (m,n/2)         if (m,n) in (0,0)+(1,0)Z+(0,6)Z U 
   (m,n) |-> <                              (0,2)+(1,0)Z+(0,6)Z
              | (2m,n/2)        if (m,n) in (0,4)+(1,0)Z+(0,6)Z
              |
              java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@Display(Sigma_T^-1);A
  
  Rcwa permutation of Z^2 with modulus (2,0)Z+(0,3)Z
  
              /
              | (m,2n)             if (m,n) in (0,0)+(1,0)Z+(0,3)Z U 
              |                                (0,1)+(1,0)Z+(0,3)Z
   (m,n) |-> <  (m/2,2n)           if (m,n) in (0,2)+(2,0)Z+(0,3)Z
              | ((m-1)/2,(2n-1)/3) if (m,n) in (1,2)+(2,0)Z+(0,3)Z
              |
              java.lang.NullPointerException
  
\end{Verbatim}
 Now, the $3n+1$ conjecture is equivalent to the assertion that the line $n=4$ is a set of representatives for the cycles of \texttt{Sigma{\textunderscore}T} on the half plane $n > 0$. 

 Let's have a look at a part of a cycle of \texttt{Sigma{\textunderscore}T}: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Trajectory(Sigma_T,[0,27],75);|
  [ [ 0, 27 ], [ 1, 41 ], [ 3, 62 ], [ 3, 31 ], [ 7, 47 ], [ 15, 71 ], 
    [ 31, 107 ], [ 63, 161 ], [ 127, 242 ], [ 127, 121 ], [ 255, 182 ], 
    [ 255, 91 ], [ 511, 137 ], [ 1023, 206 ], [ 1023, 103 ], 
    [ 2047, 155 ], [ 4095, 233 ], [ 8191, 350 ], [ 8191, 175 ], 
    [ 16383, 263 ], [ 32767, 395 ], [ 65535, 593 ], [ 131071, 890 ], 
    [ 131071, 445 ], [ 262143, 668 ], [ 262143, 334 ], [ 524286, 167 ], 
    [ 1048573, 251 ], [ 2097147, 377 ], [ 4194295, 566 ], [ 4194295, 283 ], 
    [ 8388591, 425 ], [ 16777183, 638 ], [ 16777183, 319 ], 
    [ 33554367, 479 ], [ 67108735, 719 ], [ 134217471, 1079 ], 
    [ 268434943, 1619 ], [ 536869887, 2429 ], [ 1073739775, 3644 ], 
    [ 1073739775, 1822 ], [ 2147479550, 911 ], [ 4294959101, 1367 ], 
    [ 8589918203, 2051 ], [ 17179836407, 3077 ], [ 34359672815, 4616 ], 
    [ 34359672815, 2308 ], [ 68719345630, 1154 ], [ 68719345630, 577 ], 
    [ 137438691261, 866 ], [ 137438691261, 433 ], [ 274877382523, 650 ], 
    [ 274877382523, 325 ], [ 549754765047, 488 ], [ 549754765047, 244 ], 
    [ 1099509530094, 122 ], [ 1099509530094, 61 ], [ 2199019060189, 92 ], 
    [ 2199019060189, 46 ], [ 4398038120378, 23 ], [ 8796076240757, 35 ], 
    [ 17592152481515, 53 ], [ 35184304963031, 80 ], [ 35184304963031, 40 ], 
    [ 70368609926062, 20 ], [ 70368609926062, 10 ], [ 140737219852124, 5 ], 
    [ 281474439704249, 8 ], [ 281474439704249, 4 ], [ 562948879408498, 2 ], 
    [ 562948879408498, 1 ], [ 1125897758816997, 2 ], 
    [ 1125897758816997, 1 ], [ 2251795517633995, 2 ], 
    [ 2251795517633995, 1 ] ]
  !gapprompt@gap>| !gapinput@Trajectory(Sigma_T^-1,[0,27],20);|
  [ [ 0, 27 ], [ 0, 54 ], [ 0, 108 ], [ 0, 216 ], [ 0, 432 ], [ 0, 864 ], 
    [ 0, 1728 ], [ 0, 3456 ], [ 0, 6912 ], [ 0, 13824 ], [ 0, 27648 ], 
    [ 0, 55296 ], [ 0, 110592 ], [ 0, 221184 ], [ 0, 442368 ], 
    [ 0, 884736 ], [ 0, 1769472 ], [ 0, 3538944 ], [ 0, 7077888 ], 
    [ 0, 14155776 ] ]
  
\end{Verbatim}
 While it seems easy to make conjectures regarding the behaviour of cycles of \texttt{Sigma{\textunderscore}T}, obtaining results on it is apparently hard. We observe however that \texttt{Sigma{\textunderscore}T} can be written as a product of two permutations of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ whose cycles can be described easily: 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@a := RcwaMapping(Integers^2,[[1,0],[0,2]],[[[[4,0],[0,1]],[0, 0],2],A
  !gapprompt@>A !gapinput@                                              [[[4,0],[0,1]],[2,-1],2]]);A
  <rcwa mapping of Z^2 with modulus (1,0)Z+(0,2)Z>
  !gapprompt@gap>A !gapinput@b := a^-1*Sigma_T;A
  <rcwa permutation of Z^2 with modulus (2,0)Z+(0,3)Z>
  !gapprompt@gap>A !gapinput@Display(a);A
  
  Rcwa permutation of Z^2 with modulus (1,0)Z+(0,2)Z
  
              /
              | (2m,n/2)       if (m,n) in (0,0)+(1,0)Z+(0,2)Z
   (m,n) |-> <  (2m+1,(n-1)/2) if (m,n) in (0,1)+(1,0)Z+(0,2)Z
              |
              java.lang.NullPointerException
  
  !gapprompt@gap>A !gapinput@Display(b);A
  
  Rcwa permutation of Z^2 with modulus (2,0)Z+(0,3)Z
  
              /
              | (m,3n+2) if (m,n) in (1,0)+(2,0)Z+(0,1)Z
              | (m/2,n)  if (m,n) in (0,0)+(2,0)Z+(0,3)Z U 
   (m,n) |-> <                       (0,1)+(2,0)Z+(0,3)Z
              | (m,n)    if (m,n) in (0,2)+(2,0)Z+(0,3)Z
              |
              java.lang.NullPointerException
  
\end{Verbatim}
 It is easy to see that both \texttt{a} and{\nobreakspace}\texttt{b} have infinite order. The cycles of{\nobreakspace}\texttt{a} have roughly hyperbolic shape and run, so to speak, from $(0,\pm \infty)$ to $(\pm \infty,0)$. A given cycle contains only finitely many points both of whose coordinates
are nonzero. The fixed points of{\nobreakspace}\texttt{a} are (0,0) and (\texttt{\symbol{45}}1,\texttt{\symbol{45}}1). We have a look at
an example of a cycle of{\nobreakspace}\texttt{a}: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Trajectory(a,[1000,1000],15);|
  [ [ 1000, 1000 ], [ 2000, 500 ], [ 4000, 250 ], [ 8000, 125 ], 
    [ 16001, 62 ], [ 32002, 31 ], [ 64005, 15 ], [ 128011, 7 ], 
    [ 256023, 3 ], [ 512047, 1 ], [ 1024095, 0 ], [ 2048190, 0 ], 
    [ 4096380, 0 ], [ 8192760, 0 ], [ 16385520, 0 ] ]
  !gapprompt@gap>| !gapinput@Trajectory(a^-1,[1000,1000],15);|
  [ [ 1000, 1000 ], [ 500, 2000 ], [ 250, 4000 ], [ 125, 8000 ], 
    [ 62, 16001 ], [ 31, 32002 ], [ 15, 64005 ], [ 7, 128011 ], 
    [ 3, 256023 ], [ 1, 512047 ], [ 0, 1024095 ], [ 0, 2048190 ], 
    [ 0, 4096380 ], [ 0, 8192760 ], [ 0, 16385520 ] ]
  
\end{Verbatim}
 It is left as an easy exercise to the reader to find out how the cycles
of{\nobreakspace}\texttt{b} look like. 

 Enter \texttt{AssignGlobals(LoadRCWAExamples().ZxZ);} in order to assign the global variables defined in this section. }

  
\section{\textcolor{Chapter }{ Finite quotients of Grigorchuk groups }}\label{sec:GrigorchukGroups}
\logpage{[ 7, 19, 0 ]}
\hyperdef{L}{X81EB8D397898C6B2}{}
{
  In this section, we show how to construct finite quotients of the two infinite
periodic groups introduced by Rostislav Grigorchuk in{\nobreakspace}\cite{Grigorchuk80} with the help of \textsf{RCWA}. The first of these, nowadays known as ``Grigorchuk group'', is investigated in an example given on the \textsf{GAP} website \texttt{\symbol{45}}\texttt{\symbol{45}} see \href{https://www.gap-system.org/Doc/Examples/grigorchuk.html} {\texttt{https://www.gap\texttt{\symbol{45}}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}[commandchars=!@|,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}
 The actual constructors for the generators are modified as follows: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=]
  
  a := level -> Permutation(ClassTransposition(0,2,1,2),[0..2^level-1]);
  b := level -> SequenceElement(0,level);
  c := level -> SequenceElement(2,level);
  d := level -> SequenceElement(1,level);
  
\end{Verbatim}
 All computations given on the webpage can now be done just as with the ``original'' construction of the quotients of the Grigorchuk group. In the sequel, we
construct finite quotients of the second group introduced in{\nobreakspace}\cite{Grigorchuk80}: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@FourCycle := RcwaMapping((4,5,6,7),[4..7]);|
  ( 0(4), 1(4), 2(4), 3(4) )
  !gapprompt@gap>| !gapinput@GrigorchukGroup2Generator := function ( level )|
  !gapprompt@>| !gapinput@     if level = 1 then return FourCycle; else|
  !gapprompt@>| !gapinput@       return   Restriction(FourCycle, RcwaMapping([[4,1,1]]))|
  !gapprompt@>| !gapinput@              * Restriction(FourCycle, RcwaMapping([[4,3,1]]))|
  !gapprompt@>| !gapinput@              * Restriction(GrigorchukGroup2Generator(level-1),|
  !gapprompt@>| !gapinput@                            RcwaMapping([[4,0,1]]));|
  !gapprompt@>| !gapinput@     fi;|
  !gapprompt@>| !gapinput@   end;;|
  !gapprompt@gap>| !gapinput@GrigorchukGroup2 := level -> Group(FourCycle,|
  !gapprompt@>| !gapinput@                                      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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@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> ]
  !gapprompt@gap>| !gapinput@H := List([1..4],lev->Action(G[lev],[0..4^lev-1])); # Isom. 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> ]
  !gapprompt@gap>| !gapinput@List(H,Size);|
  [ 4, 1024, 4294967296, 1329227995784915872903807060280344576 ]
  !gapprompt@gap>| !gapinput@List(last,n->Collected(Factors(n)));|
  [ [ [ 2, 2 ] ], [ [ 2, 10 ] ], [ [ 2, 32 ] ], [ [ 2, 120 ] ] ]
  !gapprompt@gap>| !gapinput@List(H,NilpotencyClassOfGroup);      |
  [ 1, 6, 14, 40 ]
  
\end{Verbatim}
 Enter \texttt{AssignGlobals(LoadRCWAExamples().GrigorchukQuotients);} in order to assign the global variables defined in this section. }

  
\section{\textcolor{Chapter }{ Forward orbits of a monoid with 2 generators }}\label{sec:ForwardOrbit}
\logpage{[ 7, 20, 0 ]}
\hyperdef{L}{X7DD9502F80364631}{}
{
  The $3n+1$ conjecture asserts that the forward orbit of any positive integer under the
Collatz mapping $T$ contains{\nobreakspace}1. In contrast, it seems likely that ``most'' trajectories of the two mappings 
  
\[
  T_5^\pm: \ \mathbb{Z} \longrightarrow \mathbb{Z}, \ \ \ java.lang.NullPointerException
    n \ \longmapsto java.lang.NullPointerException
    \begin{cases}
      \frac{n}{2}        & \text{if} \ n \ \text{even}, \\
      \frac{5n \pm 1}{2} & \text{if} \ n \ \text{odd}
    \end{cases}
  \]

   diverge. However we can show by means of computation that the forward orbit of
any positive integer under the action of the monoid generated by the two
mappings $T_5^-$ and{\nobreakspace}$T_5^+$ indeed contains{\nobreakspace}1. First of all, we enter the generators: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@T5m := RcwaMapping([[1,0,2],[5,-1,2]]);;|
  !gapprompt@gap>| !gapinput@T5p := RcwaMapping([[1,0,2],[5, 1,2]]);;|
  
\end{Verbatim}
 We look for a number $k$ such that for any residue class $r(2^k)$ there is a product{\nobreakspace}$f$ of $k${\nobreakspace}mappings $T_5^\pm$ whose restriction to $r(2^k)$ is given by $n \mapsto (an+b)/c$ where $c>a$: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@k := 1;;|
  !gapprompt@gap>| !gapinput@repeat|
  !gapprompt@>| !gapinput@     maps := List(Tuples([T5m,T5p],k),Product);|
  !gapprompt@>| !gapinput@     decr := List(maps,DecreasingOn);|
  !gapprompt@>| !gapinput@     decreasable := Union(decr);|
  !gapprompt@>| !gapinput@     Print(k,": "); View(decreasable); Print("\n");|
  !gapprompt@>| !gapinput@     k := k + 1;|
  !gapprompt@>| !gapinput@   until decreasable = Integers;|
  1: 0(2)
  2: 0(4)
  3: Z \ 1(8) U 7(8)
  4: 0(4) U 3(16) U 6(16) U 10(16) U 13(16)
  5: Z \ 7(32) U 25(32)
  6: <union of 48 residue classes (mod 64)>
  7: Integers
  
\end{Verbatim}
 Thus $k=7$ serves our purposes. To be sure that for any positive integer $n$ our monoid contains a mapping $f$ such that $n^f<n$, we still need to check this condition for ``small''{\nobreakspace}$n$. Since in case $c>a$ we have $(an+b)/c \geq n$ if only if $n \leq b/(c-a)$, we only need to check those $n$ which are not larger than the largest coefficient $b_{r(m)}$ occurring in any of the products under consideration: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@maxb := Maximum(List(maps,f->Maximum(List(Coefficients(f),t->t[2]))));|
  25999
  !gapprompt@gap>| !gapinput@small := Filtered([1..maxb],n->ForAll(maps,f->n^f>=n));|
  [ 1, 7, 9, 11 ]
  
\end{Verbatim}
 This means that except of{\nobreakspace}1, only for $n \in \{{7,9,11\}}$ there is no product of 7 mappings $T_5^\pm$ which maps $n$ to a smaller integer. We check that also the forward orbits of these three
integers contain{\nobreakspace}1 by successively computing preimages
of{\nobreakspace}1: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@S := [1];; k := 0;;|
  !gapprompt@gap>| !gapinput@repeat|
  !gapprompt@>| !gapinput@     S := Union(S,PreImage(T5m,S),PreImage(T5p,S));|
  !gapprompt@>| !gapinput@     k := k+1;|
  !gapprompt@>| !gapinput@   until IsSubset(S,small);|
  !gapprompt@gap>| !gapinput@k;|
  17
  
\end{Verbatim}
 Enter \texttt{AssignGlobals(LoadRCWAExamples().CollatzMapping);} in order to assign the global variables defined in this section. }

  
\section{\textcolor{Chapter }{ The free group of rank 2 and the modular group PSL(2,{\ensuremath{\mathbb Z}}) }}\label{sec:F2andPSL2Z}
\logpage{[ 7, 21, 0 ]}
\hyperdef{L}{X815800ED820C6ECF}{}
{
  The free group of rank{\nobreakspace}2 embeds into RCWA({\ensuremath{\mathbb
Z}}) \texttt{\symbol{45}}\texttt{\symbol{45}} 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\texttt{\symbol{45}}called ``Schottky groups'' (cf.{\nobreakspace}\cite{LaHarpe00}, page{\nobreakspace}27) from PSL(2,{\ensuremath{\mathbb C}}) to
RCWA({\ensuremath{\mathbb Z}}) (we use the notation from the cited book): 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@D := AllResidueClassesModulo(4);|
  [ 0(4), 1(4), 2(4), 3(4) ]
  !gapprompt@gap>| !gapinput@gamma1 := RepresentativeAction(RCWA(Integers),|
  !gapprompt@>| !gapinput@                                  Difference(Integers,D[1]),D[2]);;|
  !gapprompt@gap>| !gapinput@gamma2 := RepresentativeAction(RCWA(Integers),|
  !gapprompt@>| !gapinput@                                  Difference(Integers,D[3]),D[4]);;|
  !gapprompt@gap>| !gapinput@F2 := Group(gamma1,gamma2);|
  <rcwa group over Z with 2 generators>
  
\end{Verbatim}
 We can do some checks: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@X1 := Union(D{[1,2]});; X2 := Union(D{[3,4]});;|
  !gapprompt@gap>| !gapinput@    IsSubset(X1,X2^gamma1) and IsSubset(X1,X2^(gamma1^-1))|
  !gapprompt@>| !gapinput@   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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Factorization(gamma1);|
  [ ( 0(2), 1(2) ), ( 3(4), 5(8) ), ( 0(2), 1(8) ) ]
  !gapprompt@gap>| !gapinput@Factorization(gamma2);|
  [ ( 0(2), 1(2) ), ( 1(4), 7(8) ), ( 0(2), 3(8) ) ]
  
\end{Verbatim}
 The above construction is used by \texttt{IsomorphismRcwaGroup} (\ref{IsomorphismRcwaGroup:for a group}) to embed free groups of any rank{\nobreakspace}$\geq 2$. 

 We give another only slightly different representation of the free group of
rank{\nobreakspace}2. We verify that it really is one by applying the
so\texttt{\symbol{45}}called \emph{Table\texttt{\symbol{45}}Tennis Lemma} (see e.g.{\nobreakspace}\cite{LaHarpe00}, Section{\nobreakspace}II.B.) to the infinite cyclic groups generated by the
two generators and to the same two sets \texttt{X1} and \texttt{X2} as above: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@r1 := ClassTransposition(0,2,1,2)*ClassTransposition(0,2,1,4);;|
  !gapprompt@gap>| !gapinput@r2 := ClassTransposition(0,2,1,2)*ClassTransposition(0,2,3,4);;|
  !gapprompt@gap>| !gapinput@F2 := Group(r1^2,r2^2);;|
  !gapprompt@gap>| !gapinput@List(GeneratorsOfGroup(F2),IsTame);|
  [ false, false ]
  !gapprompt@gap>| !gapinput@    IsSubset(X1,X2^F2.1) and IsSubset(X1,X2^(F2.1^-1))|
  !gapprompt@>| !gapinput@   and IsSubset(X2,X1^F2.2) and IsSubset(X2,X1^(F2.2^-1));|
  true
  !gapprompt@gap>| !gapinput@[Sources(r1),Sinks(r1),Loops(r1)]; # compare with X1|
  [ [ 0(4) ], [ 1(4) ], [ 0(4), 1(4) ] ]
  !gapprompt@gap>| !gapinput@[Sources(r2),Sinks(r2),Loops(r2)]; # compare with X2|
  [ [ 2(4) ], [ 3(4) ], [ 2(4), 3(4) ] ]
  !gapprompt@gap>| !gapinput@   IsSubset(X1,Union(Sinks(r1))) and IsSubset(X1,Union(Sinks(r1^-1)))|
  !gapprompt@>| !gapinput@  and IsSubset(X2,Union(Sinks(r2))) and IsSubset(X2,Union(Sinks(r2^-1)));|
  true
  !gapprompt@gap>| !gapinput@IsSubset(Union(Sinks(r1)),X2^F2.1) and|
  !gapprompt@>| !gapinput@   IsSubset(Union(Sinks(r1^-1)),X2^(F2.1^-1));|
  true
  !gapprompt@gap>| !gapinput@IsSubset(Union(Sinks(r2)),X1^F2.2) and|
  !gapprompt@>| !gapinput@   IsSubset(Union(Sinks(r2^-1)),X1^(F2.2^-1));|
  true
  
\end{Verbatim}
 Drawing the transition graphs of \texttt{r1} and \texttt{r2} for modulus{\nobreakspace}4 may help to understand what is actually done in
this calculation. It is easy to see that the group generated by \texttt{r1} and{\nobreakspace}\texttt{r2} is \emph{not} free: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Order(r1/r2);|
  3
  
\end{Verbatim}
 The modular group PSL(2,{\ensuremath{\mathbb Z}}) embeds into
CT({\ensuremath{\mathbb Z}}) as well. We give an embedding, and check that it
really is one by applying the Table Tennis Lemma as above: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@PSL2Z := |
  !gapprompt@>| !gapinput@     Group(ClassTransposition(0,3,1,3) * ClassTransposition(0,3,2,3),|
  !gapprompt@>| !gapinput@           ClassTransposition(1,3,0,6) * ClassTransposition(2,3,3,6));;|
  !gapprompt@gap>| !gapinput@List(GeneratorsOfGroup(PSL2Z),Order);|
  [ 3, 2 ]
  !gapprompt@gap>| !gapinput@X1 := Difference(Integers,ResidueClass(0,3));|
  Z \ 0(3)
  !gapprompt@gap>| !gapinput@X2 := ResidueClass(0,3);|
  0(3)
  !gapprompt@gap>| !gapinput@IsSubset(X1,X2^PSL2Z.1) and IsSubset(X1,X2^(PSL2Z.1^2));|
  true
  !gapprompt@gap>| !gapinput@IsSubset(X2,X1^PSL2Z.2);|
  true
  
\end{Verbatim}
 A slightly different representation of PSL(2,{\ensuremath{\mathbb Z}}) can be
obtained by using \textsf{RCWA}'s general method for \texttt{IsomorphismRcwaGroup} for free products of finite groups: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Image(IsomorphismRcwaGroup(FreeProduct(CyclicGroup(3),|
  !gapprompt@>| !gapinput@                                               CyclicGroup(2))));|
  <wild rcwa group over Z with 2 generators>
  !gapprompt@gap>| !gapinput@List(GeneratorsOfGroup(G),Factorization);|
  [ [ ( 0(4), 2(4) ), ( 1(2), 0(4) ) ], [ ( 0(2), 1(2) ) ] ]
  
\end{Verbatim}
 Enter \texttt{AssignGlobals(LoadRCWAExamples().F2{\textunderscore}PSL2Z);} in order to assign the global variables defined in this section.  }

  }

       
\chapter{\textcolor{Chapter }{The Algorithms Implemented in RCWA}}\label{ch:algorithms}
\logpage{[ 8, 0, 0 ]}
\hyperdef{L}{X79EA0B717B045756}{}
{
  This chapter lists brief descriptions of the algorithms and methods
implemented in this package. These descriptions are kept very informal and
terse, 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 performing
I/O operations, storing or recalling one or several values or doing very basic
computations, and ``straightforward'' means that no sophisticated algorithm is used. Note that ``trivial'' and ``straightforward'' are to be read as \emph{mathematically} trivial respectively straightforward, and that the code of a function or
method attributed in this way can still be reasonably long and complicated.
Longer and better descriptions of \emph{some} of the algorithms and methods can be found in{\nobreakspace}\cite{Kohl08b}. 
\begin{description}
\item[{ \texttt{ActionOnRespectedPartition(\mbox{\texttt{\mdseries\slshape G}})} }]  ``Straightforward'' after having computed a respected partition by \texttt{RespectedPartition}. 
\item[{ \texttt{AllElementsOfCTZWithGivenModulus(\mbox{\texttt{\mdseries\slshape m}})} }]  This function first determines a list of all unordered partitions $\mathcal{P}$ of {\ensuremath{\mathbb Z}} into \mbox{\texttt{\mdseries\slshape m}} residue classes. Then for any such partition $\mathcal{P}$ it runs a loop over the elements of the symmetric group of degree \mbox{\texttt{\mdseries\slshape m}}. For any $\sigma \in {\rm S}_m$ and any partition $\mathcal{P}$ it constructs the element of ${\rm CT}(\mathbb{Z})$ with modulus dividing $m$ which maps the ordered partition $\{0(m), 1(m), \dots, m-1(m)\}$ to the ordered partition obtained from $\mathcal{P}$ by permuting the residue classes with $\sigma$. Finally it discards the elements whose modulus is a proper divisor of \mbox{\texttt{\mdseries\slshape m}}, and returns the ``rest''. 
\item[{ \texttt{Ball(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape g}},\mbox{\texttt{\mdseries\slshape r}})} }]  ``Straightforward''. 
\item[{ \texttt{Ball(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape p}},\mbox{\texttt{\mdseries\slshape r}},\mbox{\texttt{\mdseries\slshape act}})} }]  ``Straightforward''. 
\item[{ \texttt{ClassPairs(\mbox{\texttt{\mdseries\slshape m}})} }]  Runs a loop over all 4\texttt{\symbol{45}}tuples of nonnegative integers less
than \mbox{\texttt{\mdseries\slshape m}}, and filters by congruence criteria and ordering of the entries. 
\item[{ \texttt{ClassReflection(\mbox{\texttt{\mdseries\slshape r}},\mbox{\texttt{\mdseries\slshape m}})} }]  ``Trivial''. 
\item[{ \texttt{ClassRotation(\mbox{\texttt{\mdseries\slshape r}},\mbox{\texttt{\mdseries\slshape m}},\mbox{\texttt{\mdseries\slshape u}})} }]  ``Trivial''. 
\item[{ \texttt{ClassShift(\mbox{\texttt{\mdseries\slshape r}},\mbox{\texttt{\mdseries\slshape m}})} }]  ``Trivial''. 
\item[{ \texttt{ClassTransposition(\mbox{\texttt{\mdseries\slshape r1}},\mbox{\texttt{\mdseries\slshape m1}},\mbox{\texttt{\mdseries\slshape r2}},\mbox{\texttt{\mdseries\slshape m2}})} }]  ``Trivial''. 
\item[{ \texttt{ClassWiseOrderPreservingOn(\mbox{\texttt{\mdseries\slshape f}})}, etc. }]  Forms the union of the residue classes modulo the modulus of{\nobreakspace}\mbox{\texttt{\mdseries\slshape f}} in whose corresponding coefficient triple the first entry is positive, zero or
negative, respectively. 
\item[{ \texttt{Coefficients(\mbox{\texttt{\mdseries\slshape f}})} }]  ``Trivial''. 
\item[{ \texttt{CommonRightInverse(\mbox{\texttt{\mdseries\slshape l}},\mbox{\texttt{\mdseries\slshape r}})} }]  See \texttt{RightInverse}. 
\item[{ \texttt{CT(\mbox{\texttt{\mdseries\slshape R}})} }]  Attributes and properties are set according to{\nobreakspace}\cite{Kohl09}. 
\item[{ \texttt{CycleRepresentativesAndLengths(\mbox{\texttt{\mdseries\slshape g}},\mbox{\texttt{\mdseries\slshape S}})} }]  ``Straightforward''. 
\item[{ \texttt{CyclesOnFiniteOrbit(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape g}},\mbox{\texttt{\mdseries\slshape n}})} }]  ``Straightforward''. 
\item[{ \texttt{DecreasingOn(\mbox{\texttt{\mdseries\slshape f}})} }]  Forms the union of the residue classes which are determined by the
coefficients as indicated. 
\item[{ \texttt{DerivedSubgroup(\mbox{\texttt{\mdseries\slshape G}})} }]  No genuine method \texttt{\symbol{45}}\texttt{\symbol{45}} \textsf{GAP} Library methods already work for tame groups. 
\item[{ \texttt{Determinant(\mbox{\texttt{\mdseries\slshape g}})} }]  Evaluation of the given expression. For the mathematical meaning
(epimorphism!), see Theorem{\nobreakspace}2.11.9 in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{DifferencesList(\mbox{\texttt{\mdseries\slshape l}})} }]  ``Trivial''. 
\item[{ \texttt{DirectProduct(\mbox{\texttt{\mdseries\slshape G1}},\mbox{\texttt{\mdseries\slshape G2}}, ... )} }]  Restricts the groups \mbox{\texttt{\mdseries\slshape G1}}, \mbox{\texttt{\mdseries\slshape G2}}, ... to disjoint residue classes. See \texttt{Restriction} and Corollary{\nobreakspace}2.3.3 in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{Display(\mbox{\texttt{\mdseries\slshape f}})} }]  ``Trivial''. 
\item[{ \texttt{DistanceToNextSmallerPointInOrbit(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape n}})} }]  ``Straightforward'' \texttt{\symbol{45}}\texttt{\symbol{45}} computes balls of radius $r$ about \mbox{\texttt{\mdseries\slshape n}} for $r = 1, 2, \dots$ until a point smaller than $n$ is found. 
\item[{ \texttt{Divisor(\mbox{\texttt{\mdseries\slshape f}})} }]  Lcm of coefficients, as indicated. 
\item[{ \texttt{DrawGrid(\mbox{\texttt{\mdseries\slshape U}},\mbox{\texttt{\mdseries\slshape range{\textunderscore}y}},\mbox{\texttt{\mdseries\slshape range{\textunderscore}x}},\mbox{\texttt{\mdseries\slshape filename}})} }]  ``Straightforward''. 
\item[{ \texttt{DrawOrbitPicture} }]  Compute spheres of radius $1, \dots, r$ around the given point(s). Choose the origin either in the lower left corner
of the picture (if all points lie in the first quadrant) or in the middle of
the picture (if they don't). Mark points of the ball with black pixels in case
of a monochrome picture. Choose colors from the given palette depending on the
distance from the starting points in case of a colored picture. 
\item[{ \texttt{EpimorphismFromFpGroup(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape r}})} }]  Computes orders of elements in the ball of radius{\nobreakspace}\mbox{\texttt{\mdseries\slshape r}} about{\nobreakspace}1 in{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}}, and uses the corresponding relations if they affect the abelian invariants
of \mbox{\texttt{\mdseries\slshape G}}, \mbox{\texttt{\mdseries\slshape G'}}, \mbox{\texttt{\mdseries\slshape G''}}, etc.. 
\item[{ \texttt{Exponent(\mbox{\texttt{\mdseries\slshape G}})} }]  Check whether \mbox{\texttt{\mdseries\slshape G}} is finite. If it is, then use the \textsf{GAP} Library method, applied to \texttt{Image(IsomorphismPermGroup(\mbox{\texttt{\mdseries\slshape G}}))}. Check whether \mbox{\texttt{\mdseries\slshape G}} is tame. If yes, return \texttt{infinity}. If not, run a loop over \mbox{\texttt{\mdseries\slshape G}} until finding an element of infinite order. Once one is found, return \texttt{infinity}. 

 The final loop to find a non\texttt{\symbol{45}}torsion element can be left
away under the assumption that any finitely generated wild rcwa group has a
wild element. It looks likely that this holds, but currently the author does
not know a proof. 
\item[{ \texttt{ExtRepOfObj(\mbox{\texttt{\mdseries\slshape f}})} }]  ``Trivial''. 
\item[{ \texttt{FactorizationIntoCSCRCT(\mbox{\texttt{\mdseries\slshape g}})}, {\nobreakspace} \texttt{Factorization(\mbox{\texttt{\mdseries\slshape g}})} }]  The method used here is rather sophisticated, and 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\texttt{\symbol{45}}wise order\texttt{\symbol{45}}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 in a similar
way as a permutation of a finite set can be factored into transpositions. 
\item[{ \texttt{FactorizationOnConnectedComponents(\mbox{\texttt{\mdseries\slshape f}},\mbox{\texttt{\mdseries\slshape m}})} }]  Calls \textsf{GRAPE} to get the connected components of the transition graph, and then computes a
partition of the suitably ``blown up'' coefficient list corresponding to the connected components. 
\item[{ \texttt{FixedPointsOfAffinePartialMappings(\mbox{\texttt{\mdseries\slshape f}})} }]  ``Straightforward''. 
\item[{ \texttt{FixedResidueClasses(\mbox{\texttt{\mdseries\slshape g}},\mbox{\texttt{\mdseries\slshape maxmod}})}, {\nobreakspace} \texttt{FixedResidueClasses(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape maxmod}})} }]  Runs a loop over all moduli $m \leq$ \mbox{\texttt{\mdseries\slshape maxmod}} and all residues $r$ modulo these moduli, and selects those residue classes $r(m)$ which are mapped to itself by \mbox{\texttt{\mdseries\slshape g}}, respectively, by all generators of \mbox{\texttt{\mdseries\slshape G}}. 
\item[{ \texttt{FloatQuotientsList(\mbox{\texttt{\mdseries\slshape l}})} }]  ``Trivial''. 
\item[{ \texttt{GluckTaylorInvariant(\mbox{\texttt{\mdseries\slshape a}})} }]  Evaluation of the given expression. 
\item[{ \texttt{GroupByResidueClasses(\mbox{\texttt{\mdseries\slshape classes}})} }]  Finds all pairs of residue classes in the list \mbox{\texttt{\mdseries\slshape classes}} which are disjoint, forms the corresponding class transpositions and returns
the group generated by them. 
\item[{ \texttt{GuessedDivergence(\mbox{\texttt{\mdseries\slshape f}})} }]  Numerical computation of the limit of some series, which seems to converge ``often''. Caution!!! 
\item[{ \texttt{Image(\mbox{\texttt{\mdseries\slshape f}})}, {\nobreakspace} \texttt{Image(\mbox{\texttt{\mdseries\slshape f}},\mbox{\texttt{\mdseries\slshape S}})} }]  ``Straightforward'' if one can compute images of residue classes under affine mappings and unite
and intersect residue classes (Chinese Remainder Theorem). See
Lemma{\nobreakspace}1.2.1 in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{ImageDensity(\mbox{\texttt{\mdseries\slshape f}})} }]  Evaluation of the given expression. 
\item[{ \texttt{\mbox{\texttt{\mdseries\slshape g}} in \mbox{\texttt{\mdseries\slshape G}}} (membership test for rcwa groups) }]  Test whether the mapping \mbox{\texttt{\mdseries\slshape g}} or its inverse is in the list of generators of{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}}. If it is, return \texttt{true}. Test whether its prime set is a subset of the prime set of{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}}. If not, return \texttt{false}. Test whether the multiplier or the divisor of{\nobreakspace}\mbox{\texttt{\mdseries\slshape g}} has a prime factor which does not divide the multiplier of{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}}. If yes, return \texttt{false}. Test if \mbox{\texttt{\mdseries\slshape G}} is class\texttt{\symbol{45}}wise order\texttt{\symbol{45}}preserving, and \mbox{\texttt{\mdseries\slshape g}} is not. If so, return \texttt{false}. Test if the sign of \mbox{\texttt{\mdseries\slshape g}} is{\nobreakspace}\texttt{\symbol{45}}1 and all generators of{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} have sign{\nobreakspace}1. If yes, return \texttt{false}. Test if \mbox{\texttt{\mdseries\slshape G}} is class\texttt{\symbol{45}}wise order\texttt{\symbol{45}}preserving, all
generators of{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} have determinant{\nobreakspace}0 and \mbox{\texttt{\mdseries\slshape g}} has determinant{\nobreakspace}$\neq 0$. If yes, return \texttt{false}. Test whether the support of{\nobreakspace}\mbox{\texttt{\mdseries\slshape g}} is a subset of the support of{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}}. If not, return \texttt{false}. Test whether \mbox{\texttt{\mdseries\slshape G}} fixes the nonnegative integers setwise, but{\nobreakspace}\mbox{\texttt{\mdseries\slshape g}} does not. If yes, return \texttt{false}. 

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

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

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

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

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

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

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

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

 The method for free groups uses an adaptation of the construction given on
page{\nobreakspace}27 in{\nobreakspace}\cite{LaHarpe00} from PSL(2,{\ensuremath{\mathbb C}}) to RCWA({\ensuremath{\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{IsOne(\mbox{\texttt{\mdseries\slshape f}})} }]  ``Trivial''. 
\item[{ \texttt{IsPerfectGroup(\mbox{\texttt{\mdseries\slshape G}})} }]  If the group \mbox{\texttt{\mdseries\slshape G}} is trivial, then return \texttt{true}. Otherwise if it is abelian, then return \texttt{false}. 

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

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

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

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

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

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

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

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

 If it terminates: If $S = {\ensuremath{\mathbb Z}}$, return \texttt{true}, otherwise return \texttt{false}. 
\item[{ \texttt{IsTransitiveOnNonnegativeIntegersInSupport(\mbox{\texttt{\mdseries\slshape G}})} }]  Computes balls about 1 with successively increasing radii, and checks whether
the union of the sets where the elements of these balls are decreasing or
shifting down equals the support of \mbox{\texttt{\mdseries\slshape G}}. If a positive answer is found, transitivity on ``small'' points (nonnegative integers less than an explicit bound) is verified. 
\item[{ \texttt{IsZero(\mbox{\texttt{\mdseries\slshape f}})} }]  ``Trivial''. 
\item[{ \texttt{KernelOfActionOnRespectedPartition(\mbox{\texttt{\mdseries\slshape G}})} }]  First determine the abelian invariants of the kernel{\nobreakspace}\texttt{K}. For this, compute sufficiently many quotients of orders of permutation
groups induced by{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} on refinements of the stored respected partition{\nobreakspace}\texttt{P} by the order of the permutation group induced by{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} on{\nobreakspace}\texttt{P} itself. Then use a random walk through the group \mbox{\texttt{\mdseries\slshape G}}. Compute powers of elements encountered along the way which
fix{\nobreakspace}\texttt{P}. Translate these kernel elements into elements of a polycyclically presented
group isomorphic to the \texttt{|P|}\texttt{\symbol{45}}fold direct product of the infinite dihedral group (\texttt{K} certainly embeds into this group). Use \textsf{Polycyclic}{\nobreakspace}\cite{Polycyclic} to collect independent ``nice'' generators of{\nobreakspace}\texttt{K}. Proceed until the permutation groups induced by{\nobreakspace}\texttt{K} on the refined respected partitions all equal the initially stored quotients. 
\item[{ \texttt{LargestSourcesOfAffineMappings(\mbox{\texttt{\mdseries\slshape f}})} }]  Forms unions of residue classes modulo the modulus of the mapping, whose
corresponding coefficient triples are equal. 
\item[{ \texttt{LaTeXStringRcwaMapping(\mbox{\texttt{\mdseries\slshape f}})}, {\nobreakspace} \texttt{LaTeXAndXDVI(\mbox{\texttt{\mdseries\slshape f}})} }]  Collects residue classes those corresponding coefficient triples are equal. 
\item[{ \texttt{LikelyContractionCentre(\mbox{\texttt{\mdseries\slshape f}},\mbox{\texttt{\mdseries\slshape maxn}},\mbox{\texttt{\mdseries\slshape bound}})} }]  Computes trajectories with starting values from a given interval, until a
cycle is reached. Aborts if the trajectory exceeds the prescribed bound. Form
the union of the detected cycles. 
\item[{ \texttt{LoadDatabaseOf...()}, {\nobreakspace} \texttt{LoadRCWAExamples()} }]  ``Trivial''. \texttt{\symbol{45}}\texttt{\symbol{45}} These functions do nothing more
than reading in certain files. 
\item[{ \texttt{LocalizedRcwaMapping(\mbox{\texttt{\mdseries\slshape f}},\mbox{\texttt{\mdseries\slshape p}})} }]  ``Trivial''. 
\item[{ \texttt{Log2HTML(\mbox{\texttt{\mdseries\slshape logfilename}})} }]  Straightforward string operations. 
\item[{ \texttt{Loops(\mbox{\texttt{\mdseries\slshape f}})} }]  Runs over the residue classes modulo the modulus of{\nobreakspace}\mbox{\texttt{\mdseries\slshape f}}, and selects those of them which \mbox{\texttt{\mdseries\slshape f}} does not map to themselves, but which intersect
non\texttt{\symbol{45}}trivially with their images under{\nobreakspace}\mbox{\texttt{\mdseries\slshape f}}. 
\item[{ \texttt{MaximalShift(\mbox{\texttt{\mdseries\slshape f}})} }]  ``Trivial''. 
\item[{ \texttt{MergerExtension(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape points}},\mbox{\texttt{\mdseries\slshape point}})} }]  As described in \texttt{MergerExtension} (\ref{MergerExtension:for finite permutation groups}). 
\item[{ \texttt{Mirrored(\mbox{\texttt{\mdseries\slshape g}})}, {\nobreakspace} \texttt{Mirrored(\mbox{\texttt{\mdseries\slshape G}})} }]  Conjugates with $n \mapsto -n - 1$, as indicated in the definition. 
\item[{ \texttt{mKnot(\mbox{\texttt{\mdseries\slshape m}})} }]  ``Straightforward'', following the definition given in \cite{Keller99}. 
\item[{ \texttt{Modulus(\mbox{\texttt{\mdseries\slshape G}})} }]  Searches for a wild element in the group. If unsuccessful, tries to construct
a respected partition (see \texttt{RespectedPartition}). 
\item[{ \texttt{Modulus(\mbox{\texttt{\mdseries\slshape f}})} }]  ``Trivial''. 
\item[{ \texttt{MovedPoints(\mbox{\texttt{\mdseries\slshape G}})} }]  Needs only forming unions of residue classes and determining fixed points of
affine mappings. 
\item[{ \texttt{Multiplier(\mbox{\texttt{\mdseries\slshape f}})} }]  Lcm of coefficients, as indicated. 
\item[{ \texttt{Multpk(\mbox{\texttt{\mdseries\slshape f}},\mbox{\texttt{\mdseries\slshape p}},\mbox{\texttt{\mdseries\slshape k}})} }]  Forms the union of the residue classes modulo the modulus of the mapping,
which are determined by the given divisibility criteria for the coefficients
of the corresponding affine mapping. 
\item[{ \texttt{NrClassPairs(\mbox{\texttt{\mdseries\slshape m}})} }]  Relatively straightforward. \texttt{\symbol{45}}\texttt{\symbol{45}} Practical
for values of \mbox{\texttt{\mdseries\slshape m}} ranging up into the hundreds and corresponding counts of
\$10\texttt{\symbol{94}}9\$ and more. 
\item[{ \texttt{NrConjugacyClassesOfCTZOfOrder(\mbox{\texttt{\mdseries\slshape ord}})}, }]  Evaluation of the expression \texttt{Length(Filtered(Combinations(DivisorsInt(ord)), l
\texttt{\symbol{45}}{\textgreater} l {\textless}{\textgreater} [] and Lcm(l) =
ord))}. 
\item[{ \texttt{NrConjugacyClassesOfRCWAZOfOrder(\mbox{\texttt{\mdseries\slshape ord}})} }]  The class numbers are taken from Corollary{\nobreakspace}2.7.1
in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{ObjByExtRep(\mbox{\texttt{\mdseries\slshape fam}},\mbox{\texttt{\mdseries\slshape l}})} }]  ``Trivial''. 
\item[{ \texttt{One(\mbox{\texttt{\mdseries\slshape f}})}, {\nobreakspace} \texttt{One(\mbox{\texttt{\mdseries\slshape G}})}, }]  ``Trivial''. 
\item[{ \texttt{Orbit(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape pnt}},\mbox{\texttt{\mdseries\slshape gens}},\mbox{\texttt{\mdseries\slshape acts}},\mbox{\texttt{\mdseries\slshape act}})} }]  Check if the orbit has length less than a certain bound. If so, then return it
as a list. Otherwise test whether the group \mbox{\texttt{\mdseries\slshape G}} is tame or wild. 

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

 If \mbox{\texttt{\mdseries\slshape G}} is wild, then return an orbit object which stores the group{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}}, the representative{\nobreakspace}\mbox{\texttt{\mdseries\slshape rep}} and the action{\nobreakspace}\mbox{\texttt{\mdseries\slshape act}}. 
\item[{ \texttt{OrbitsModulo(\mbox{\texttt{\mdseries\slshape f}},\mbox{\texttt{\mdseries\slshape m}})} }]  Uses \textsf{GRAPE} to compute the connected components of the transition graph. 
\item[{ \texttt{OrbitsModulo(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape m}})} }]  ``Straightforward''. 
\item[{ \texttt{Order(\mbox{\texttt{\mdseries\slshape f}})} }]  Test for \texttt{IsTame}. If the mapping is not tame, then return \texttt{infinity}. Otherwise use Corollary{\nobreakspace}2.5.10 in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{PermutationOpNC(\mbox{\texttt{\mdseries\slshape sigma}},\mbox{\texttt{\mdseries\slshape P}},\mbox{\texttt{\mdseries\slshape act}})} }]  Several different methods for different types of arguments, which either
provide straightforward optimizations via computing with coefficients
directly, or just delegate to \texttt{PermutationOp}. 
\item[{ \texttt{PreImage(\mbox{\texttt{\mdseries\slshape f}},\mbox{\texttt{\mdseries\slshape S}})} }]  See \texttt{Image}. 
\item[{ \texttt{PreImagesRepresentative(\mbox{\texttt{\mdseries\slshape phi}},\mbox{\texttt{\mdseries\slshape g}})}, {\nobreakspace} \texttt{PreImagesRepresentatives(\mbox{\texttt{\mdseries\slshape phi}},\mbox{\texttt{\mdseries\slshape g}})} }]  As described in the documentation of these methods. The underlying idea to
successively compute two balls around{\nobreakspace}1 and{\nobreakspace}\mbox{\texttt{\mdseries\slshape g}} until they intersect non\texttt{\symbol{45}}trivially is standard in
computational group theory. For rcwa groups it would mean wasting both memory
and run time to actually compute group elements. Thus only images of tuples of
points are computed and stored. 
\item[{ \texttt{PrimeSet(\mbox{\texttt{\mdseries\slshape f}})}, {\nobreakspace} \texttt{PrimeSet(\mbox{\texttt{\mdseries\slshape G}})} }]  ``Straightforward''. 
\item[{ \texttt{PrimeSwitch(\mbox{\texttt{\mdseries\slshape p}})} }]  Multiplication of rcwa mappings as indicated. 
\item[{ \texttt{Print(\mbox{\texttt{\mdseries\slshape f}})} }]  ``Trivial''. 
\item[{ \texttt{\mbox{\texttt{\mdseries\slshape f}}*\mbox{\texttt{\mdseries\slshape g}}} }]  Essentially composition of affine mappings. See Lemma{\nobreakspace}1.3.1,
Part{\nobreakspace}(a) in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{ProjectionsToCoordinates(\mbox{\texttt{\mdseries\slshape f}})} }]  Straightforward coefficient operations. 
\item[{ \texttt{ProjectionsToInvariantUnionsOfResidueClasses(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape m}})} }]  Use \texttt{OrbitsModulo} to determine the supports of the images of the epimorphisms to be determined,
and use \texttt{RestrictedPerm} to compute the images of the generators of{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}} under these epimorphisms. 
\item[{ \texttt{QuotientsList(\mbox{\texttt{\mdseries\slshape l}})} }]  ``Trivial''. 
\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{\mdseries\slshape G}})} }]  Performs the first part of the computations done by \texttt{KernelOfActionOnRespectedPartition}. 
\item[{ \texttt{Rcwa(\mbox{\texttt{\mdseries\slshape R}})} }]  ``Trivial''. \texttt{\symbol{45}}\texttt{\symbol{45}} Attributes and properties set can
be derived easily or hold by definition. 
\item[{ \texttt{RCWA(\mbox{\texttt{\mdseries\slshape R}})} }]  Attributes and properties are set according to Theorem{\nobreakspace}2.1.1,
Theorem{\nobreakspace}2.1.2, Corollary{\nobreakspace}2.1.6 and
Theorem{\nobreakspace}2.12.8 in{\nobreakspace}\cite{Kohl05}. 
\item[{ \texttt{RcwaGroupByPermGroup(\mbox{\texttt{\mdseries\slshape G}})} }]  Uses \texttt{RcwaMapping}, Part{\nobreakspace}(d). 
\item[{ \texttt{RCWAInfo(\mbox{\texttt{\mdseries\slshape n}})} }]  ``Trivial''. 
\item[{ \texttt{RcwaMapping} }]  (a)\texttt{\symbol{45}}(c): ``trivial'', (d): \texttt{n\texttt{\symbol{94}}perm \texttt{\symbol{45}} n} for determining the coefficients, (e): ``affine mappings by values at two given points'', (f) and (g): ``trivial'', (h) and (i): correspond to Lemma{\nobreakspace}2.1.4 in{\nobreakspace}\cite{Kohl05}, (j): uses a simple parser for the permitted expressions. 
\item[{ \texttt{RCWATestAll()}, {\nobreakspace} \texttt{RCWATestInstall()} }]  Just read in files running / containing the tests. 
\item[{ \texttt{RCWATestExamples()} }]  Runs the example tester from the \textsf{GAPDoc} package. 
\item[{ \texttt{RepresentativeAction(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape src}},\mbox{\texttt{\mdseries\slshape dest}},\mbox{\texttt{\mdseries\slshape act}})}, {\nobreakspace} \texttt{RepresentativeActionPreImage} }]  As described in the documentation of these methods. The underlying idea to
successively compute two balls around \mbox{\texttt{\mdseries\slshape src}} and \mbox{\texttt{\mdseries\slshape dest}} until they intersect non\texttt{\symbol{45}}trivially is standard in
computational group theory. Words standing for products of generators of \mbox{\texttt{\mdseries\slshape G}} are stored for every image of \mbox{\texttt{\mdseries\slshape src}} or \mbox{\texttt{\mdseries\slshape dest}}. 
\item[{ \texttt{RepresentativeAction(RCWA(Integers),\mbox{\texttt{\mdseries\slshape P1}},\mbox{\texttt{\mdseries\slshape P2}})} }]  Arbitrary mapping: see Lemma{\nobreakspace}2.1.4 in{\nobreakspace}\cite{Kohl05}. Tame mapping: see proof of Theorem{\nobreakspace}2.8.9 in{\nobreakspace}\cite{Kohl05}. The former is almost trivial, while the latter is a bit complicated and
takes usually also much more time. 
\item[{ \texttt{RepresentativeAction(RCWA(Integers),\mbox{\texttt{\mdseries\slshape f}},\mbox{\texttt{\mdseries\slshape g}})} }]  The algorithm used by \texttt{IsConjugate} constructs actually also an element \texttt{x} such that \texttt{\mbox{\texttt{\mdseries\slshape f}}\texttt{\symbol{94}}x = \mbox{\texttt{\mdseries\slshape g}}}. 
\item[{ \texttt{RespectedPartition(\mbox{\texttt{\mdseries\slshape f}})}, {\nobreakspace} \texttt{RespectedPartition(\mbox{\texttt{\mdseries\slshape G}})} }]  There are presently two sophisticated algorithms implemented for finding
respected partitions. One of them has evolved from the algorithm described in
the proof of Theorem{\nobreakspace}2.5.8 in{\nobreakspace}\cite{Kohl05}. The other one starts with the coarsest partition of the base ring such that
every generator of \mbox{\texttt{\mdseries\slshape G}} is affine on every part. This partition is then refined successively until a
respected partition is obtained. The refinement step is basically as follows:
Take the images of the partition under all generators of \mbox{\texttt{\mdseries\slshape G}}. This way one obtains as many further partitions of the base ring as there
are generators of{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}}. Then the ``new'' partition is the coarsest common refinement of all these partitions. 
\item[{ \texttt{RespectsPartition(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape P}})} }]  ``Straightforward''. 
\item[{ \texttt{RestrictedBall(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape g}},\mbox{\texttt{\mdseries\slshape r}},\mbox{\texttt{\mdseries\slshape modulusbound}})} }]  ``Straightforward''. 
\item[{ \texttt{RestrictedPerm(\mbox{\texttt{\mdseries\slshape g}},\mbox{\texttt{\mdseries\slshape S}})} }]  ``Straightforward''. 
\item[{ \texttt{Restriction(\mbox{\texttt{\mdseries\slshape g}},\mbox{\texttt{\mdseries\slshape f}})} }]  Computes the action of \texttt{RightInverse(\mbox{\texttt{\mdseries\slshape f}}) * g * f} on the image of{\nobreakspace}\mbox{\texttt{\mdseries\slshape f}}. 
\item[{ \texttt{Restriction(\mbox{\texttt{\mdseries\slshape G}},\mbox{\texttt{\mdseries\slshape f}})} }]  Gets a set of generators by applying \texttt{Restriction(\mbox{\texttt{\mdseries\slshape g}},\mbox{\texttt{\mdseries\slshape f}})} to the generators \mbox{\texttt{\mdseries\slshape g}} of{\nobreakspace}\mbox{\texttt{\mdseries\slshape G}}. 
\item[{ \texttt{RightInverse(\mbox{\texttt{\mdseries\slshape f}})} }]  ``Straightforward'' if one knows how to compute images of residue classes under affine mappings,
and how to compute inverses of affine mappings. 
\item[{ \texttt{Root(\mbox{\texttt{\mdseries\slshape f}},\mbox{\texttt{\mdseries\slshape k}})} }]  If \mbox{\texttt{\mdseries\slshape f}} is bijective, class\texttt{\symbol{45}}wise
order\texttt{\symbol{45}}preserving and has finite order: 

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

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

       
\chapter{\textcolor{Chapter }{Installation and Auxiliary Functions}}\label{ch:InstallationAndAuxiliaryFunctions}
\logpage{[ 9, 0, 0 ]}
\hyperdef{L}{X859F6BF88754E5CC}{}
{
   
\section{\textcolor{Chapter }{Requirements}}\label{sec:Requirements}
\logpage{[ 9, 1, 0 ]}
\hyperdef{L}{X85A08CF187A6D986}{}
{
  This version of \textsf{RCWA} needs at least \textsf{GAP}{\nobreakspace}4.9.0 in 64\texttt{\symbol{45}}bit mode, \textsf{ResClasses}{\nobreakspace}4.7.0, \textsf{GRAPE}{\nobreakspace}4.7{\nobreakspace}\cite{GRAPE}, \textsf{Polycyclic}{\nobreakspace}2.11{\nobreakspace}\cite{Polycyclic}, \textsf{FR}{\nobreakspace}2.2.1{\nobreakspace}\cite{FR}, \textsf{GAPDoc}{\nobreakspace}1.5.1{\nobreakspace}\cite{GAPDoc}, and \textsf{Utils}{\nobreakspace}0.40{\nobreakspace}\cite{Utils}. With possible exception of the most recent version of \textsf{ResClasses}, all needed packages are already present in an
up\texttt{\symbol{45}}to\texttt{\symbol{45}}date standard \textsf{GAP} installation. The \textsf{RCWA} package is completely written in the \textsf{GAP} language and can be used on all platforms for which \textsf{GAP} is available. }

  
\section{\textcolor{Chapter }{Installation}}\label{sec:Installation}
\logpage{[ 9, 2, 0 ]}
\hyperdef{L}{X8360C04082558A12}{}
{
  Like any other \textsf{GAP} package, \textsf{RCWA} is usually 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 testing routines}}\label{sec:TheTestingRoutines}
\logpage{[ 9, 3, 0 ]}
\hyperdef{L}{X865D6A49826B92EC}{}
{
  

\subsection{\textcolor{Chapter }{RCWATestInstall}}
\logpage{[ 9, 3, 1 ]}\nobreak
\hyperdef{L}{X8314E1597BF1555B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RCWATestInstall({\mdseries\slshape })\index{RCWATestInstall@\texttt{RCWATestInstall}}
\label{RCWATestInstall}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} if no errors were found, and \texttt{false} otherwise. 



 Performs a nontrivial computation to check whether an installation of \textsf{RCWA} appears to work. Errors, i.e. differences to the correct results of the test
computation, are reported. The processed test file is \texttt{pkg/rcwa/tst/testinstall.tst}. }

 

\subsection{\textcolor{Chapter }{RCWATestAll}}
\logpage{[ 9, 3, 2 ]}\nobreak
\hyperdef{L}{X877DDD787E4ABDC2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RCWATestAll({\mdseries\slshape })\index{RCWATestAll@\texttt{RCWATestAll}}
\label{RCWATestAll}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} if no errors were found, and \texttt{false} otherwise. 



 Runs the full test suite of the \textsf{RCWA} package. Any differences to the supposed results of the test computations are
reported. The processed test files are in the \texttt{tst} subdirectory of the package directory. 

 Please note that the test suite is a tool for developing. The tests are
deliberately very volatile to allow to spot possible problems of any kind also
in other packages or in the \textsf{GAP} Library. For this reason you may see reports of differences which simply
reflect improved methods in other packages or in the \textsf{GAP} Library (for example an object may already know more of its attributes or
properties than it is expected to, or an object may be represented in a better
way), or which are caused by changes of the way certain objects are printed,
and which are therefore harmless. However if the correct and the actual output
look different mathematically or if you see error messages or if \textsf{GAP} crashes, then something went wrong. Also, reports about significantly
increased run times of individual commands as well as run times of test files
which are much longer than the predicted times shown may indicate a problem. }

 

\subsection{\textcolor{Chapter }{RCWATestExamples}}
\logpage{[ 9, 3, 3 ]}\nobreak
\hyperdef{L}{X799793987AA3F34C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RCWATestExamples({\mdseries\slshape })\index{RCWATestExamples@\texttt{RCWATestExamples}}
\label{RCWATestExamples}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing. 



 Runs all examples in the manual of the \textsf{RCWA} package, and reports any differences between the actual output and the output
printed in the manual. }

 }

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

\subsection{\textcolor{Chapter }{InfoRCWA}}
\logpage{[ 9, 4, 1 ]}\nobreak
\hyperdef{L}{X7BAF5F4986288983}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\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{\mdseries\slshape n}}\texttt{)} is a shorthand for \texttt{SetInfoLevel(InfoRCWA},\mbox{\texttt{\mdseries\slshape n}}\texttt{)}. \index{RCWAInfo@\texttt{RCWAInfo}} }

 }

  }

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

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

\addcontentsline{toc}{chapter}{References}

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

\cleardoublepage
\phantomsection
\addcontentsline{toc}{chapter}{Index}


\printindex

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