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

\usepackage{fancyvrb}

\usepackage{pslatex}

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

% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
%% were never documented, give conflicts with some additional packages


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

\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\begin{center}{\Huge \textbf{Functionally recursive groups\mbox{}}}\\[1cm]
\hypersetup{pdftitle=Functionally recursive groups}
\markright{\scriptsize \mbox{}\hfill Functionally recursive groups \hfill\mbox{}}
{\Large \textbf{Self-similar groups\mbox{}}}\\[1cm]
{Version 0.857142p7 \mbox{}}\\[1cm]
{\$Date: 2008/11/13 15:28:12 \$\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\large \textbf{Laurent Bartholdi   \mbox{}}}\\
\hypersetup{pdfauthor=Laurent Bartholdi   }
\mbox{}\\[2cm]
\begin{minipage}{12cm}\noindent
 Groups generated by automata or satisfying functional recursions \end{minipage}

\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{Laurent Bartholdi   } --- Email: \href{mailto:// laurent.bartholdi@gmail.com} {\texttt{ laurent.bartholdi@gmail.com}}\\
 --- Homepage: \href{http://www.uni-math.gwdg.de/laurent/} {\texttt{http://www.uni-math.gwdg.de/laurent/}}}\\

\noindent \textbf{Address: }\begin{minipage}[t]{8cm}\noindent
 Mathematisches Institut, Bunsenstra{\ss}e 3-5, D-37073 G{\"o}ttingen\\
D-37073 G{\"o}ttingen\\
Germany \end{minipage}
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Abstract}
\logpage{[ 0, 0, 1 ]}
 This document describes the package \textsf{FR}, which implements in \textsf{GAP} the basic objects of Mealy machines and functional recursions; and handles
groups that they generate.  

 Groups defined by a recursive action on a rooted tree can be defined in \textsf{GAP} via their recursion. Various algorithms are implemented to manipulate these
groups and their elements. 

 For comments or questions on \textsf{FR} please contact the author; this package is still under development. \mbox{}}\\[1cm]
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 2 ]}
{\copyright} 2006-2008 by Laurent Bartholdi \mbox{}}\\[1cm]
{\small 
\section*{Acknowledgements}
\logpage{[ 0, 0, 3 ]}
Part of this work is supported by the "Swiss National Fund for Scientific
Research" \mbox{}}\\[1cm]
{\small 
\section*{Colophon}
\logpage{[ 0, 0, 4 ]}
 This project started in the mid-1990s, when, as a PhD student I did many
calculations with groups generated by automata, and realized the similarities
between all calculations; it quickly became clear that these calculations
could be done much better by a computer than by a human. 

 The first routines I wrote constructed finite representations of the groups
considered, so as to get insight from fast calculations within \textsf{GAP}. The results then had to be proved correct within the infinite group under
consideration, and this often involved guessing appropriate words in the
infinite group with a given image in the finite quotient. 

 Around 2000, I had developed quite a few routines, which I assembled in a \textsf{GAP} package, that dealt directly with infinite groups. This package was primitive
at its core, but was extended with various routines as they became useful. 

 I decided in late 2005 to start a new package from scratch, that would
encorporate as much functionality as possible in a uniform manner; that would
handle semigroups as well as groups; that could be easily extended; and with a
complete, understandable documentation. I hope I am not too far from these
objectives. \mbox{}}\\[1cm]
\newpage

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

\tableofcontents
\newpage

 
\chapter{\textcolor{Chapter }{Licensing}}\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X86DB23CC834ABD71}{}
{
 This program 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 any later version. 

 This program 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. 

 You should have received a copy of the GNU General Public License along with
this program, in the file COPYING. If not, see \href{http://www.gnu.org/licenses/} {\texttt{http://www.gnu.org/licenses/}}. }

 
\chapter{\textcolor{Chapter }{FR package}}\label{frpackage}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X7ADCE68284FB4ACF}{}
{
 
\section{\textcolor{Chapter }{A brief mathematical introduction}}\label{mathintro}
\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X80C332C686212786}{}
{
 This chapter assumes that you have no familiarity with groups generated by
automata. If you do, and wish to see their usage within \textsf{GAP} through a sample session, please skip to Section \ref{frintro}. For a more thourough introduction on self-similar groups see \cite{MR2091700} or \cite{MR2035113}. 

 We shall here be interested in groups $G$ defined by their action on a regular rooted tree. Let $X$ be a finite set; and let $X^*$ denote the set of words (free monoid) over $X$. Then $X^*$ naturally has the structure of a regular rooted tree: the root is the empty
word, and vertex $v \in X^*$ is connected to vertex $vx$ for all choices of $x \in X$. Each vertex except the root therefore has $\#X+1$ neighbours. 

 Let $W$ denote the automorphism group of the graph $X^*$. Given $a \in W$, we may restrict its action to $X \subset X^*$, and obtain a permutation $\pi_a$ on $X$, called the \emph{activity} of $a$. We may also obtain, for all $x\in X$, a tree automorphism $a_x \in W$, called the \emph{state of $a$ at $x$}, by the formula 
\[(v){a_x} = w \quad\textrm{if}\quad (xv)a = x^{\pi_a}w.\]
 The data $(a_x,\pi_a)$ determine uniquely the automorphism $a$, and any choice of $a_x$ and $\pi_a$ defines a tree isometry. We therefore have a group isomorphism 
\[\phi: W \to W\wr \mathop{Sym}(X),\]
 called the \emph{Wreath recursion}. The image of $\phi$ is the permutational wreath product $W^X \rtimes \mathop{Sym}(X)$. 

 The state $a_x$ should be interpreted as the restriction of the action of $a$ on the subtree $xX^*$; the automorphism $a$ is defined by acting first on each of the subtrees of the form $xX^*$ by its respective state, and then permuting these subtrees according to $\pi_a$. The wreath recursion can be iterated on the states of $a$, to define states $a_v$ for any $v \in X^*$. 

 The automorphism $a \in W$ may be represented by a graph, as follows. There is one vertex for each state $a_v$ of $a$, labeled $\pi_{a_v}$; and for each $x \in X$ there is one edge from state $a_v$ to state $a_{vx}$, labeled $x$. This graph is nothing but a quotient of the regular rooted tree $X^*$, where vertices $v$ and $w$ are identified if $a_v=a_w$. Again, this graph, with a choice of initial vertex, determines uniquely the
automorphism $a$. It is called the \emph{Mealy machine} associated with $a$. 

 Of particular interest are \emph{finite-state automorphisms}: these are automorphisms whose Mealy machine has finitely many states. The
product and inverse of finite-state automorphisms is again finite-state. 

 A subgroup $G \le W$ is \emph{self-similar} if $G^\phi \subset G\wr\mathop{Sym}(X)$. This is equivalent to asking, for every $a \in G$, that all of its states $a_x$ also belong to $G$. 

 The following important properties have also been considered. A subgroup $G \le W$ is \emph{level-transitive} if its action is transitive on all the $G$-subsets $X^n$. It is \emph{weakly branched} if it is level-transitive, and for every $v\in X^*$ there is a non-trivial $a_v\in G$ that fixes $X^* \setminus vX^*$. It is \emph{branched} if furthermore for each $n \in \mathbb N$ the group generated by all such $a_v$ for all $v$ of length $n$ has finite index in $G$. 

 A self-similar finitely generated group $G \le $ is \emph{contracting} if there are constants $K,n \in \mathbb N$ and $\lambda<1$ such that $|a_v|\le\lambda|a|+K$ for all $a\in G$ and $v\in X^n$; here $|a|$ denotes the minimal number of generators needed to express $a$. It then follows that there exists a finite set $N\subset G$ such that for all $a\in G$, all but finitely many of the states of $a$ belong to $N$. The minimal such $N$ is called the \emph{nucleus} of $G$. Since the states of elements of the nucleus are again in the nucleus, we see
that the nucleus is naturally a Mealy machine. By considering all elements of $W$ obtained from this Mealy machine by choosing all possible initial states, we
obtain a generating set for $G$ made of all states of a single machine; this is the \emph{group generated} by the machine. 

 In this package, we are mainly interested in self-similar groups of
finite-state automorphisms. The reason is historical: Aleshin \cite{MR713968}, and later Grigorchuk \cite{MR565099} and Gupta and Sidki \cite{MR696534} constructed peculiar examples of groups using self-similar finite-state
automorphisms. All these groups can be defined by drawing a small machine (at
most five vertices) and considering the group that they generate. 

 We assumed for simplicity that the elements $a$ were invertible. Actually, in the definition of Mealy machines it makes sense
to accept arbitrary maps, and not necessarily bijections of $X$ as a label at each vertex. One may in this way define peculiar semigroups. }

 
\section{\textcolor{Chapter }{An example session}}\label{frintro}
\logpage{[ 2, 2, 0 ]}
\hyperdef{L}{X78DF4DE18260BD80}{}
{
 This is a brief introduction describing some of the simpler features of the \textsf{FR} package. It assumes you have some familiarity with the theory of groups
defined by automata; if not, a brief mathematical introduction may be found in
Section \ref{mathintro}. We show here and comment a typical use of the package. 

 The package is installed by unpacking the archive in the \texttt{pkg/} directory of your \textsf{GAP} installation. It can also be placed in a local directory, which must be added
to the load-path by invoking \texttt{gap} with the \texttt{-l} option. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> LoadPackage("fr");
  ----------------------------------------------------------------
  Loading FR 0.857142p5 (Functionally recursive and automata groups)
  by Laurent Bartholdi (http://www.uni-math.gwdg.de/laurent)
  ----------------------------------------------------------------
  true
\end{Verbatim}
 Many FR groups are predefined by \textsf{FR}, see Chapter \ref{frexamples}. We consider here the \emph{Basilica group}, considered in \cite{MR1902367} and \cite{MR2176547}. 

 We may start by defining a group: it has two generators $a$ and $b$, satisfying the specified recursions. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> B := FRGroup("a=<1,b>(1,2)","b=<1,a>":IsFRElement);
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> AssignGeneratorVariables(B);
  #I  Assigned the global variables [ a, b ]
\end{Verbatim}
 We have just created the group $B=\langle a,b\rangle$. 

 Note that this group is predefined as \texttt{BasilicaGroup}. We now compute the decompositions of the generators: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> DecompositionOfFRElement(a); DecompositionOfFRElement(b);
  [ [ <2|identity ...>, <2|b> ], (1,2) ]
  [ [ <2|identity ...>, <2|a> ], () ]
\end{Verbatim}
 Elements are described as words in the generators; they are printed as \texttt{{\textless}2|a{\textgreater}}, where the $2$ reminds of the degree of the tree on which $a$ acts. 

 The optional argument \texttt{IsFRElement} (\ref{IsFRElement}) tells \textsf{FR} to store elements in this way. This representation is always possible, but it
is usually inefficient for calculations. The argument \texttt{IsMealyElement} (\ref{IsMealyElement}) forces \textsf{FR} to use a more efficient representation, which in some cases may take an
infinite time to set up. With no extra argument, \textsf{FR} does what it thinks is best. 

 Elements act on sequences over $\{1,2\}$. The action is computed in the standard manner: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> 1^a; [1]^a; [1,1]^a;
  2
  [ 2 ]
  [ 2, 1 ]
\end{Verbatim}
 Periodic sequences are also implemented in \textsf{FR}; they are constructed by giving the period and preperiod. The period is
printed by preceding it with a "/": 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> v := PeriodicList([1],[2]);
  [ 1, / 2 ]
  gap> v^a; v^(a^2);
  [/ 2 ]
  [/ 1, 2 ]
  gap> last{[1..10]};
  [ 1, 2, 1, 2, 1, 2, 1, 2, 1, 2 ]
\end{Verbatim}
 

 Most computations are much more efficient if $B$'s elements are converted to \emph{Mealy representation}, 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Bm := Image(IsomorphismMealyGroup(B));
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> a := Bm.1; b := Bm.2;
  <Mealy element on alphabet [ 1, 2 ] with 3 states, initial state 1>
  <Mealy element on alphabet [ 1, 2 ] with 3 states, initial state 1>
\end{Verbatim}
 This could have been done automatically by specifying \texttt{:IsMealyElement} as an option in the call to \texttt{FRGroup}. 

 The group $B$ is torsion-free, and its elements are bounded automata. Although
torsion-freeness is difficult to check for \textsf{FR}, it can be checked on individual elements: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> IsBoundedFRSemigroup(Bm);
  true
  gap> Order(a); Order(b);
  infinity
  infinity
  gap> g := PseudoRandom(B);; Length(InitialState(g));
  4679
  gap> Order(g); time;
  infinity
  2599
\end{Verbatim}
 

 The group $B$ is weakly branched; more precisely, the derived subgroup $B'$ contains $B' \times B'$. To prove that, it suffices to check $[a,b] \times 1\in B'$ and $1 \times [a,b]\in B'$. These elements are constructed using \texttt{VertexElement} (\ref{VertexElement}): 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> c := Comm(a,b);
  <Mealy element on alphabet [ 1, 2 ] with 9 states, initial state 1>
  gap> K := NormalClosure(Bm,Group(c));
  <self-similar group over [ 1 .. 2 ] with 3 generators>
  gap> VertexElement(1,c) in K; VertexElement(1,c) in K;
  true
  true
  gap> DecompositionOfFRElement(VertexElement(1,c)=[[c,One(Bm)],()];
  true
  gap> VertexElement(2,c)=Comm(b,a^2);
  true
\end{Verbatim}
 Note that we had to guess the form of the element \texttt{VertexElement(2,c)} above. This could have been found out by \textsf{GAP} using \texttt{ShortGroupWordInSet} (\ref{ShortGroupWordInSet}). 

 We may also check the relations $[b^p,(b^p)^{a^p}]=1$ and $[a^{2p},(a^{2p})^{b^p}]$ for $p$ any power of $2$: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> ForAll([0..10],i->IsOne(Comm(b^(2^i),(b^(2^i))^((a^(2^i)))))); time;
  true
  1361
\end{Verbatim}
 Since the group $B$ is bounded, it is contracting. We compute its nucleus: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> NucleusOfFRSemigroup(B);
  [ <2|identity ...>, <2|b>, <2|b^-1>, <2|a>, <2|a^-1>, <2|b^-1*a>, <2|a^-1*b> ]
\end{Verbatim}
 We then compute the Mealy machine with stateset this nucleus, and draw it
graphically (this requires the external programs \textsf{graphviz} and \textsf{imagemagick}): 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> N := NucleusMachine(B);
  <Mealy machine on alphabet [ 1, 2 ] with 7 states>
  gap> Draw(N);
\end{Verbatim}
 We may also draw powers of the dual automaton: these are approximations to the
Schreier graph of $B$. However, we also construct a smaller Mealy machine with states only $a$ and $b$, which give better images: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Draw(DualMachine(N)^3);
  gap> M := AsMealyMachine(FRMachine(a))[1];
  <Mealy machine on alphabet [ 1, 2 ] with 3 states>
  gap> Draw(DualMachine(M)^4);
\end{Verbatim}
 These Schreier graphs are orbits of the group; they can be displayed as
follows: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> WordGrowth(B:point:=[1,1,1,1],draw);
\end{Verbatim}
 More properties of $B$ can be checked, or experimented with, on its finite quotients obtained by
truncating the tree on which $B$ acts at a given length. \texttt{PermGroup(B,n)} constructs a permutation group which is the natural quotient of $B$ acting on $2^n$ points: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> G := PermGroup(B,7);
  <permutation group with 2 generators>
  gap> Size(G); LogInt(last,2);
  309485009821345068724781056
  88
\end{Verbatim}
 We may "guess" the structure of the Lie algebra of $B$ by examining the ranks of the successive quotients along its Jennings series: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> J := JenningsLieAlgebra(G); time;
  <Lie algebra of dimension 88 over GF(2)>
  18035
  gap> List([1..15],i->Dimension(Grading(J).hom_components(i)));
  [ 2, 3, 1, 4, 1, 2, 1, 4, 1, 2, 1, 3, 1, 2, 1 ]
\end{Verbatim}
 The "$4$" in position $8$ of that list should really be a "$5$"; computations on finite quotients of $B$ usually give lower bounds for invariants of $B$. In that case, we guess that the ranks behave like a "ruler" function, i.e.
that the rank of the homogeneous component of degree $i$ is $2+\nu_2(i)$ if $i$ is a power of $2$ and is $1+\nu_2(i)$ otherwise; here $\nu_2(i)$ is the number of times $2$ divides $i$. }

 }

 
\chapter{\textcolor{Chapter }{Functionally recursive machines}}\label{frmachines}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X7D65CA8B876E514C}{}
{
 At the core of this package are \emph{functionally recursive machines}. The internals of machine will be described later, but each machine $M$ has an associated \emph{alphabet} $X$, a \emph{set of states} $Q$, and a \emph{transition function} $\phi:Q \times X \to X \times Q$. An \emph{element}, as we will see in Section \ref{frelements}, is given by a machine and an initial state $q\in Q$. 

 The element $(M,q)$ defines a transformation on the set $X^*$ of strings (finite or infinite) over the alphabet $X$, as follows: the empty string is always fixed. Given a string $x_1x_2\dots x_n$ with $n\ge0$, compute $\phi(q,x_1)=(y_1,r)$; then compute the action of $(M,r)$ on the string $x_2\dots x_n$, and call the result $y_2\dots y_n$. Then the action of $(M,q)$ on $x_1x_2\dots x_n$ yields $y_1y_2\dots y_n$. 

 This can be understood more formally as follows. The transition function $\phi$ induces a map $\phi^n:Q\times X^n \to X^n \times Q$, defined by successively applying $\phi$ to move the $Q$ from the left to the right. Similarly, $\phi$ can be extended to a map $Q^m\times X^n \to X^n \times Q^m$. 

 We see that the action on finite strings preserves their length, and also
preserves prefixes: if $(M,q)$ maps $x_1\dots x_n$ to $y_1\dots y_m$, then necessarily $m=n$; and if $k<n$ then $T$ maps $x_1\dots x_k$ to $y_1\dots y_k$. 

 The strings over the alphabet $X$ can be naturally organised into a rooted tree. The root represents the empty
string, and the strings $x_1\dots x_n$ and $x_1\dots x_{n+1}$ are connected by an edge, for all $x_i\in X$. 
\section{\textcolor{Chapter }{Types of machines}}\label{frmachine-types}
\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X7D52F7ED83E2D153}{}
{
 Machines must be accessible to computation; therefore it is reasonable to
assume that their alphabet $X$ is finite. 

 If the stateset $Q$ is also finite, the machine is called a \emph{Mealy machine}, and its transition function $\phi$ can be stored as a table. 

 More general machines are obtained if one allows the stateset $Q$ to be a free group/semigroup/monoid generated by a finite set $S$, and the transition function $\phi$ to be specified on $S\times X$. Its values are then extended naturally by composition. 

 Machines store their transitions (second coordinate of $\phi$), and their output, (first coordinate of $\phi$) in a matrix indexed by state and letter. In particular, \texttt{PermList(output[state])} gives the action on the first level. 

 Because of the way \textsf{GAP} handles permutations and transformations, a permutation is never equal to a
transformation, even though both can answer \texttt{true} to $IsOne$. Therefore, \textsf{FR} introduces a new type of transformation, which can be equal to a permutation,
and which is actually represented as a permutation is it is invertible. Like
permutations, the new transformations do not have a fixed degree. They are
created by \texttt{Trans(list)}. }

 
\section{\textcolor{Chapter }{Products of machines}}\label{frmachine-products}
\logpage{[ 3, 2, 0 ]}
\hyperdef{L}{X7EB36FBB78F4F26A}{}
{
 Machines can be combined in different manners. If two machines act on the same
alphabet, then their \emph{sum} and \emph{product} are defined as machines acting again on the same alphabet; the statesets are
the free products (which is also their sum, in the category of semigroups) of
the respective statesets. The sum or product of machines has a stateset of
highest possible category, i.e. is a group unless some argument is a monoid,
and a monoid unless some argument is a semigroup. The transition and output
functions are the union of the respective functions of their arguments. 

 If a non-empty collection of machines have same stateset, then their \emph{tensor sum} and \emph{tensor product} are machines again with same stateset; the alphabets on which the machines act
are the disjoint union, respectively cartesian product, of the arguments'
alphabets. The transition and output functions are again the union or
composition of the respective functions of their arguments. 

 The \emph{direct sum} and \emph{direct product} of a collection of machines are always defined. Its stateset is generated by
the union of the arguments' statesets, as for a sum or a product; its alphabet
is the disjoint union, respectively cartesian product of its arguments'
alphabets, as for a tensor sum or product. The transition and output functions
are again the union of the respective functions of their arguments. }

 
\section{\textcolor{Chapter }{Creators for \texttt{FRMachine}s}}\logpage{[ 3, 3, 0 ]}
\hyperdef{L}{X828640667D2E5280}{}
{
 

\subsection{\textcolor{Chapter }{FRMachineNC (family,free,listlist,list)}}
\logpage{[ 3, 3, 1 ]}\nobreak
\hyperdef{L}{X80D310EF7FD5EA44}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRMachineNC({\slshape fam, free, transitions, outputs})\index{FRMachineNC@\texttt{FRMachineNC}!family,free,listlist,list}
\label{FRMachineNC:family,free,listlist,list}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new FR machine.



 This function constructs a new FR machine, belonging to family \mbox{\texttt{\slshape fam}}. It has stateset the free group/semigroup/monoid \mbox{\texttt{\slshape free}}, and transitions described by \mbox{\texttt{\slshape states}} and \mbox{\texttt{\slshape outputs}}. 

 \mbox{\texttt{\slshape transitions}} is a list of lists; \mbox{\texttt{\slshape transitions}}[\mbox{\texttt{\slshape s}}][\mbox{\texttt{\slshape x}}] is a word in \mbox{\texttt{\slshape free}}, which is the state reached by the machine when started in state \mbox{\texttt{\slshape s}} and fed input \mbox{\texttt{\slshape x}}. 

 \mbox{\texttt{\slshape outputs}} is also a list of lists; \mbox{\texttt{\slshape outputs}}[\mbox{\texttt{\slshape s}}][\mbox{\texttt{\slshape x}}] is the output produced by the machine is in state \mbox{\texttt{\slshape s}} and inputs \mbox{\texttt{\slshape x}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> f := FreeGroup(2);
  <free group on the generators [ f1, f2 ]>
  gap> m := FRMachineNC(FRMFamily([1,2]),f,[[One(f),f.1],[One(f),f.2^-1]],
                        [[2,1],[1,2]]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ f1, f2 ] )>
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{FRMachine ([list,]list,list)}}
\logpage{[ 3, 3, 2 ]}\nobreak
\hyperdef{L}{X808F3BD97EDA8CE8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRMachine({\slshape [names, ]transitions, outputs})\index{FRMachine@\texttt{FRMachine}![list,]list,list}
\label{FRMachine:[list,]list,list}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRMachine({\slshape free, transitions, outputs})\index{FRMachine@\texttt{FRMachine}!semigroup,list,list}
\label{FRMachine:semigroup,list,list}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new FR machine.



 This function constructs a new FR machine. It has stateset a free
group/semigroup/monoid, and structure described by \mbox{\texttt{\slshape transitions}} and \mbox{\texttt{\slshape outputs}}. 

 If there is an argument \mbox{\texttt{\slshape free}}, it is the free group/monoid/semigroup to be used as stateset. Otherwise, the
stateset will be guessed from the \mbox{\texttt{\slshape transitions}} and \mbox{\texttt{\slshape outputs}}; it will be a free group if all states are invertible, and a monoid
otherwise. \mbox{\texttt{\slshape names}} is then an optional list, with at position \mbox{\texttt{\slshape s}} a string naming generator \mbox{\texttt{\slshape s}} of the stateset. If \mbox{\texttt{\slshape names}} contains too few entries, they are completed by the names \mbox{\texttt{\slshape {\textunderscore}{\textunderscore}1,{\textunderscore}{\textunderscore}2,...}}. 

 \mbox{\texttt{\slshape transitions}} is a list of lists; \texttt{transitions[s][x]} is either an associative word, or a list of integers describing the state
reached by the machine when started in state \mbox{\texttt{\slshape s}} and fed input \mbox{\texttt{\slshape x}}. Positive integers indicate a generator index, negative integers its inverse,
the empty list in the identity state, and lists of length greater than one
indicate a product of states. If an entry is an FR element, then its machine
is incorporated into the newly constructed one. 

 \mbox{\texttt{\slshape outputs}} is a list; at position \mbox{\texttt{\slshape s}} it contains a permutation, a transformation, or a list of integers (the images
of a transformation), describing the activity of state \mbox{\texttt{\slshape s}}. If all states are invertible, the outputs are all converted to permutations,
while if there is a non-invertible state then the outputs are all converted to
transformations. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := FRMachine(["tau","mu"],[[[],[1]],[[],[-2]]],[(1,2),(1,2)]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ tau, mu ] )>
  gap> m=n;
  true
  gap> Display(n);
       |     1         2
  -----+--------+---------+
   tau | <id>,2     tau,1
    mu | <id>,2   mu^-1,1
  -----+--------+---------+
  gap> m := FRMachine([[[],[FRElement(n,1)]]],[()]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ f1, f2, f3 ] )>
  gap> Display(m);
      |     1         2
  ----+--------+---------+
   f1 | <id>,1      f2,2
   f2 | <id>,2      f2,1
   f3 | <id>,2   f1^-1,1
  ----+--------+---------+
  gap> f := FreeGroup(2);
  <free group on the generators [ f1, f2 ]>
  gap> p := FRMachine(f,[[One(f),f.1],[One(f),f.2^-1],[(1,2),(1,2)]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ f1, f2 ] )>
  gap> n=p;
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{UnderlyingFRMachine}}
\logpage{[ 3, 3, 3 ]}\nobreak
\hyperdef{L}{X7C383F4383D22BFC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{UnderlyingFRMachine({\slshape obj})\index{UnderlyingFRMachine@\texttt{UnderlyingFRMachine}}
\label{UnderlyingFRMachine}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
An FR machine underlying \mbox{\texttt{\slshape obj}}.



 FR elements, FR groups etc. often have an underlying FR machine, which is
returned by this command. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ a, b ] )>
  gap> a := FRElement(m,1); b := FRElement(m,2);
  <2|a>
  <2|b>
  gap> UnderlyingFRMachine(a)=m;
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AsGroupFRMachine}}
\logpage{[ 3, 3, 4 ]}\nobreak
\hyperdef{L}{X7BF186227C0ABE8D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsGroupFRMachine({\slshape m})\index{AsGroupFRMachine@\texttt{AsGroupFRMachine}}
\label{AsGroupFRMachine}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsMonoidFRMachine({\slshape m})\index{AsMonoidFRMachine@\texttt{AsMonoidFRMachine}}
\label{AsMonoidFRMachine}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsSemigroupFRMachine({\slshape m})\index{AsSemigroupFRMachine@\texttt{AsSemigroupFRMachine}}
\label{AsSemigroupFRMachine}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
An FR machine isomorphic to \mbox{\texttt{\slshape m}}, on a free group.



 This function constructs, from the FR machine \mbox{\texttt{\slshape m}}, an isomorphic FR machine \texttt{n} with a free group/monoid/semigroup as stateset. The attribute \texttt{Correspondence(n)} is a mapping (homomorphism or list) from the stateset of \mbox{\texttt{\slshape m}} to the stateset of \texttt{n}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> s := FreeSemigroup(1);;
  gap> sm := FRMachine(s,[[GeneratorsOfSemigroup(s)[1],
                           GeneratorsOfSemigroup(s)[1]^2]],[(1,2)]);
  <FR machine with alphabet [ 1 .. 2 ] on Semigroup( [ s1 ] )>
  gap> m := FreeMonoid(1);;
  gap> mm := FRMachine(m,[[One(m),GeneratorsOfMonoid(m)[1]^2]],[(1,2)]);
  <FR machine with alphabet [ 1 .. 2 ] on Monoid( [ m1 ], ... )>
  gap> g := FreeGroup(1);;
  gap> gm := FRMachine(g,[[One(g),GeneratorsOfGroup(g)[1]^-2]],[(1,2)]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ f1 ] )>
  gap> AsGroupFRMachine(sm); Display(last);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ f1 ] )>
      |   1        2
  ----+------+--------+
   f1 | f1,2   f1^2,1
  ----+------+--------+
  gap> Correspondence(last);
  MappingByFunction( <free semigroup on the generators
  [ s1 ]>, <free group on the generators [ f1 ]>, function( w ) ... end )
  gap> AsGroupFRMachine(mm); Display(last);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ f1 ] )>
      |     1        2
  ----+--------+--------+
   f1 | <id>,2   f1^2,1
  ----+--------+--------+
  gap> AsGroupFRMachine(gm); Display(last);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ f1 ] )>
      |     1         2
  ----+--------+---------+
   f1 | <id>,2   f1^-2,1
  ----+--------+---------+
  gap> AsMonoidFRMachine(sm); Display(last);
  <FR machine with alphabet [ 1 .. 2 ] on Monoid( [ m1 ], ... )>
      |   1        2
  ----+------+--------+
   m1 | m1,2   m1^2,1
    ----+------+--------+
  gap> AsMonoidFRMachine(mm); Display(last);
  <FR machine with alphabet [ 1 .. 2 ] on Monoid( [ m1 ], ... )>
      |     1        2
  ----+--------+--------+
   m1 | <id>,2   m1^2,1
  ----+--------+--------+
  gap> AsMonoidFRMachine(gm); Display(last);
  <FR machine with alphabet [ 1 .. 2 ] on Monoid( [ m1, m2 ], ... )>
      |     1        2
  ----+--------+--------+
   m1 | <id>,2   m2^2,1
   m2 | m1^2,2   <id>,1
  ----+--------+--------+
  gap> AsSemigroupFRMachine(sm); Display(last);
  <FR machine with alphabet [ 1 .. 2 ] on Semigroup( [ s1 ] )>
      |   1        2
  ----+------+--------+
   s1 | s1,2   s1^2,1
  ----+------+--------+
  gap> AsSemigroupFRMachine(mm); Display(last);
  <FR machine with alphabet [ 1 .. 2 ] on Semigroup( [ s1, s2 ] )>
      |   1        2
  ----+------+--------+
   s1 | s2,2   s1^2,1
   s2 | s2,1     s2,2
  ----+------+--------+
  gap> AsSemigroupFRMachine(gm); Display(last);
  <FR machine with alphabet [ 1 .. 2 ] on Semigroup( [ s1, s2, s3 ] )>
      |     1        2
  ----+--------+--------+
   s1 |   s3,2   s2^2,1
   s2 | s1^2,2     s3,1
   s3 |   s3,1     s3,2
  ----+--------+--------+
  gap>
  gap> Display(GuptaSidkiMachines(3));
     |  1     2     3
  ---+-----+-----+-----+
   a | a,1   a,2   a,3
   b | a,2   a,3   a,1
   c | a,3   a,1   a,2
   d | b,1   c,2   d,3
  ---+-----+-----+-----+
  gap> AsGroupFRMachine(GuptaSidkiMachines(3));
  <FR machine with alphabet [ 1 .. 3 ] on Group( [ f1, f2 ] )>
  gap> Display(last);
      |     1         2        3
  ----+--------+---------+--------+
   f1 | <id>,2    <id>,3   <id>,1
   f2 |   f1,1   f1^-1,2     f2,3
  ----+--------+---------+--------+
  gap> Correspondence(last);
  [ <identity ...>, f1, f1^-1, f2 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ChangeFRMachineBasis}}
\logpage{[ 3, 3, 5 ]}\nobreak
\hyperdef{L}{X814F53B97C3F43F5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ChangeFRMachineBasis({\slshape m[, l]})\index{ChangeFRMachineBasis@\texttt{ChangeFRMachineBasis}}
\label{ChangeFRMachineBasis}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
An equivalent FR machine, in a new basis.



 This function constructs a new group FR machine, given a group FR machine \mbox{\texttt{\slshape m}} and a list of states \mbox{\texttt{\slshape l}} (as elements of the free object \texttt{StateSet(m)}). 

 The new machine has the following transitions: if alphabet letter \texttt{a} is mapped to \texttt{b} by state \texttt{s} in \mbox{\texttt{\slshape m}}, leading to state \texttt{t}, then in the new machine the new state is \texttt{l[a]\texttt{\symbol{94}}-1*t*l[b]}. 

 The group generated by the new machine is isomorphic to the group generated by \mbox{\texttt{\slshape m}}. This command amounts to a change of basis of the associated bimodule (see \cite[Section 2.2]{MR2162164}). It amounts to conjugation by the automorphism \texttt{c=FRElement("c",[l[1]*c,...,l[n]*c],[()],1)}. 

 If the second argument is absent, this command attempts to choose one that
makes many entries of the recursion trivial. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := FRMachine(["tau","mu"],[[[],[1]],[[],[-2]]],[(1,2),(1,2)]);;
  gap> Display(n);
   G   |     1         2
  -----+--------+---------+
   tau | <id>,2     tau,1
    mu | <id>,2   mu^-1,1
  -----+--------+---------+
  gap> nt := ChangeFRMachineBasis(n,GeneratorsOfFRMachine(n){[1,1]});;
  gap> Display(nt);
   G   |     1                    2
  -----+--------+--------------------+
   tau | <id>,2                tau,1
    mu | <id>,2   tau^-1*mu^-1*tau,1
  -----+--------+--------------------+
\end{Verbatim}
 }

 }

 
\section{\textcolor{Chapter }{Attributes for \texttt{FRMachine}s}}\logpage{[ 3, 4, 0 ]}
\hyperdef{L}{X8753FA157B2AD6DC}{}
{
 

\subsection{\textcolor{Chapter }{StateSet (FR machine)}}
\logpage{[ 3, 4, 1 ]}\nobreak
\hyperdef{L}{X8000470D7DA7FFBD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StateSet({\slshape m})\index{StateSet@\texttt{StateSet}!FR machine}
\label{StateSet:FR machine}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
The set of states associated with \mbox{\texttt{\slshape m}}.



 This function returns the stateset of \mbox{\texttt{\slshape m}}. It can be either a list (if the machine is of Mealy type), or a free
group/semigroup/monoid (in all other cases). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := FRMachine(["tau","mu"],[[[],[1]],[[],[-2]]],[(1,2),(1,2)]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ tau, mu ] )>
  gap> StateSet(n);
  <free group on the generators [ tau, mu ]>
  gap> StateSet(AsMealyMachine(n));
  [ 1 .. 4 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{GeneratorsOfFRMachine}}
\logpage{[ 3, 4, 2 ]}\nobreak
\hyperdef{L}{X7F77F5DD789FA2F4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GeneratorsOfFRMachine({\slshape m})\index{GeneratorsOfFRMachine@\texttt{GeneratorsOfFRMachine}}
\label{GeneratorsOfFRMachine}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
The generating set of the stateset of \mbox{\texttt{\slshape m}}.



 This function returns the generating set of the stateset of \mbox{\texttt{\slshape machine}}. If \mbox{\texttt{\slshape m}} is a Mealy machine, it returs the stateset. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := FRMachine(["tau","mu"],[[[],[1]],[[],[-2]]],[(1,2),(1,2)]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ tau, mu ] )>
  gap> GeneratorsOfFRMachine(n);
  [ tau, mu ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Output (FR machine,state)}}
\logpage{[ 3, 4, 3 ]}\nobreak
\hyperdef{L}{X80B52A8A7F30878E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Output({\slshape m, s})\index{Output@\texttt{Output}!FR machine,state}
\label{Output:FR machine,state}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Output({\slshape m, s, x})\index{Output@\texttt{Output}!FR machine,state,letter}
\label{Output:FR machine,state,letter}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A transformation of \mbox{\texttt{\slshape m}}'s alphabet.



 This function returns the transformation of \mbox{\texttt{\slshape m}}'s alphabet associated with state \mbox{\texttt{\slshape s}}. This transformation is returned as a list of images. 

 \mbox{\texttt{\slshape s}} is also allowed to be a list, in which case it is interpreted as the
corresponding product of states. 

 In the second form, the result is actually the image of \mbox{\texttt{\slshape x}} under \texttt{Output(m,s)}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ a, b ] )>
  gap> Output(n,[1,2]);
  [2,1]
  gap> Output(n,Product(GeneratorsOfFRMachine(n)));
  [2,1]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Transition (FR machine,state,input)}}
\logpage{[ 3, 4, 4 ]}\nobreak
\hyperdef{L}{X7AEE87BC8393FA54}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Transition({\slshape m, s, i})\index{Transition@\texttt{Transition}!FR machine,state,input}
\label{Transition:FR machine,state,input}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
An element of \mbox{\texttt{\slshape m}}'s stateset.



 This function returns the state reached by \mbox{\texttt{\slshape m}} when started in state \mbox{\texttt{\slshape s}} and fed input \mbox{\texttt{\slshape i}}. This input may be an alphabet letter or a sequence of alphabet letters. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ a, b ] )>
  gap> Transition(n,[2,1],2);
  a*b
  gap> Transition(n,Product(GeneratorsOfFRMachine(n))^2,1);
  a*b
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{WreathRecursion}}
\logpage{[ 3, 4, 5 ]}\nobreak
\hyperdef{L}{X7D95D1498586E5D0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WreathRecursion({\slshape machine})\index{WreathRecursion@\texttt{WreathRecursion}}
\label{WreathRecursion}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
A function on the stateset of \mbox{\texttt{\slshape machine}}.



 This function returns a function on \mbox{\texttt{\slshape machine}}'s stateset. This function, on receiving state \mbox{\texttt{\slshape q}} as input, returns a list. Its first entry is a list indexed by \mbox{\texttt{\slshape machine}}'s alphabet, with in position \mbox{\texttt{\slshape x}} the state \mbox{\texttt{\slshape machine}} would be in if it received input \mbox{\texttt{\slshape x}} when in state \mbox{\texttt{\slshape q}}. The second entry is the list of the permutation of \mbox{\texttt{\slshape machine}}'s alphabet induced by \mbox{\texttt{\slshape q}}. 

 \mbox{\texttt{\slshape WreathRecursion(machine)(q)[1][a]}} is equal to \mbox{\texttt{\slshape Transition(machine,q,a)}} and \mbox{\texttt{\slshape WreathRecursion(machine)(q)[2]}} is equal to \mbox{\texttt{\slshape Output(machine,q)}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ a, b ] )>
  gap> WreathRecursion(n)(GeneratorsOfFRMachine(n)[1]);
  [ [ <identity ...>, b ], [2,1] ]
  gap> WreathRecursion(n)(GeneratorsOfFRMachine(n)[2]);
  [ [ <identity ...>, a ], [1,2] ]
\end{Verbatim}
 }

 }

 
\section{\textcolor{Chapter }{Operations for \texttt{FRMachine}s}}\logpage{[ 3, 5, 0 ]}
\hyperdef{L}{X8158A8307CA98A3D}{}
{
 

\subsection{\textcolor{Chapter }{StructuralGroup}}
\logpage{[ 3, 5, 1 ]}\nobreak
\hyperdef{L}{X8289C2F77D67EDC3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StructuralGroup({\slshape machine})\index{StructuralGroup@\texttt{StructuralGroup}}
\label{StructuralGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StructuralMonoid({\slshape machine})\index{StructuralMonoid@\texttt{StructuralMonoid}}
\label{StructuralMonoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StructuralSemigroup({\slshape machine})\index{StructuralSemigroup@\texttt{StructuralSemigroup}}
\label{StructuralSemigroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A finitely presented group/monoid/semigroup capturing the structure of \mbox{\texttt{\slshape machine}}.



 This function returns a finitely presented group/monoid/semigroup, with
generators the union of the \texttt{AlphabetOfFRObject} (\ref{AlphabetOfFRObject}) and \texttt{GeneratorsOfFRMachine} (\ref{GeneratorsOfFRMachine}) of \mbox{\texttt{\slshape machine}}, and relations all $qa'=aq'$ whenever $\phi(q,a)=(a',q')$. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := FRMachine(["a","b","c"],[[[2],[3]],[[3],[2]],[[1],[1]]],[(1,2),(1,2),()]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ a, b, c ] )>
  gap> StructuralGroup(n);
  <fp group on the generators [ a, b, c, 1, 2 ]>
  gap> RelatorsOfFpGroup(last);
  [ a*2*b^-1*1^-1, a*1*c^-1*2^-1, b*2*c^-1*1^-1,
    b*1*b^-1*2^-1, c*1*a^-1*1^-1, c*2*a^-1*2^-1 ]
  gap> SimplifiedFpGroup(last2);
  <fp group on the generators [ a, 1 ]>
  gap> RelatorsOfFpGroup(last);
  [ 1^-1*a^2*1^4*a^-2*1^-1*a*1^-2*a^-1, 1*a*1^-1*a*1^2*a^-1*1*a^-2*1^-3*a,
    1^-1*a^2*1^2*a^-1*1^-1*a*1^2*a^-2*1^-2 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{\texttt{\symbol{92}}+}}
\logpage{[ 3, 5, 2 ]}\nobreak
\hyperdef{L}{X7F2703417F270341}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{\texttt{\symbol{92}}+({\slshape machine1, machine2})\index{+@\texttt{\texttt{\symbol{92}}+}}
\label{+}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
A new FR machine, in the same family as its arguments.



 This function returns a new FR machine, with stateset generated by the union
of the statesets of its arguments. The arguments \mbox{\texttt{\slshape machine1}} and \mbox{\texttt{\slshape machine2}} must operate on the same alphabet. If the stateset of \mbox{\texttt{\slshape machine1}} is free on $n_1$ letters and the stateset of \mbox{\texttt{\slshape machine2}} is free on $n_2$ letters, then the stateset of their sum is free on $n_1+n_2$ letters, with the first $n_1$ identified with \mbox{\texttt{\slshape machine1}}'s states and the next $n_2$ with \mbox{\texttt{\slshape machine2}}'s. 

 The transition and output functions are naturally extended to the sum. 

 The arguments may be free groups, semigroups or monoid machines. The sum is in
the weakest containing category: it is a group machine if both arguments are
group machines; a monoid if both are either group of monoid machines; and a
semigroup machine otherwise. 

 The maps from the stateset of \mbox{\texttt{\slshape machine1}} or \mbox{\texttt{\slshape machine2}} to the stateset of the result \texttt{r} can be recovered as \texttt{Correspondence(r)[1]} and \texttt{Correspondence(r)[2]}; see \texttt{Correspondence} (\ref{Correspondence:FR machine}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> tau := FRMachine([[[],[1]]],[(1,2)]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ f1 ] )>
  gap> mu := FRMachine([[[],[-1]]],[(1,2)]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ f1 ] )>
  gap> sum := tau+mu;; Display(sum);
       |     1          2
  -----+--------+----------+
   f11 | <id>,2      f11,1
   f12 | <id>,2   f12^-1,1
  -----+--------+----------+
  gap> Correspondence(sum)[1];
  [ f1 ] -> [ f11 ]
  gap> GeneratorsOfFRMachine(tau)[1]^last;
  f11
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{\texttt{\symbol{92}}*}}
\logpage{[ 3, 5, 3 ]}\nobreak
\hyperdef{L}{X7857704878577048}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{\texttt{\symbol{92}}*({\slshape machine1, machine2})\index{*@\texttt{\texttt{\symbol{92}}*}}
\label{*}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
A new FR machine, in the same family as its arguments.



 The product of two FR machines coincides with their sum, since the natural
free object mapping to the product of the statesets is generated by the union
of the statesets. See therefore \texttt{\texttt{\symbol{92}}+} (\ref{+}). }

 

\subsection{\textcolor{Chapter }{TensorSumOp (FR Machines)}}
\logpage{[ 3, 5, 4 ]}\nobreak
\hyperdef{L}{X7C0677148107F7FE}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TensorSumOp({\slshape FR{\textunderscore}machines, machine})\index{TensorSumOp@\texttt{TensorSumOp}!FR Machines}
\label{TensorSumOp:FR Machines}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
A new FR machine on the disjoint union of the arguments' alphabets.



 The tensor sum of FR machines with same stateset is defined as the FR machine
acting on the disjoint union of the alphabets; if these alphabets are \texttt{[1..n1]} up to \texttt{[1..nk]}, then the alphabet of their sum is \texttt{[1..n1+...+nk]} and the transition functions are similarly concatenated. 

 The first argument is a list; the second argument is any element of that list,
and is used only to improve the method selection algorithm. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := TensorSum(AddingMachine(2),AddingMachine(3),AddingMachine(4));
  AddingMachine(2)(+)AddingMachine(3)(+)AddingMachine(4)
  gap> Display(m);
     |  1     2     3     4     5     6     7     8     9
  ---+-----+-----+-----+-----+-----+-----+-----+-----+-----+
   a | a,1   a,2   a,3   a,4   a,5   a,6   a,7   a,8   a,9
   b | a,2   b,1   a,4   a,5   b,3   a,7   a,8   a,9   b,6
  ---+-----+-----+-----+-----+-----+-----+-----+-----+-----+
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{TensorProductOp (FR Machines)}}
\logpage{[ 3, 5, 5 ]}\nobreak
\hyperdef{L}{X8077C8A47E22FCB5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TensorProductOp({\slshape FR, machines, machine})\index{TensorProductOp@\texttt{TensorProductOp}!FR Machines}
\label{TensorProductOp:FR Machines}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
A new FR machine on the cartesian product of the arguments' alphabets.



 The tensor product of FR machines with same stateset is defined as the FR
machine acting on the cartesian product of the alphabets. The transition
function and output function behave as if a single letter, in the tensor
product's alphabet, were a word (read from left to right) in the machines'
alphabets. 

 The first argument is a list; the second argument is any element of that list,
and is used only to improve the method selection algorithm. 

 Due to an overloading problem in the GAP library, the user-level command is
temporarily renamed \texttt{TensorProductX}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := TensorProductX(AddingMachine(2),AddingMachine(3));
  AddingMachine(2)(*)AddingMachine(3)
  gap> Display(last);
     |  1     2     3     4     5     6
  ---+-----+-----+-----+-----+-----+-----+
   a | a,1   a,2   a,3   a,4   a,5   a,6
   b | a,4   a,5   a,6   a,2   a,3   b,1
  ---+-----+-----+-----+-----+-----+-----+
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{DirectSumOp (FR Machines)}}
\logpage{[ 3, 5, 6 ]}\nobreak
\hyperdef{L}{X7D248C737D29A7CC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DirectSumOp({\slshape FR, machines, machine})\index{DirectSumOp@\texttt{DirectSumOp}!FR Machines}
\label{DirectSumOp:FR Machines}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
A new FR machine on the disjoint union of the arguments' alphabets.



 The direct sum of FR machines is defined as the FR machine with stateset
generated by the disjoint union of the statesets, acting on the disjoint union
of the alphabets; if these alphabets are \texttt{[1..n1]} up to \texttt{[1..nk]}, then the alphabet of their sum is \texttt{[1..n1+...+nk]} and the output and transition functions are similarly concatenated. 

 The first argument is a list; the second argument is any element of that list,
and is used only to improve the method selection algorithm. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := DirectSum(AddingMachine(2),AddingMachine(3),AddingMachine(4));
  AddingMachine(2)#AddingMachine(3)#AddingMachine(4)
  gap> Display(m);
     |  1     2     3     4     5     6     7     8     9
  ---+-----+-----+-----+-----+-----+-----+-----+-----+-----+
   a | a,1   a,2   a,3   a,4   a,5   a,6   a,7   a,8   a,9
   b | a,2   b,1   b,3   b,4   b,5   b,6   b,7   b,8   b,9
   c | c,1   c,2   a,3   a,4   a,5   c,6   c,7   c,8   c,9
   d | d,1   d,2   a,4   a,5   b,3   d,6   d,7   d,8   d,9
   e | e,1   e,2   e,3   e,4   e,5   a,6   a,7   a,8   a,9
   f | f,1   f,2   f,3   f,4   f,5   a,7   a,8   a,9   b,6
  ---+-----+-----+-----+-----+-----+-----+-----+-----+-----+
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{DirectProductOp (FR Machines)}}
\logpage{[ 3, 5, 7 ]}\nobreak
\hyperdef{L}{X81456F10820CAC87}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DirectProductOp({\slshape FR, machines, machine})\index{DirectProductOp@\texttt{DirectProductOp}!FR Machines}
\label{DirectProductOp:FR Machines}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
A new FR machine on the cartesian product of the arguments' alphabets.



 The direct product of FR machines is defined as the FR machine with stateset
generated by the product of the statesets, acting on the product of the
alphabets; if these alphabets are \texttt{[1..n1]} up to \texttt{[1..nk]}, then the alphabet of their product is \texttt{[1..n1*...*nk]} and the output and transition functions act component-wise. 

 The first argument is a list; the second argument is any element of that list,
and is used only to improve the method selection algorithm. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := DirectProduct(AddingMachine(2),AddingMachine(3));
  AddingMachine(2)xAddingMachine(3)
  gap> Display(last);
     |  1     2     3     4     5     6
  ---+-----+-----+-----+-----+-----+-----+
   a | a,1   a,2   a,3   a,4   a,5   a,6
   b | a,2   a,3   b,1   a,5   a,6   b,4
   c | a,4   a,5   a,6   c,1   c,2   c,3
   d | a,5   a,6   b,4   c,2   c,3   d,1
  ---+-----+-----+-----+-----+-----+-----+
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{TreeWreathProduct (FR machine)}}
\logpage{[ 3, 5, 8 ]}\nobreak
\hyperdef{L}{X7A0858097AA3FBDA}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TreeWreathProduct({\slshape m, n, x0, y0})\index{TreeWreathProduct@\texttt{TreeWreathProduct}!FR machine}
\label{TreeWreathProduct:FR machine}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
A new FR machine on the cartesian product of the arguments' alphabets.



 The \emph{tree-wreath product} of two FR machines is a machine acting on the product of its arguments'
alphabets $X,Y$, in such a way that many images of the first machine's states under
conjugation by the second commute. 

 It is introduced (in lesser generality, and with small variations) in \cite{MR2197828}, and may be described as follows: one takes two copies of the stateset of \mbox{\texttt{\slshape m}}, one copy of the stateset of \mbox{\texttt{\slshape n}}, and, if necessary, an extra identity state. 

 The first copy of \mbox{\texttt{\slshape m}} fixes the alphabet $X\times Y$; its state $\tilde s$ has transitions to the identity except $\tilde s$ at $(x0,y0)$ and $s$ at $(*,y0)$ for any other $*$. The second copy of \mbox{\texttt{\slshape m}} is also trivial except that, on input $(x,y0)$, its state $s$ goes to state $s'$ with output $(x',y0)$ whenever $s$ originally went, on input $x$, to state $s'$ with output $x'$. This copy of \mbox{\texttt{\slshape m}} therefore acts only in the $X$ direction, on the subtree $(X\times\{y0\})^\infty$, on subtrees below vertices of the form $(x0,y0)^t(x,y0)$. 

 A state $t$ in the copy of \mbox{\texttt{\slshape n}} maps the input $(x,y)$ to $(x,y')$ and proceeds to state $t'$ if $y=y0$, and to the identity state otherwise, when on input $y$ the original machine mapped state $t$ to output $t'$ and output $y'$. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := TreeWreathProduct(AddingMachine(2),AddingMachine(3),1,1);
  AddingMachine(2)~AddingMachine(3)
  gap> Display(last);
     |  1     2     3     4     5     6
  ---+-----+-----+-----+-----+-----+-----+
   a | c,2   c,3   a,1   c,5   c,6   c,4
   b | c,4   c,2   c,3   b,1   c,5   c,6
   c | c,1   c,2   c,3   c,4   c,5   c,6
   d | d,1   c,2   c,3   b,4   c,5   c,6
  ---+-----+-----+-----+-----+-----+-----+
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{SubFRMachine}}
\logpage{[ 3, 5, 9 ]}\nobreak
\hyperdef{L}{X811B5BF17A3FE577}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SubFRMachine({\slshape machine1, machine2})\index{SubFRMachine@\texttt{SubFRMachine}}
\label{SubFRMachine}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
Either \texttt{fail} or an embedding of the states of \mbox{\texttt{\slshape machine2}} in the states of \mbox{\texttt{\slshape machine1}}.



 This function attempts to locate a copy of \mbox{\texttt{\slshape machine2}} in \mbox{\texttt{\slshape machine1}}. If is succeeds, it returns a homomorphism from the stateset of \mbox{\texttt{\slshape machine2}} into the stateset of \mbox{\texttt{\slshape machine1}}; otherwise it returns \texttt{fail}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := FRMachine(["tau","mu"],[[[],[1]],[[],[-2]]],[(1,2),(1,2)]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ tau, mu ] )>
  gap> tauinv := FRMachine([[[1],[]]],[(1,2)]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ f1 ] )>
  gap> SubFRMachine(n,tauinv);
  [ f1 ] -> [ tau^-1 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Minimized (FR machine)}}
\logpage{[ 3, 5, 10 ]}\nobreak
\hyperdef{L}{X81B382BD81B2BD34}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Minimized({\slshape m})\index{Minimized@\texttt{Minimized}!FR machine}
\label{Minimized:FR machine}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A minimized machine equivalent to \mbox{\texttt{\slshape m}}.



 This function attempts to construct a machine equivalent to \mbox{\texttt{\slshape m}}, but with a stateset of smaller rank. Identical generators are collapsed to a
single generator of the stateset; if \mbox{\texttt{\slshape m}} is a group or monoid machine then trivial generators are removed; if \mbox{\texttt{\slshape m}} is a group machine then mutually inverse generators are grouped. This function
sets as \texttt{Correspondence(result)} a mapping between the stateset of \mbox{\texttt{\slshape m}} and the stateset of the result; see \texttt{Correspondence} (\ref{Correspondence:FR machine}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := FRMachine(["tau","mu"],[[[],[1]],[[],[-2]]],[(1,2),(1,2)]);;
  gap> m := FRMachine(["tauinv"],[[[1],[]]],[(1,2)]);;
  gap> sum := n+m+n;
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ tau1, mu1, tauinv1, tau2, mu2 ] )>
  gap> min := Minimized(sum);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ tau1, mu1 ] )>
  gap> Correspondence(min);
  [ tau1, mu1, tauinv1, tau2, mu2 ] -> [ tau1, mu1, tau1^-1, tau1, mu1 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Correspondence (FR machine)}}
\logpage{[ 3, 5, 11 ]}\nobreak
\hyperdef{L}{X7C107A42815F91DA}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Correspondence({\slshape m})\index{Correspondence@\texttt{Correspondence}!FR machine}
\label{Correspondence:FR machine}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
A mapping between statesets of FR machines.



 If a machine \mbox{\texttt{\slshape m}} was created as a minimized group/monoid/semigroup machine, then \texttt{Correspondence(m)} is a mapping between the stateset of the original machine and the stateset of \mbox{\texttt{\slshape m}}. See \texttt{Minimized} (\ref{Minimized:FR machine}) for an example. 

 If \mbox{\texttt{\slshape m}} was created as a minimized Mealy machine, then \texttt{Correspondence(m)} is a list identifying, for each state of the original machine, a state of the
new machine. If the original state is inaccessible, the corresponding list
entry is unbound. See \texttt{Minimized} (\ref{Minimized:Mealy machine}) for an example. 

 If \mbox{\texttt{\slshape m}} was created using \texttt{AsGroupFRMachine} (\ref{AsGroupFRMachine}), \texttt{AsMonoidFRMachine} (\ref{AsMonoidFRMachine}), \texttt{AsSemigroupFRMachine} (\ref{AsSemigroupFRMachine}), or \texttt{AsMealyMachine} (\ref{AsMealyMachine:FR machine}), then \texttt{Correspondence(m)} is a list or a homomorphism identifying for each generator of the original
machine a generator, or word in the generators, of the new machine. It is a
list if either the original or the final machine is a Mealy machine, and a
homomorphism in other cases. 

 If \mbox{\texttt{\slshape m}} was created as a sum of two machines, then \mbox{\texttt{\slshape m}} has a mapping \texttt{Correspondence(m)[i]} between the stateset of machine \texttt{i=1,2} and its own stateset. See \texttt{\texttt{\symbol{92}}+} (\ref{+}) for an example. }

 }

 }

 
\chapter{\textcolor{Chapter }{Functionally recursive elements}}\label{frelements}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X863D82207A1320F1}{}
{
 A \emph{functionally recursive element} is given by a functionally recursive machine and an initial state $q$. Many functions for FR machines, which accept a state as an argument, apply
to FR elements. In that case, no state is passed to the function. 

 The main function of FR elements is to serve as group/monoid/semigroup
elements: they can be multiplied and divided, and they act naturally on
sequences. They can also be tested for equality, and can be sorted. 

 FR elements are stored as free group/monoid/semigroup words. They are printed
as \texttt{{\textless}n|w{\textgreater}}, where \texttt{n} is the degree of their alphabet. 

 Equality of FR elements is tested as follows. Given FR elements $(m,q)$ and $(m,r)$, we set up a "rewriting system" for $m$, which records a purported set of relations among states of $m$. We start by an empty rewriting system, and we always ensure that the
rewriting system is reduced and shortlex-reducing. Then, to compare $q$ and $r$, we first compare their activities. If they differ, the elements are
distinct. Otherwise, we reduce $q$ and $r$ using the rewriting system. If the resulting words are graphically equal, then
they are equal. Otherwise, we add the rule $q\to r$ or $r\to q$ to the rewriting system, and proceed recursively to compare coordinatewise the
states of these reduced words. As a bonus, we keep the rewriting system to
speed up future comparisons. 

 Efficient comparison requires lookup in sorted lists, aka "Sets". Given two FR
elements $x$ and $y$, we declare that $x<y$ if, for the shortlex-first sequence $l$ such that \texttt{Output(Transition(x,l))} and \texttt{Output(Transition(y,l))} differ, the former is less than the latter (compared as lists). In fact, a
single internal function compares $x$ and $y$ and returns $-1,0,1$ depending on whether $x<y$ or $x=y$ or $x>y$. It traverses, in breadth first fashion, the alphabet sequences, and stops
either when provably $x=y$ or if different outputs appear. 
\section{\textcolor{Chapter }{Creators for \texttt{FRElement}s}}\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X79DE08CD7EE57360}{}
{
 

\subsection{\textcolor{Chapter }{FRElementNC (family,free,listlist,list,assocword)}}
\logpage{[ 4, 1, 1 ]}\nobreak
\hyperdef{L}{X7839813183881054}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRElementNC({\slshape fam, free, transitions, outputs, init})\index{FRElementNC@\texttt{FRElementNC}!family,free,listlist,list,assocword}
\label{FRElementNC:family,free,listlist,list,assocword}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new FR element.



 This function constructs a new FR element, belonging to family \mbox{\texttt{\slshape fam}}. It has stateset the free group/semigroup/monoid \mbox{\texttt{\slshape free}}, and transitions described by \mbox{\texttt{\slshape states}} and \mbox{\texttt{\slshape outputs}}, and initial states \mbox{\texttt{\slshape init}}. 

 \mbox{\texttt{\slshape transitions}} is a list of lists; \mbox{\texttt{\slshape transitions}}[\mbox{\texttt{\slshape s}}][\mbox{\texttt{\slshape x}}] is a word in \mbox{\texttt{\slshape free}}, which is the state reached by the machine when started in state \mbox{\texttt{\slshape s}} and fed input \mbox{\texttt{\slshape x}}. 

 \mbox{\texttt{\slshape outputs}} is a list of lists; \mbox{\texttt{\slshape outputs}}[\mbox{\texttt{\slshape s}}][\mbox{\texttt{\slshape x}}] is a output letter of the machine when it receives input \mbox{\texttt{\slshape x}} in state \mbox{\texttt{\slshape s}}. 

 \mbox{\texttt{\slshape init}} is a word in \mbox{\texttt{\slshape free}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> f := FreeGroup(2);
  <free group on the generators [ f1, f2 ]>
  gap> e := FRElementNC(FREFamily([1,2]),f,[[One(f),f.1],[One(f),f.2^-1]],
                        [[2,1],[2,1]],f.1);
  <2|f1>
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{FRElement ([list,]list,list,list)}}
\logpage{[ 4, 1, 2 ]}\nobreak
\hyperdef{L}{X7CF5EDEB874BF9E3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRElement({\slshape [names, ]transitions, outputs, init})\index{FRElement@\texttt{FRElement}![list,]list,list,list}
\label{FRElement:[list,]list,list,list}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRElement({\slshape free, transitions, outputs, init})\index{FRElement@\texttt{FRElement}!semigroup,list,list,list}
\label{FRElement:semigroup,list,list,list}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new FR element.



 This function constructs a new FR element. It has stateset a free
group/semigroup/monoid, structure described by \mbox{\texttt{\slshape transitions}} and \mbox{\texttt{\slshape outputs}}, and initial state \mbox{\texttt{\slshape init}}. If the stateset is not passed as argument \mbox{\texttt{\slshape free}}, then it is determined by \mbox{\texttt{\slshape transitions}} and \mbox{\texttt{\slshape outputs}}; it is a free group if all states are invertible, and a free monoid
otherwise. In that case, \mbox{\texttt{\slshape names}} is an optional list; at position \mbox{\texttt{\slshape s}} it contains a string naming generator \mbox{\texttt{\slshape s}}. 

 \mbox{\texttt{\slshape transitions}} is a list of lists; \texttt{transitions[s][x]} is either an associative word, or a list of integers or FR elements describing
the state reached by the machine when started in state \mbox{\texttt{\slshape s}} and fed input \mbox{\texttt{\slshape x}}. Positive integers indicate a generator, negative integers its inverse, the
empty list in the identity state, and lists of length greater than one
indicate a product of states. If an entry is an FR element, then its machine
is incorporated into the newly constructed element. 

 \mbox{\texttt{\slshape outputs}} is a list; at position \mbox{\texttt{\slshape s}} it contains a permutation, a transformation, or a list of images, describing
the activity of state \mbox{\texttt{\slshape s}}. 

 \mbox{\texttt{\slshape init}} is either an associative word, an integer, or a list of integers describing
the inital state of the machine. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);
  <2|tau>
  gap> tau1 := FRElement(["tau1"],[[[],[2]],[[],[2]]],[(),(1,2)],1);
  <2|tau1>
  gap> (tau/tau1)^2;
  <2|tau1*tau2^-1*tau1*tau2^-1>
  gap> IsOne(last);
  true
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> f := FreeGroup("tau","tau1");
  <free group on the generators [ tau, tau1 ]>
  gap> tau := FRElement(f,[[One(f),f.1],[One(f),f.1]],[(1,2),()],f.1);
  <2|tau>
  gap> tau1 := FRElement(f,[[One(f),f.1],[One(f),f.1]],[(1,2),()],f.2);
  <2|tau1>
  gap> (tau/tau1)^2;
  <2|tau1*tau2^-1*tau1*tau2^-1>
  gap> IsOne(last);
  true
  gap> tauX := FRElement(f,[[One(f),f.1],[One(f),f.1]],[(1,2),()],1);;
  gap> tauY := FRElement(f,[[One(f),f.1],[One(f),f.1]],[(1,2),()],f.1);;
  gap> Size(Set([tau,tauX,tauY]));
  1
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{FRElement (machine/element,list)}}
\logpage{[ 4, 1, 3 ]}\nobreak
\hyperdef{L}{X86181654827919EE}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRElement({\slshape m, q})\index{FRElement@\texttt{FRElement}!machine/element,list}
\label{FRElement:machine/element,list}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new FR element.



 This function constructs a new FR element. If \mbox{\texttt{\slshape m}} is an FR machine, it creates the element $(m,q)$ whose \texttt{FRMachine} is \mbox{\texttt{\slshape m}} and whose initial state is \mbox{\texttt{\slshape q}}. 

If \mbox{\texttt{\slshape m}} is an FR element, this command creates an FR element with the same FR machine
as \mbox{\texttt{\slshape m}}, and with initial state \mbox{\texttt{\slshape q}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ a, b ] )>
  gap> a := FRElement(m,1); b := FRElement(m,2);
  <2|a>
  <2|b>
  gap> Comm(b,b^a);
  <2|b^-1*a^-1*b^-1*a*b*a^-1*b*a>
  gap> IsOne(last);
  true
  gap> last2=FRElement(m,[-2,-1,-2,1,2,-1,2,1]);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ComposeElement (elementcoll,perm)}}
\logpage{[ 4, 1, 4 ]}\nobreak
\hyperdef{L}{X80D518E2804ABF70}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ComposeElement({\slshape l, p})\index{ComposeElement@\texttt{ComposeElement}!elementcoll,perm}
\label{ComposeElement:elementcoll,perm}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new FR element.



 This function constructs a new FR element. \mbox{\texttt{\slshape l}} is a list of FR elements, and \mbox{\texttt{\slshape p}} is a permutation, transformation or list. In that last case, the resulting
element \texttt{g} satisfies \texttt{DecompositionOfFRElement(g)=[l,p]}. 

 If all arguments are Mealy element, the result is a Mealy element. Otherwise,
it is a MonoidFRElement. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);;
  gap> a := FRElement(m,1); b := FRElement(m,2);
  <2|a>
  <2|b>
  gap> ComposeElement([b^0,b],(1,2));
  <2|f1>
  gap> last=a;
  true
  gap> DecompositionOfFRElement(last2);
  [ [ <2|identity ...>, <2|f5> ], [ 2, 1 ] ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{VertexElement}}
\logpage{[ 4, 1, 5 ]}\nobreak
\hyperdef{L}{X7CE388057DAB4802}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{VertexElement({\slshape v, e})\index{VertexElement@\texttt{VertexElement}}
\label{VertexElement}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new FR element.



 This function constructs a new FR element. \mbox{\texttt{\slshape v}} is either an integer or a list of integers, and represents a vertex. \mbox{\texttt{\slshape e}} is an FR element. The resulting element acts on the subtree below vertex \mbox{\texttt{\slshape v}} as \mbox{\texttt{\slshape e}} acts on the whole tree, and fixes all other subtrees. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> e := FRElement([[[],[]]],[(1,2)],[1]);
  <2|f1>
  gap> f := VertexElement(1,e);;
  gap> g := VertexElement(2,f);;
  gap> g = VertexElement([2,1],e);
  true
  gap> 1^e;
  2
  gap> [1,1]^f;
  [ 1, 2 ]
  gap> [2,1,1]^g;
  [ 2, 1, 2 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{DiagonalElement}}
\logpage{[ 4, 1, 6 ]}\nobreak
\hyperdef{L}{X848EB430831097E6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DiagonalElement({\slshape n, e})\index{DiagonalElement@\texttt{DiagonalElement}}
\label{DiagonalElement}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new FR element.



 This function constructs a new FR element. \mbox{\texttt{\slshape n}} is either an integer or a list of integers, representing a sequence of
operations to be performed on \mbox{\texttt{\slshape e}} starting from the last. 

 \texttt{DiagonalElement(n,e)} is an element with trivial output, and with $e^{(-1)^i \mathop{binomial}(n,i)}$ in coordinate $i+1$ of the alphabet, assumed to be of the form \texttt{[1..d]}. 

 In particular, \texttt{DiagonalElement(0,e)} is the same as \texttt{VertexElement(1,e)}; \texttt{DiagonalElement(1,e)} is the commutator of \texttt{VertexElement(1,e)} with any cycle mapping 1 to 2; and \texttt{DiagonalElement(-1,e)} has a transition to \mbox{\texttt{\slshape e}} at all inputs. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> e := FRElement([[[],[],[1]]],[(1,2,3)],[1]);
  <3|f1>
  gap> Display(e);
      |     1        2      3
  ----+--------+--------+------+
   f1 | <id>,2   <id>,3   f1,1
  ----+--------+--------+------+
  Initial state: f1
  gap> Display(DiagonalElement(0,e));
      |     1        2        3
  ----+--------+--------+--------+
   f1 |   f2,1   <id>,2   <id>,3
   f2 | <id>,2   <id>,3     f2,1
  ----+--------+--------+--------+
  Initial state: f1
  gap> Display(DiagonalElement(1,e));
      |     1         2        3
  ----+--------+---------+--------+
   f1 |   f2,1   f2^-1,2   <id>,3
   f2 | <id>,2    <id>,3     f2,1
  ----+--------+---------+--------+
  Initial state: f1
  gap> Display(DiagonalElement(2,e));
      |     1         2      3
  ----+--------+---------+------+
   f1 |   f2,1   f2^-2,2   f2,3
   f2 | <id>,2    <id>,3   f2,1
  ----+--------+---------+------+
  Initial state: f1
  gap> Display(DiagonalElement(-1,e));
      |     1        2      3
  ----+--------+--------+------+
   f1 |   f2,1     f2,2   f2,3
   f2 | <id>,2   <id>,3   f2,1
  ----+--------+--------+------+
  Initial state: f1
  gap> DiagonalElement(-1,e)=DiagonalElement(2,e);
  true
  gap> Display(DiagonalElement([0,-1],e));
   G  |     1        2        3
  ----+--------+--------+--------+
   f1 |   f2,1   <id>,2   <id>,3
   f2 |   f3,1     f3,2     f3,3
   f3 | <id>,2   <id>,3     f3,1
  ----+--------+--------+--------+
  Initial state: f1
  gap> Display(DiagonalElement([-1,0],e));
   G  |     1        2        3
  ----+--------+--------+--------+
   f1 |   f2,1     f2,2     f2,3
   f2 |   f3,1   <id>,2   <id>,3
   f3 | <id>,2   <id>,3     f3,1
  ----+--------+--------+--------+
  Initial state: f1
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AsGroupFRElement}}
\logpage{[ 4, 1, 7 ]}\nobreak
\hyperdef{L}{X7EB5DE3978840CDF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsGroupFRElement({\slshape e})\index{AsGroupFRElement@\texttt{AsGroupFRElement}}
\label{AsGroupFRElement}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsMonoidFRElement({\slshape e})\index{AsMonoidFRElement@\texttt{AsMonoidFRElement}}
\label{AsMonoidFRElement}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsSemigroupFRElement({\slshape e})\index{AsSemigroupFRElement@\texttt{AsSemigroupFRElement}}
\label{AsSemigroupFRElement}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
An FR element isomorphic to \mbox{\texttt{\slshape m}}, with a free group/monoid/semigroup as stateset.



 This function constructs, from the FR element \mbox{\texttt{\slshape e}}, an isomorphic FR element \texttt{f} with a free group/monoid/semigroup as stateset. \mbox{\texttt{\slshape e}} may be a Mealy, group, monoid or semigroup FR element. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> e := AsGroupFRElement(FRElement(GuptaSidkiMachines(3),4));
  <3|f1>
  gap> Display(e);
   G  |     1         2        3
  ----+--------+---------+--------+
   f1 |   f2,1   f2^-1,2     f1,3
   f2 | <id>,2    <id>,3   <id>,1
  ----+--------+---------+--------+
  Initial state: f1
  gap> e=FRElement(GuptaSidkiMachines(3),4);
  #I  \=: converting second argument to FR element
  true
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> e := AsMonoidFRElement(FRElement(GuptaSidkiMachines(3),4));
  <3|m1>
  gap> Display(e);
   M  |     1        2        3
  ----+--------+--------+--------+
   m1 |   m2,1     m3,2     m1,3
   m2 | <id>,2   <id>,3   <id>,1
   m3 | <id>,3   <id>,1   <id>,2
  ----+--------+--------+--------+
  Initial state: m1
  gap> e=FRElement(GuptaSidkiMachines(3),4);
  #I  \=: converting second argument to FR element
  true
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> e := AsSemigroupFRElement(FRElement(GuptaSidkiMachines(3),4));
  <3|s1>
  gap> Display(e);
   S  |   1      2      3
  ----+------+------+------+
   s1 | s2,1   s3,2   s1,3
   s2 | s4,2   s4,3   s4,1
   s3 | s4,3   s4,1   s4,2
   s4 | s4,1   s4,2   s4,3
  ----+------+------+------+
  Initial state: s1
  gap> e=FRElement(GuptaSidkiMachines(3),4);
  #I  \=: converting second argument to FR element
  true
\end{Verbatim}
 }

 }

 
\section{\textcolor{Chapter }{Operations and Attributes for \texttt{FRElement}s}}\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X812C932C7E2F2885}{}
{
 

\subsection{\textcolor{Chapter }{Output (FR element)}}
\logpage{[ 4, 2, 1 ]}\nobreak
\hyperdef{L}{X78F819CF7DDBF310}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Output({\slshape e})\index{Output@\texttt{Output}!FR element}
\label{Output:FR element}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A transformation of \mbox{\texttt{\slshape e}}'s alphabet.



 This function returns the transformation of \mbox{\texttt{\slshape e}}'s alphabet, i.e. the action on strings of length 1 over the alphabet. This
transformation is a permutation if \mbox{\texttt{\slshape machine}} is a group machine, and a transformation otherwise. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;
  gap> Output(tau);
  (1,2)
  zap := FRElement(["zap"],[[[],[1]]],[[1,1]],[1]);;
  gap> Output(zap);
  <1,1>
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Activity}}
\logpage{[ 4, 2, 2 ]}\nobreak
\hyperdef{L}{X8732D01C82999F32}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Activity({\slshape e[, l]})\index{Activity@\texttt{Activity}}
\label{Activity}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ActivityInt({\slshape e[, l]})\index{ActivityInt@\texttt{ActivityInt}}
\label{ActivityInt}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ActivityTransformation({\slshape e[, l]})\index{ActivityTransformation@\texttt{ActivityTransformation}}
\label{ActivityTransformation}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ActivityPerm({\slshape e[, l]})\index{ActivityPerm@\texttt{ActivityPerm}}
\label{ActivityPerm}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The transformation induced by \mbox{\texttt{\slshape e}} on the \mbox{\texttt{\slshape l}}th level of the tree.



 This function returns the transformation induced by \mbox{\texttt{\slshape e}} on the \mbox{\texttt{\slshape l}}th level of the tree, i.e. on the strings of length \mbox{\texttt{\slshape l}} over \mbox{\texttt{\slshape e}}'s alphabet. 

 This set of strings is identified with the set $L=\{1,\dots,d^l\}$ of integers, where the alphabet of \mbox{\texttt{\slshape e}} has $d$ letters. Changes of the first letter of a string induce changes of a multiple
of $d^{l-1}$ on the position in $L$, while changes of the last letter of a string induce changes of $1$ on the position in $L$. 

 This command returns a permutation if \mbox{\texttt{\slshape e}} is invertible; and a transformations otherwise. In the second form, it returns
the unique integer \texttt{i} such that the transformation \mbox{\texttt{\slshape e}} acts on \texttt{[1..Length(AlphabetOfFRObject(e))\texttt{\symbol{94}}n]} as adding \texttt{i} in base \texttt{Length(alphabet(e))}, or \texttt{fail} if no such \texttt{i} exists. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;
  gap> Output(tau); PermList(last)=Activity(tau);
  [ 2, 1 ]
  true
  gap> Activity(tau,2); ActivityInt(tau,2);
  (1,3,2,4)
  1
  gap> Activity(tau,3); ActivityInt(tau,3);
  (1,5,3,7,2,6,4,8)
  1
  zap := FRElement(["zap"],[[[1],[]]],[[1,1]],[1]);
  <2|zap>
  gap> Output(zap);
  [ 1, 1 ]
  gap> Activity(zap,3);
  <1,1,1,2,1,2,3,4>
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Transition (FR element,input)}}
\logpage{[ 4, 2, 3 ]}\nobreak
\hyperdef{L}{X7CE58B2D837B2845}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Transition({\slshape e, i})\index{Transition@\texttt{Transition}!FR element,input}
\label{Transition:FR element,input}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
An element of \mbox{\texttt{\slshape machine}}'s stateset.



 This function returns the state reached by \mbox{\texttt{\slshape e}} when fed input \mbox{\texttt{\slshape i}}. This input may be an alphabet letter or a sequence of alphabet letters. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;
  gap> Transition(tau,2);
  tau
  gap> Transition(tau,[2,2]);
  tau
  gap> Transition(tau^2,[2,2]);
  tau
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Portrait}}
\logpage{[ 4, 2, 4 ]}\nobreak
\hyperdef{L}{X84A193C67CDBDA35}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Portrait({\slshape e, l})\index{Portrait@\texttt{Portrait}}
\label{Portrait}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PortraitInt({\slshape e, l})\index{PortraitInt@\texttt{PortraitInt}}
\label{PortraitInt}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A nested list describing the action of \mbox{\texttt{\slshape e}}.



 This function returns a sequence of $l+1$ lists; the $i$th list in the sequence is an \mbox{\texttt{\slshape i-1}}-fold nested list. The entry at position $(x_1,\dots,x_i)$ is the transformation of the alphabet induced by \mbox{\texttt{\slshape e}} under vertex $x_1\dots x_i$. 

 The difference between \texttt{Portrait} and \texttt{Portrait} is that the latter describes transformations are described as powers of the
cycle $x\mapsto x+1$, as for the function \texttt{ActivityInt} (\ref{ActivityInt}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;
  gap> Portrait(tau,0);
  [ (1,2) ]
  gap> Portrait(tau,3);
  [ (1,2), [ (), (1,2) ], [ [ (), () ], [ (), (1,2) ] ],
    [ [ [ (), () ], [ (), () ] ], [ [ (), () ], [ (), (1,2) ] ] ] ]
  gap> PortraitInt(tau,0);
  [ ZmodpZObj(1,2) ]
  gap> PortraitInt(tau,3);
  [ ZmodpZObj(1,2), [ZmodpZObj(0,2), ZmodpZObj(1,2)],
    [ [ZmodpZObj(0,2), ZmodpZObj(0,2)], [ZmodpZObj(0,2), ZmodpZObj(1,2)] ],
    [ [ [ZmodpZObj(0,2), ZmodpZObj(0,2)], [ZmodpZObj(0,2), ZmodpZObj(0,2)] ],
      [ [ZmodpZObj(0,2), ZmodpZObj(0,2)], [ZmodpZObj(0,2), ZmodpZObj(1,2)] ] ] ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{DecompositionOfFRElement}}
\logpage{[ 4, 2, 5 ]}\nobreak
\hyperdef{L}{X850EB66E7804BA3B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DecompositionOfFRElement({\slshape e[, n]})\index{DecompositionOfFRElement@\texttt{DecompositionOfFRElement}}
\label{DecompositionOfFRElement}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A list describing the action and transitions of \mbox{\texttt{\slshape e}}.



 This function returns a list. The second coordinate is the action of \mbox{\texttt{\slshape e}} on its alphabet, see \texttt{Output} (\ref{Output:FR element}). The first coordinate is a list, containing in position $i$ the FR element inducing the action of \mbox{\texttt{\slshape e}} on strings starting with $i$. 

 If a second argument \mbox{\texttt{\slshape n}} is supplied, the decomposition is iterated \mbox{\texttt{\slshape n}} times. 

 This FR element has same underlying machine as \mbox{\texttt{\slshape e}}, and initial state given by \texttt{Transition} (\ref{Transition:FR element,input}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;
  gap> DecompositionOfFRElement(tau);
  [ [ <2|identity ...>, <2|tau> ], [ 2, 1 ] ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{StateSet (FR element)}}
\logpage{[ 4, 2, 6 ]}\nobreak
\hyperdef{L}{X85441F1683E9D820}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StateSet({\slshape e})\index{StateSet@\texttt{StateSet}!FR element}
\label{StateSet:FR element}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The set of states associated with \mbox{\texttt{\slshape e}}.



 This function returns the stateset of \mbox{\texttt{\slshape e}}. If \mbox{\texttt{\slshape e}} is of Mealy type, this is the list of all states reached by \mbox{\texttt{\slshape e}}. 

 If \mbox{\texttt{\slshape e}} is of group/semigroup/monoid type, then this is the stateset of the underlying
FR machine, and not the minimal set of states of \mbox{\texttt{\slshape e}}, which is computed with \texttt{States} (\ref{States}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;
  gap> StateSet(tau);
  <free group on the generators [ tau ]>
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{State}}
\logpage{[ 4, 2, 7 ]}\nobreak
\hyperdef{L}{X819E3E3080297347}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{State({\slshape e, v})\index{State@\texttt{State}}
\label{State}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
An FR element describing the action of \mbox{\texttt{\slshape e}} at vertex \mbox{\texttt{\slshape v}}.



 This function returns the FR element with same underlying machine as \mbox{\texttt{\slshape e}}, acting on the binary tree as \mbox{\texttt{\slshape e}} acts on the subtree below \mbox{\texttt{\slshape v}}. 

 \mbox{\texttt{\slshape v}} is either an integer or a list. This function returns an FR element, but
otherwise is essentially a call to \texttt{Transition} (\ref{Transition:FR element,input}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;
  gap> State(tau,2);
  <2|tau>
  gap> State(tau,[2,2]);
  <2|tau>
  gap> State(tau^2,[2,2]);
  <2|tau>
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{States}}
\logpage{[ 4, 2, 8 ]}\nobreak
\hyperdef{L}{X7B0C97BC7C3BA20D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{States({\slshape e})\index{States@\texttt{States}}
\label{States}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A list of FR elements describing the action of \mbox{\texttt{\slshape e}} on all subtrees.



 This function calls repeatedly \texttt{State} (\ref{State}) to compute all the states of \mbox{\texttt{\slshape e}}; it returns the smallest list of \texttt{FRElement}s that is closed under the function \texttt{State} (\ref{State}). 

 \mbox{\texttt{\slshape e}} may be either an FR element, or a list of FR elements. In the latter case, it
amounts to computing the list of all states of all elements of the list \mbox{\texttt{\slshape e}}. 

 The ordering of the list is as follows. First come \mbox{\texttt{\slshape e}}, or all elements of \mbox{\texttt{\slshape e}}. Then come the states reached by \mbox{\texttt{\slshape e}} in one transition, ordered by the alphabet letter leading to them; then come
those reached in two transitions, ordered lexicographically by the transition;
etc. 

 Note that this function is not guaranteed to terminate. There is currently no
mechanism that detects whether an FR element is finite state, so in fact this
function terminates if and only if \mbox{\texttt{\slshape e}} is finite-state. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);;
  gap> a := FRElement(m,1);; b := FRElement(m,2);;
  gap> States(a);
  [ <2|a>, <2|identity ...>, <2|b> ]
  gap> States(b);
  [ <2|b>, <2|identity ...>, <2|a> ]
  gap> States(a^2);
  [ <2|a^2>, <2|b>, <2|identity ...>, <2|a> ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{FixedStates}}
\logpage{[ 4, 2, 9 ]}\nobreak
\hyperdef{L}{X804B2E0F7E37F5B8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FixedStates({\slshape e})\index{FixedStates@\texttt{FixedStates}}
\label{FixedStates}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A list of FR elements describing the action of \mbox{\texttt{\slshape e}} at fixed vertices.



 This function calls repeatedly \texttt{State} (\ref{State}) to compute all the states of \mbox{\texttt{\slshape e}} at non-trivial fixed vertices. 

 \mbox{\texttt{\slshape e}} may be either an FR element, or a list of FR elements. In the latter case, it
amounts to computing the list of all states of all elements of the list \mbox{\texttt{\slshape e}}. 

 The ordering of the list is as follows. First come \mbox{\texttt{\slshape e}}, or all elements of \mbox{\texttt{\slshape e}}. Then come the states reached by \mbox{\texttt{\slshape e}} in one transition, ordered by the alphabet letter leading to them; then come
those reached in two transitions, ordered lexicographically by the transition;
etc. 

 Note that this function is not guaranteed to terminate, if \mbox{\texttt{\slshape e}} is not finite-state. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);;
  gap> a := FRElement(m,1);; b := FRElement(m,2);;
  gap> FixedStates(a);
  [ ]
  gap> FixedStates(b);
  [ <2|identity ...>, <2|a> ]
  gap> FixedStates(a^2);
  [ <2|b>, <2|identity ...>, <2|a> ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{LimitStates}}
\logpage{[ 4, 2, 10 ]}\nobreak
\hyperdef{L}{X8303B36C83371FB3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LimitStates({\slshape e})\index{LimitStates@\texttt{LimitStates}}
\label{LimitStates}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A set of FR element describing the recurring actions of \mbox{\texttt{\slshape e}} on all subtrees.



 This function computes the \texttt{States} (\ref{States}) $S$ of \mbox{\texttt{\slshape e}}, and then repeatedly removes elements that are not \emph{recurrent}, i.e. that do not appear as states of elements of $S$ on subtrees distinct from the entire tree; and then converts the result to a
set. 

 As for \texttt{States} (\ref{States}), \mbox{\texttt{\slshape e}} may be either an FR element, or a list of FR elements. 

 Note that this function is not guaranteed to terminate. It currently
terminates if and only if \texttt{States} (\ref{States}) terminates. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);;
  gap> a := FRElement(m,1);; b := FRElement(m,2);;
  gap> LimitStates(a);
  [ <2|a>, <2|identity ...>, <2|b> ]
  gap> LimitStates(a^2);
  [ <2|b>, <2|identity ...>, <2|a> ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsFiniteStateFRElement}}
\logpage{[ 4, 2, 11 ]}\nobreak
\hyperdef{L}{X7C4076707CBBE945}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFiniteStateFRElement({\slshape e})\index{IsFiniteStateFRElement@\texttt{IsFiniteStateFRElement}}
\label{IsFiniteStateFRElement}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFiniteStateFRMachine({\slshape e})\index{IsFiniteStateFRMachine@\texttt{IsFiniteStateFRMachine}}
\label{IsFiniteStateFRMachine}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape e}} is a finite-state element.



 This function tests whether \mbox{\texttt{\slshape e}} is a finite-state element. 

 When applied to a Mealy element, it returns \texttt{true}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := GuptaSidkiMachines(3);; Display(m);
     |  1     2     3
  ---+-----+-----+-----+
   a | a,1   a,2   a,3
   b | a,2   a,3   a,1
   c | a,3   a,1   a,2
   d | b,1   c,2   d,3
  ---+-----+-----+-----+
  gap> Filtered(StateSet(m),i->IsFiniteStateFRElement(FRElement(m,i)));
  [ 1, 2, 3, 4 ]
  gap> IsFiniteStateFRMachine(m);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{InitialState}}
\logpage{[ 4, 2, 12 ]}\nobreak
\hyperdef{L}{X79E65E818690B4EB}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{InitialState({\slshape e})\index{InitialState@\texttt{InitialState}}
\label{InitialState}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The initial state of an FR element.



 This function returns the initial state of an FR element. It is an element of
the stateset of the underlying FR machine of \mbox{\texttt{\slshape e}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := FRElement(["tau","mu"],[[[],[1]],[[],[-2]]],[(1,2),(1,2)],[1,2]);
  <2|tau*mu>
  gap> InitialState(n);
  tau*mu
  gap> last in StateSet(n);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{\texttt{\symbol{92}}\texttt{\symbol{94}} (POW)}}
\logpage{[ 4, 2, 13 ]}\nobreak
\hyperdef{L}{X823B6E3D819432D6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{\texttt{\symbol{92}}\texttt{\symbol{94}}({\slshape e, v})\index{^@\texttt{\texttt{\symbol{92}}\texttt{\symbol{94}}}!POW}
\label{^:POW}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
The image of a vertex \mbox{\texttt{\slshape v}} under \mbox{\texttt{\slshape e}}.



 This function accepts an FR element and a vertex \mbox{\texttt{\slshape v}}, which is either an integer or a list. It returns the image of \mbox{\texttt{\slshape v}} under the transformation \mbox{\texttt{\slshape e}}, in the same format (integer/list) as \mbox{\texttt{\slshape v}}. 

 The list \mbox{\texttt{\slshape v}} can be a periodic list (see \texttt{PeriodicList} (\ref{PeriodicList})). In that case, the result in again a periodic list. The computation will
succeed only if the states along the period are again periodic. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;
  gap> 1^tau;
  2
  gap> [1,1]^tau;
  [ 2, 1 ]
  gap> [2,2,2]^tau;
  [ 1, 1, 1 ]
  gap List([0..5],i->PeriodicList([],[2])^(tau^i));
  [ [/ 2 ], [/ 1 ], [ 2, / 1 ], [ 1, 2, / 1 ], [ 2, 2, / 1 ],
    [ 1, 1, 2, / 1 ] ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{\texttt{\symbol{92}}* (PROD)}}
\logpage{[ 4, 2, 14 ]}\nobreak
\hyperdef{L}{X7C3CF6AF86336EDC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{\texttt{\symbol{92}}*({\slshape m, n})\index{*@\texttt{\texttt{\symbol{92}}*}!PROD}
\label{*:PROD}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
The product of the two FR elements \mbox{\texttt{\slshape m}} and \mbox{\texttt{\slshape n}}.



 This function returns a new FR element, which is the product of the FR
elements \mbox{\texttt{\slshape m}} and \mbox{\texttt{\slshape n}}. 

 In case \mbox{\texttt{\slshape m}} and \mbox{\texttt{\slshape n}} have the same underlying machine, this is the machine of the result. In case
the machine of \mbox{\texttt{\slshape n}} embeds in the machine of \mbox{\texttt{\slshape m}} (see \texttt{SubFRMachine} (\ref{SubFRMachine})), the machine of the product is the machine of \mbox{\texttt{\slshape m}}. In case the machine of \mbox{\texttt{\slshape m}} embeds in the machine of \mbox{\texttt{\slshape n}}, the machine of the product is the machine of \mbox{\texttt{\slshape n}}. Otherwise the machine of the product is the product of the machines of \mbox{\texttt{\slshape m}} and \mbox{\texttt{\slshape n}} (See \texttt{\texttt{\symbol{92}}*} (\ref{*})). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> tau := FRElement(["tau"],[[[],[1]]],[(1,2)],[1]);;
  gap> tau*tau; tau^2;
  <2|tau^2>
  <2|tau^2>
  gap> [2,2,2]^(tau^2);
  [ 2, 1, 1 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{\texttt{\symbol{92}}[\texttt{\symbol{92}}] (ELMLIST)}}
\logpage{[ 4, 2, 15 ]}\nobreak
\hyperdef{L}{X78C19ACA78F9F067}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{\texttt{\symbol{92}}[\texttt{\symbol{92}}]({\slshape m, i})\index{[]@\texttt{\texttt{\symbol{92}}[\texttt{\symbol{92}}]}!ELMLIST}
\label{[]:ELMLIST}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{\texttt{\symbol{92}}\texttt{\symbol{123}}\texttt{\symbol{92}}\texttt{\symbol{125}}({\slshape m, l})\index{{}@\texttt{\texttt{\symbol{92}}\texttt{\symbol{123}}\texttt{\symbol{92}}\texttt{\symbol{125}}}!ELMSLIST}
\label{{}:ELMSLIST}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
A [list of] FR element[s] with initial state \mbox{\texttt{\slshape i}}.



 These are respectively synonyms for \texttt{FRElement(m,i)} and \texttt{List(l,s-{\textgreater}FRElement(m,s))}. The argument \mbox{\texttt{\slshape m}} must be an FR machine, \mbox{\texttt{\slshape i}} must be a positive integer, and \mbox{\texttt{\slshape l}} must be a list. }

 }

 }

 
\chapter{\textcolor{Chapter }{Mealy machines and elements}}\label{mealy}
\logpage{[ 5, 0, 0 ]}
\hyperdef{L}{X7C77EBC17DEF4CF6}{}
{
 \emph{Mealy machines} form a special class of FR machines. They have as stateset a finite set, as
opposed to a free group/monoid/semigroup. All commands available for FR
machines are also available for Mealy machines, but the latter have added
functionality. 

 There are currently two types of Mealy machines; one has as stateset an
interval of integers of the form \texttt{[1..m]} and as alphabet a set of integers; the other has an arbitrary domain as
stateset and alphabet. Almost no functionality is implemented for the latter
type, but there is a function converting it to the former type (see \texttt{AsMealyMachine} (\ref{AsMealyMachine:FR machine})). 

 The internal representation of a Mealy machine of the first kind is quite
different from that of FR machines. The alphabet is assumed to be an interval \texttt{[1..n]}, and the stateset is assumed to be an interval \texttt{[1..m]}. The transitions are stored as a $m \times n$ matrix, and the outputs are stored in a list of length $m$, consisting of permutations or transformations. 

 Mealy machines have additional properties, in particular they can act on
periodic sequences (see \texttt{PeriodicList} (\ref{PeriodicList})). For example, the periodic sequence \texttt{PeriodicList([1],[1,2])} describes the infinite ray \texttt{[1,1,2,1,2,..]} in the tree. In principle, Mealy machines could act on sequences accepted by
an automaton, although this is not yet implemented. 

 Mealy elements are Mealy machines with an initial state. For efficiency
reasons, Mealy elements are always minimized, and their states are ordered in
a canonical top-down, left-to-right order of traversal of the tree. In
particular, their initial state is always 1. In this implementation,
multiplication of Mealy elements is slower than multiplication of group FR
elements, while comparison of Mealy elements is faster than comparison of
group FR elements. In practise, it is better to work with Mealy elements as
often as possible. 

 Products of Mealy machines behave in the same way as products of general FR
machines, see \ref{frmachine-products}. The only difference is that now the sum and products of statesets are
distinct; the sum of statesets being their disjoint union, and their product
being their cartesian product. 
\section{\textcolor{Chapter }{Creators for \texttt{MealyMachine}s and \texttt{MealyElement}s}}\logpage{[ 5, 1, 0 ]}
\hyperdef{L}{X846B89F686B50AE1}{}
{
 

\subsection{\textcolor{Chapter }{MealyMachine ([list,]listlist,list)}}
\logpage{[ 5, 1, 1 ]}\nobreak
\hyperdef{L}{X7EF3E00080624B70}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MealyMachine({\slshape [alphabet, ]transitions, output})\index{MealyMachine@\texttt{MealyMachine}![list,]listlist,list}
\label{MealyMachine:[list,]listlist,list}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MealyElement({\slshape [alphabet, ]transitions, output, init})\index{MealyElement@\texttt{MealyElement}![list,]listlist,list,int}
\label{MealyElement:[list,]listlist,list,int}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new Mealy machine/element.



 This function constructs a new Mealy machine or element, of integer type. 

 \mbox{\texttt{\slshape transitions}} is a list of lists; \texttt{transitions[s][x]} is an integer, which is the state reached by the machine when started in state \mbox{\texttt{\slshape s}} and fed input \mbox{\texttt{\slshape x}}. 

 \mbox{\texttt{\slshape output}} is a list; at position \mbox{\texttt{\slshape s}} it contains a permutation, a transformation describing the activity of state \mbox{\texttt{\slshape s}}, or a list describing the images of the transformation. 

 \mbox{\texttt{\slshape alphabet}} is an optional domain given as first argument; When present, it is assumed to
be a finite domain, mapped bijectively to \texttt{[1..n]} by its enumerator. The indices "\texttt{[s]}" above are then understood with respect to this enumeration. 

 \mbox{\texttt{\slshape init}} is an integer describing the initial state the newly created Mealy element
should be in. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> b := MealyMachine([[3,2],[3,1],[3,3]],[(1,2),(),()]);
  <Mealy machine on alphabet [ 1, 2 ] with 3 states>
  gap> Display(b);
     |  1     2
  ---+-----+-----+
   a | c,2   b,1
   b | c,1   a,2
   c | c,1   c,2
  ---+-----+-----+
  gap> n := MealyMachine(Domain([11,12]),[[3,2],[3,1],[3,3]],[(1,2),(),()]);
  <Mealy machine on alphabet [ 11, 12 ] with states [ 1 .. 3 ]>
  gap> Display(n);
     |  11     12
  ---+------+------+
   a | c,12   b,11
   b | c,11   a,12
   c | c,11   c,12
  ---+------+------+
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> tau := MealyElement([[2,1],[2,2]],[(1,2),()],1);
  <Mealy machine on alphabet [ 1, 2 ] with 2 states, initial state 1>
  gap> Display(tau);
     |  1     2
  ---+-----+-----+
   a | b,2   a,1
   b | b,1   b,2
  ---+-----+-----+
  Initial state:  a
  gap> [1,1]^tau; [[1]]^tau; [[2]]^tau;
  [ 2, 1 ]
  [ 2, [ 1 ] ]
  [ [ 1 ] ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{MealyMachine (domain,domain,function,function)}}
\logpage{[ 5, 1, 2 ]}\nobreak
\hyperdef{L}{X875B8FED7FD20FA1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MealyMachine({\slshape stateset, alphabet, transitions, output})\index{MealyMachine@\texttt{MealyMachine}!domain,domain,function,function}
\label{MealyMachine:domain,domain,function,function}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MealyElement({\slshape stateset, alphabet, transitions, output, init})\index{MealyElement@\texttt{MealyElement}!domain,domain,function,function,obj}
\label{MealyElement:domain,domain,function,function,obj}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new Mealy machine/element.



 This function constructs a new Mealy machine or element, of domain type. 

 \mbox{\texttt{\slshape stateset}} and \mbox{\texttt{\slshape alphabet}} are domains; they are not necessarily finite. 

 \mbox{\texttt{\slshape transitions}} is a function; it takes as arguments a state and an alphabet letter, and
returns a state. 

 \mbox{\texttt{\slshape output}} is either a function, accepting as arguments a state and a letter, and
returning a letter. 

 \mbox{\texttt{\slshape init}} is an element of \mbox{\texttt{\slshape stateset}} describing the initial state the newly created Mealy element should be in. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> g := Group((1,2));; n := MealyMachine(g,g,\*,\*);
  <Mealy machine on alphabet [ (), (1,2) ] with states Group( [ (1,2) ] )>
  gap> [(1,2),()]^FRElement(n,());
  [ (1,2), (1,2) ]
  gap> a := MealyElement(g,g,\*,\*,());
  <Mealy machine on alphabet [ (), (1,2) ] with states Group(
  [ (1,2) ] ), initial state ()>
  gap> [(1,2),()]^a;
  [ (1,2), (1,2) ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{MealyMachineNC (family,listlist,list)}}
\logpage{[ 5, 1, 3 ]}\nobreak
\hyperdef{L}{X8578657C7F4B6254}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MealyMachineNC({\slshape fam, transitions, output})\index{MealyMachineNC@\texttt{MealyMachineNC}!family,listlist,list}
\label{MealyMachineNC:family,listlist,list}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MealyElementNC({\slshape fam, transitions, output, init})\index{MealyElementNC@\texttt{MealyElementNC}!family,listlist,list,int}
\label{MealyElementNC:family,listlist,list,int}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new Mealy machine/element.



 This function constructs a new Mealy machine or element, of integer type. No
tests are performed to check that the arguments contain values within bounds,
or even of the right type (beyond the simple checking performed by \textsf{GAP}'s method selection algorithms). In particular, Mealy elements are always
assumed to be minimized, but these functions leave this task to the user. 

 \mbox{\texttt{\slshape fam}} is the family to which the newly created Mealy machine will belong. 

 \mbox{\texttt{\slshape transitions}} is a list of lists; \texttt{transitions[s][x]} is an integer, which is the state reached by the machine when started in state \mbox{\texttt{\slshape s}} and fed input \mbox{\texttt{\slshape x}}. 

 \mbox{\texttt{\slshape output}} is a list; at position \mbox{\texttt{\slshape s}} it contains a permutation or a transformation describing the activity of state \mbox{\texttt{\slshape s}}. 

 \mbox{\texttt{\slshape init}} is an integer describing the initial state the newly created Mealy element
should be in. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> taum := MealyMachine([[2,1],[2,2]],[(1,2),()]);
  <Mealy machine on alphabet [ 1, 2 ] with 2 states>
  gap> tauminv := MealyMachineNC(FamilyObj(taum),[[1,2],[2,2]],[(1,2),()]);
  <Mealy machine on alphabet [ 1, 2 ] with 2 states>
  gap> tau := MealyElement([[2,1],[2,2]],[(1,2),()],1);
  <Mealy machine on alphabet [ 1, 2 ] with 2 states, initial state 1>
  gap> tauinv := MealyElementNC(FamilyObj(n),[[1,2],[2,2]],[(1,2),()],1);
  <Mealy machine on alphabet [ 1, 2 ] with 2 states, initial state 1>
  gap> tau=FRElement(taum,1); tauinv=FRElement(tauminv,1);
  true
  true
  gap> IsOne(tau*tauinv);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AllMealyMachines}}
\logpage{[ 5, 1, 4 ]}\nobreak
\hyperdef{L}{X83BBE01884D6E315}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AllMealyMachines({\slshape m, n[, filters]})\index{AllMealyMachines@\texttt{AllMealyMachines}}
\label{AllMealyMachines}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
A list of all Mealy machines with specified properties.



 This function constructs all mealy with alphabet \texttt{[1..m]}, stateset \texttt{[1..n]} and specified properties. 

 These properties are specified as additional arguments. They can include \texttt{IsInvertible} (\ref{IsInvertible}), \texttt{IsReversible} (\ref{IsReversible}), \texttt{IsBireversible} (\ref{IsBireversible}), and \texttt{IsMinimized} (\ref{IsMinimized}) to specify that the machines should have that property. 

 A group/monoid/semigroup \texttt{p} may also be passed as argument; this specifies the allowable vertex
transformations of the machines. The property \texttt{IsTransitive} requires that the state-closed group/monoid/semigroup of the machine act
transitively on its alphabet, and \texttt{IsSurjective} requires that its \texttt{VertexTransformationsFRMachine} (\ref{VertexTransformationsFRMachine}) be precisely equal to \texttt{p}. 

 The argument \texttt{EquivalenceClasses} returns one isomorphism class of Mealy machine, under the permutations of the
stateset and alphabet. 

 The following example constructs the two Mealy machines \texttt{AleshinMachine} (\ref{AleshinMachine}) and \texttt{BabyAleshinMachine} (\ref{BabyAleshinMachine}): 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> l := AllMealyMachines(2,3,IsBireversible,IsSurjective,EquivalenceClasses);;
  gap> Length(l);
  20
  gap> Filtered(l,x->VertexTransformationsFRMachine(DualMachine(x))=SymmetricGroup(3)
  >                     and Size(StateSet(Minimized(x)))=3);
  [ <Mealy machine on alphabet [ 1, 2 ] with 3 states>,
    <Mealy machine on alphabet [ 1, 2 ] with 3 states> ]
   gap> Display(last[1]);
     |  1     2
  ---+-----+-----+
   a | a,1   b,2
   b | c,2   c,1
   c | b,1   a,2
  ---+-----+-----+
  gap> Display(last[2]);
     |  1     2
  ---+-----+-----+
   a | a,2   b,1
   b | c,1   c,2
   c | b,2   a,1
  ---+-----+-----+
\end{Verbatim}
 }

 }

 
\section{\textcolor{Chapter }{Operations and Attributes for \texttt{MealyMachine}s and \texttt{MealyElement}s}}\logpage{[ 5, 2, 0 ]}
\hyperdef{L}{X7F673D877B205708}{}
{
 

\subsection{\textcolor{Chapter }{Draw}}
\logpage{[ 5, 2, 1 ]}\nobreak
\hyperdef{L}{X7DF9F3AD86602DFC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Draw({\slshape m[, filename]})\index{Draw@\texttt{Draw}}
\label{Draw}
}\hfill{\scriptsize (operation)}}\\


 This function creates a graph description of the Mealy machine/element \mbox{\texttt{\slshape m}}. If a second argument \mbox{\texttt{\slshape filename}} is present, the graph is saved, in \texttt{dot} format, under that filename; otherwise it is converted to Postscript using the
program \texttt{dot} from the \textsf{graphviz} package, and is displayed in a separate X window using the program \textsf{display}. This works on UNIX systems. 

 A circle is displayed for every state of \mbox{\texttt{\slshape m}}, and there is an edge for every transition in \mbox{\texttt{\slshape m}}. It has label of the form $x/y$, where $x$ is the input symbol and $y$ is the corresponding output. Edges are coloured according to the input symbol,
in the order "red", "blue", "green", "gray", "yellow", "cyan", "orange",
"purple". If \mbox{\texttt{\slshape m}} has an initial state, it is indicated as a doubly circled state. 

 If \mbox{\texttt{\slshape m}} is a FR machine, \texttt{Draw} first attempts to convert it to a Mealy machine (see \texttt{AsMealyMachine} (\ref{AsMealyMachine:FR machine})). 

 It is assumed, but not checked, that \textsf{graphviz} and \textsf{display} are properly installed on the system. }

 

\subsection{\textcolor{Chapter }{Minimized (Mealy machine)}}
\logpage{[ 5, 2, 2 ]}\nobreak
\hyperdef{L}{X8395542D846FA2B9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Minimized({\slshape m})\index{Minimized@\texttt{Minimized}!Mealy machine}
\label{Minimized:Mealy machine}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A minimized machine equivalent to \mbox{\texttt{\slshape m}}.



 This function contructs the minimized Mealy machine \texttt{r} corresponding to \mbox{\texttt{\slshape m}}, by identifying isomorphic states; and, if \mbox{\texttt{\slshape m}} is initial, by removing inaccessible states. 

 If \mbox{\texttt{\slshape m}} is initial, the minimized automaton is such that its states are numbered first
by distance to the initial state, and then lexicographically by input letter.
(in particular, the initial state is 1). This makes comparison of minimized
automata efficient. 

 Furthermore, \texttt{Correspondence(r)} is a list describing, for each (accessible) state of \mbox{\texttt{\slshape m}}, its corresponding state in \texttt{r}; see \texttt{Correspondence} (\ref{Correspondence:FR machine}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> GrigorchukMachine := MealyMachine([[2,3],[4,4],[2,5],[4,4],[4,1]],
                                         [(),(1,2),(),(),()]);
  <Mealy machine on alphabet [ 1, 2 ] with 5 states>
  gap> g2 := GrigorchukMachine^2;
  <Mealy machine on alphabet [ 1, 2 ] with 25 states>
  gap> Minimized(g2);
  <Mealy machine on alphabet [ 1, 2 ] with 11 states, minimized>
  gap> Correspondence(last);
  [ 2, 1, 4, 11, 9, 1, 2, 5, 7, 6, 4, 3, 2, 9, 11, 11, 10, 9, 2, 4, 9, 8, 11, 4, 2 ]
  gap> e := FRElement(g2,11);
  <Mealy element on alphabet [ 1, 2 ] with 25 states, initial state 11>
  gap> Minimized(e);
  <Mealy element on alphabet [ 1, 2 ] with 5 states, initial state 1, minimized>
  gap> Correspondence(last);
  [ 3, 2, 1, 4, 5, 2, 3,,,, 1,, 3, 5, 4, 4,, 5, 3, 1, 5,, 4, 1, 3 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{DualMachine}}
\logpage{[ 5, 2, 3 ]}\nobreak
\hyperdef{L}{X809F069B798ED985}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DualMachine({\slshape m})\index{DualMachine@\texttt{DualMachine}}
\label{DualMachine}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The dual Mealy machine of \mbox{\texttt{\slshape m}}.



 This function constructs the \emph{dual} machine of \mbox{\texttt{\slshape m}}, i.e. the machine with stateset the alphabet of \mbox{\texttt{\slshape m}}, with alphabet the stateset of \mbox{\texttt{\slshape m}}, and similarly with transitions and output switched. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> b := MealyMachine([[3,2],[3,1],[3,3]],[(1,2),(),()]);
  <Mealy machine on alphabet [ 1, 2 ] with 3 states>
  gap> d := DualMachine(b)^4);
  <Mealy machine on alphabet [ 1, 2, 3 ] with 16 states>
  gap> Draw(d); # action on 2^4 points
  gap> DualMachine(d);
  <Mealy machine on alphabet [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16
   ] with 3 states>
  gap> Output(last,1)=Activity(FRElement(b,1),4);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsReversible}}
\logpage{[ 5, 2, 4 ]}\nobreak
\hyperdef{L}{X7D5D480C782FCC0B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsReversible({\slshape m})\index{IsReversible@\texttt{IsReversible}}
\label{IsReversible}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape m}} is a reversible Mealy machine.



 This function tests whether \mbox{\texttt{\slshape m}} is \emph{reversible}, i.e. whether the \texttt{DualMachine} (\ref{DualMachine}) of \mbox{\texttt{\slshape m}} is invertible. See \cite{MR1841119} for more details. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> IsReversible(MealyMachine([[1,2],[2,2]],[(1,2),()]));
  false
  gap> IsReversible(MealyMachine([[1,2],[2,1]],[(),(1,2)]));
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsMinimized}}
\logpage{[ 5, 2, 5 ]}\nobreak
\hyperdef{L}{X8310A1C08158793C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsMinimized({\slshape m})\index{IsMinimized@\texttt{IsMinimized}}
\label{IsMinimized}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape m}} is a minimized Mealy machine.



 This function tests whether \mbox{\texttt{\slshape m}} is \emph{minimized}, i.e. whether nono of its states can be removed or coalesced. All Mealy
elements are automatically minimized. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> AllMealyMachines(2, 2, IsBireversible,EquivalenceClasses);
  [ <Mealy machine on alphabet [ 1, 2 ] with 2 states>,
    <Mealy machine on alphabet [ 1, 2 ] with 2 states>,
    <Mealy machine on alphabet [ 1, 2 ] with 2 states>,
    <Mealy machine on alphabet [ 1, 2 ] with 2 states>,
    <Mealy machine on alphabet [ 1, 2 ] with 2 states>,
    <Mealy machine on alphabet [ 1, 2 ] with 2 states>,
    <Mealy machine on alphabet [ 1, 2 ] with 2 states>,
    <Mealy machine on alphabet [ 1, 2 ] with 2 states> ]
  gap> List(last,IsMinimized);
  [ false, true, false, false, false, false, true, false ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AlphabetInvolution}}
\logpage{[ 5, 2, 6 ]}\nobreak
\hyperdef{L}{X7CCB79B981912CCC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AlphabetInvolution({\slshape m})\index{AlphabetInvolution@\texttt{AlphabetInvolution}}
\label{AlphabetInvolution}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
A list giving, for each alphabet letter, its inverse.



 If \mbox{\texttt{\slshape m}} is a bireversible machine, it may happen that the stateset of the dual of \mbox{\texttt{\slshape m}} (see \texttt{DualMachine} (\ref{DualMachine})) is closed under taking inverses. If this happens, then this list records the
mapping from an alphabet letter of \mbox{\texttt{\slshape m}} to its inverse. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := GammaPQMachine(3,5);; AlphabetOfFRObject(m);
  [ 1 .. 6 ]
  gap> IsBireversible(m); AlphabetInvolution(GammaPQMachine(3,5));
  true
  [ 6, 5, 4, 3, 2, 1 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsBireversible}}
\logpage{[ 5, 2, 7 ]}\nobreak
\hyperdef{L}{X80D2545D7D0990A2}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsBireversible({\slshape m})\index{IsBireversible@\texttt{IsBireversible}}
\label{IsBireversible}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape m}} is a bireversible Mealy machine.



 This function tests whether \mbox{\texttt{\slshape m}} is \emph{bireversible}, i.e. whether all eight machines obtained from \mbox{\texttt{\slshape m}} using \texttt{DualMachine} (\ref{DualMachine}) and \texttt{Inverse} are well-defined. See \cite{MR1841119} for more details. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> IsBireversible(MealyMachine([[1,2],[2,1]],[(),(1,2)]));
  false
  gap> IsBireversible(MealyMachine([[1,1],[2,2]],[(),(1,2)]));
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{StateGrowth}}
\logpage{[ 5, 2, 8 ]}\nobreak
\hyperdef{L}{X83364DAB825D7A0D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StateGrowth({\slshape m[, x]})\index{StateGrowth@\texttt{StateGrowth}}
\label{StateGrowth}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The state growth of the Mealy machine or element \mbox{\texttt{\slshape m}}.



 This function computes, as a rational function, the power series in \mbox{\texttt{\slshape x}} whose coefficient of degree $n$ is the number of non-trivial states at level $n$ of the tree. 

 If \mbox{\texttt{\slshape x}} is absent, it is assumed to be \texttt{Indeterminate(Rationals)}. 

 If \mbox{\texttt{\slshape m}} is a Mealy machine, this function is computed with respect to all possible
starting states. If \mbox{\texttt{\slshape m}} is a Mealy element, this function is computed with respect to the initial
state of \mbox{\texttt{\slshape m}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> b := MealyMachine([[3,2],[3,1],[3,3]],[(1,2),(),()]);
  <Mealy machine on alphabet [ 1, 2 ] with 3 states>
  gap> StateGrowth(b,Indeterminate(Rationals));
  (2)/(-x_1+1)
  gap> StateGrowth(FRElement(b,1),Indeterminate(Rationals));
  (1)/(-x_1+1)
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Degree (FR element)}}
\logpage{[ 5, 2, 9 ]}\nobreak
\hyperdef{L}{X84BE780A81CAC69C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Degree({\slshape m})\index{Degree@\texttt{Degree}!FR element}
\label{Degree:FR element}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DegreeOfFRMachine({\slshape m})\index{DegreeOfFRMachine@\texttt{DegreeOfFRMachine}}
\label{DegreeOfFRMachine}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DegreeOfFRElement({\slshape m})\index{DegreeOfFRElement@\texttt{DegreeOfFRElement}}
\label{DegreeOfFRElement}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The growth degree of the Mealy machine or element \mbox{\texttt{\slshape m}}.



 This function computes the order of the pole at $x=1$ of \texttt{StateGrowth(m,x)}, in case its denominator is a product of cyclotomics; and returns \texttt{infinity} otherwise. 

 This attribute of Mealy machines was studied inter alia in \cite{MR1774362}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := MealyMachine([[2,1],[3,2],[3,3]],[(),(1,2),()]);
  <Mealy machine on alphabet [ 1, 2 ] with 3 states>
  gap> StateGrowth(m,Indeterminate(Rationals));
  (-x_1+2)/(x_1^2-2*x_1+1)
  gap> List(StateSet(m),i->Degree(FRElement(m,i)));
  [ 2, 1, -1 ]
  gap> a := MealyMachine(Group((1,2)),Group((1,2)),\*,\*);
  <Mealy machine on alphabet [ (), (1,2) ] with states Group( [ (1,2) ] )>
  gap> Degree(a);
  infinity
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsFinitaryFRElement}}
\logpage{[ 5, 2, 10 ]}\nobreak
\hyperdef{L}{X793C427084F830CE}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFinitaryFRElement({\slshape e})\index{IsFinitaryFRElement@\texttt{IsFinitaryFRElement}}
\label{IsFinitaryFRElement}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFinitaryFRMachine({\slshape e})\index{IsFinitaryFRMachine@\texttt{IsFinitaryFRMachine}}
\label{IsFinitaryFRMachine}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape e}} is a finitary element.



 This function tests whether \mbox{\texttt{\slshape e}} is a finitary element. These are by definition the elements of growth degree
at most $0$. 

 When applied to a Mealy machine, it returns \texttt{true} if all states of \mbox{\texttt{\slshape e}} are finitary. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := GuptaSidkiMachines(3);; Display(m);
     |  1     2     3
  ---+-----+-----+-----+
   a | a,1   a,2   a,3
   b | a,2   a,3   a,1
   c | a,3   a,1   a,2
   d | b,1   c,2   d,3
  ---+-----+-----+-----+
  gap> Filtered(StateSet(m),i->IsFinitaryFRElement(FRElement(m,i)));
  [ 1, 2, 3 ]
  gap> IsFinitaryFRElement(m);
  false
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Depth (FR element)}}
\logpage{[ 5, 2, 11 ]}\nobreak
\hyperdef{L}{X7E5E8B2C79688DC0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Depth({\slshape m})\index{Depth@\texttt{Depth}!FR element}
\label{Depth:FR element}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DepthOfFRMachine({\slshape m})\index{DepthOfFRMachine@\texttt{DepthOfFRMachine}}
\label{DepthOfFRMachine}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DepthOfFRElement({\slshape m})\index{DepthOfFRElement@\texttt{DepthOfFRElement}}
\label{DepthOfFRElement}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
The depth of the finitary Mealy machine or element \mbox{\texttt{\slshape m}}.



 This function computes the maximal level at which the \mbox{\texttt{\slshape m}} has an non-trivial state. In particular the identity has depth 0, and FR
elements acting only at the root vertex have depth 1. The value \texttt{infinity} is returned if \mbox{\texttt{\slshape m}} is not finitary (see \texttt{IsFinitaryFRElement} (\ref{IsFinitaryFRElement})). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := MealyMachine([[2,1],[3,3],[4,4],[4,4]],[(),(),(1,2),()]);
  <Mealy machine on alphabet [ 1, 2 ] with 4 states>
  gap> DepthOfFRMachine(m);
  infinity
  gap> List(StateSet(m),i->DepthOfFRElement(FRElement(m,i)));
  [ infinity, 2, 1, 0 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsBoundedFRElement}}
\logpage{[ 5, 2, 12 ]}\nobreak
\hyperdef{L}{X82F4410E85C54C7E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsBoundedFRElement({\slshape e})\index{IsBoundedFRElement@\texttt{IsBoundedFRElement}}
\label{IsBoundedFRElement}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsBoundedFRMachine({\slshape e})\index{IsBoundedFRMachine@\texttt{IsBoundedFRMachine}}
\label{IsBoundedFRMachine}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape e}} is a finitary element.



 This function tests whether \mbox{\texttt{\slshape e}} is a bounded element. These are by definition the elements of growth degree at
most $1$. 

 When applied to a Mealy machine, it returns \texttt{true} if all states of \mbox{\texttt{\slshape e}} are bounded. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := GuptaSidkiMachines(3);; Display(m);
     |  1     2     3
  ---+-----+-----+-----+
   a | a,1   a,2   a,3
   b | a,2   a,3   a,1
   c | a,3   a,1   a,2
   d | b,1   c,2   d,3
  ---+-----+-----+-----+
  gap> Filtered(StateSet(m),i->IsBoundedFRElement(FRElement(m,i)));
  [ 1, 2, 3, 4 ]
  gap> IsBoundedFRMachine(m);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsPolynomialGrowthFRElement}}
\logpage{[ 5, 2, 13 ]}\nobreak
\hyperdef{L}{X81D4A3F27C5FAD96}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsPolynomialGrowthFRElement({\slshape e})\index{IsPolynomialGrowthFRElement@\texttt{IsPolynomialGrowthFRElement}}
\label{IsPolynomialGrowthFRElement}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsPolynomialGrowthFRMachine({\slshape e})\index{IsPolynomialGrowthFRMachine@\texttt{IsPolynomialGrowthFRMachine}}
\label{IsPolynomialGrowthFRMachine}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape e}} is an element of polynomial growth.



 This function tests whether \mbox{\texttt{\slshape e}} is a polynomial element. These are by definition the elements of polynomial
growth degree. 

 When applied to a Mealy machine, it returns \texttt{true} if all states of \mbox{\texttt{\slshape e}} are of polynomial growth. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := GuptaSidkiMachines(3);; Display(m);
     |  1     2     3
  ---+-----+-----+-----+
   a | a,1   a,2   a,3
   b | a,2   a,3   a,1
   c | a,3   a,1   a,2
   d | b,1   c,2   d,3
  ---+-----+-----+-----+
  gap> Filtered(StateSet(m),i->IsPolynomialGrowthFRElement(FRElement(m,i)));
  [ 1, 2, 3, 4 ]
  gap> IsPolynomialGrowthFRMachine(m);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Signatures}}
\logpage{[ 5, 2, 14 ]}\nobreak
\hyperdef{L}{X7ECE17387910C023}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Signatures({\slshape e})\index{Signatures@\texttt{Signatures}}
\label{Signatures}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A list describing the product of the activities on each level.



 This function computes the product of the activities of \mbox{\texttt{\slshape e}} on each level, and returns a periodic list describing it (see \texttt{PeriodicList} (\ref{PeriodicList})). 

 The entries \texttt{pi} are permutations, and their values are meaningful only when projected in the
abelianization of \texttt{VertexTransformationsFRElement(e)}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Signatures(GrigorchukGroup.1);
  [ (1,2), / () ]
  gap> Signatures(GrigorchukGroup.2);
  [/ (), (1,2), (1,2) ]
  gap> last[50];
  (1,2)
  gap> Signatures(AddingMachine(3)[2]);
  [/ (1,2,3) ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{VertexTransformationsFRMachine}}
\logpage{[ 5, 2, 15 ]}\nobreak
\hyperdef{L}{X83DFDC3384EA4634}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{VertexTransformationsFRMachine({\slshape m})\index{VertexTransformationsFRMachine@\texttt{VertexTransformationsFRMachine}}
\label{VertexTransformationsFRMachine}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{VertexTransformationsFRElement({\slshape e})\index{VertexTransformationsFRElement@\texttt{VertexTransformationsFRElement}}
\label{VertexTransformationsFRElement}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The group/monoid generated by all vertex transformations of states of \mbox{\texttt{\slshape m}}.



 The first function computes the finite permutation group / transformation
monoid generated by all outputs of states of \mbox{\texttt{\slshape m}}. 

 The second command is a short-hand for \texttt{VertexTransformationsFRMachine(UnderlyingFRMachine(e))}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := MealyMachine([[1,3,2],[3,2,1],[2,1,3]],[(2,3),(1,3),(1,2)]);
  <Mealy machine on alphabet [ 1, 2 ] with 3 states>
  gap> VertexTransformationsFRMachine(m);
  Group([ (2,3), (1,3), (1,2) ])
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{FixedRay (FR element)}}
\logpage{[ 5, 2, 16 ]}\nobreak
\hyperdef{L}{X7E0CB3767CE08692}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FixedRay({\slshape e})\index{FixedRay@\texttt{FixedRay}!FR element}
\label{FixedRay:FR element}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The lexicographically first ray fixed by \mbox{\texttt{\slshape e}}.



 This function computes the lexicographically first infinite sequence that is
fixed by the FR element \mbox{\texttt{\slshape e}}, and returns it as a periodic list (see \texttt{PeriodicList} (\ref{PeriodicList})). It returns \texttt{fail} if no such ray exists. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := MealyMachine([[1,3,2],[3,2,1],[2,1,3]],[(2,3),(1,3),(1,2)]);
  <Mealy machine on alphabet [ 1, 2 ] with 3 states>
  gap> FixedRay(FRElement(m,1));
  [/ 1 ]
  gap> last^FRElement(m,1);
  [/ 1 ]
  gap> FixedRay(FRElement(m,[1,2]));
  fail
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsLevelTransitive (FR element)}}
\logpage{[ 5, 2, 17 ]}\nobreak
\hyperdef{L}{X828C167B7D7691E9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsLevelTransitive({\slshape e})\index{IsLevelTransitive@\texttt{IsLevelTransitive}!FR element}
\label{IsLevelTransitive:FR element}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape e}} acts transitively on each level of the tree.



 This function tests whether \mbox{\texttt{\slshape e}} acts transitively on each level of the tree. It is implemented only if \texttt{VertexTransformationsFRElement(e)} is abelian. 

 This function is used as a simple test to detect whether an element has
infinite order: if \mbox{\texttt{\slshape e}} has a fixed vertex $v$ such that the \texttt{State(e,v)} is level-transitive, then \mbox{\texttt{\slshape e}} has infinite order. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := AddingMachine(3);; Display(m);
     |  1     2     3
  ---+-----+-----+-----+
   a | a,1   a,2   a,3
   b | a,2   a,3   b,1
  ---+-----+-----+-----+
  Initial state:  b
  gap> IsLevelTransitive(m);
  true
  gap> IsLevelTransitive(Product(UnderlyingFRMachine(GrigorchukOverGroup){[2..5]}));
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AsMealyMachine (FR machine)}}
\logpage{[ 5, 2, 18 ]}\nobreak
\hyperdef{L}{X79EFE2C97D2CCEEC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsMealyMachine({\slshape m})\index{AsMealyMachine@\texttt{AsMealyMachine}!FR machine}
\label{AsMealyMachine:FR machine}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
A Mealy machine isomorphic to \mbox{\texttt{\slshape m}}.



 This function constructs a Mealy machine \texttt{r}, which is as close as possible to the FR machine \mbox{\texttt{\slshape m}}. Furthermore, \texttt{Correspondence(r)} is a list identifying, for every generator of the stateset of \mbox{\texttt{\slshape m}}, a corresponding state in the new Mealy machine; see \texttt{Correspondence} (\ref{Correspondence:FR machine}). 

 \mbox{\texttt{\slshape m}} may be a group/monoid/semigroup FR machine, or a Mealy machine; in which case
the result is returned unchanged. 

 In particular, \texttt{FRElement(m,s)} and \texttt{FRElement(AsMealyMachine(m),s)} return the same tree automorphism, for any FR machine \texttt{m} and any state \texttt{s}. 

 This function is not guaranteed to return; if \mbox{\texttt{\slshape m}} does not have finite states, then it will loop forever. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := FRMachine(["tau","mu"],[[[],[1]],[[],[-2]]],[(1,2),(1,2)]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ tau, mu ] )>
  gap> Display(n);
       |     1         2
  -----+--------+---------+
   tau | <id>,2     tau,1
    mu | <id>,2   mu^-1,1
  -----+--------+---------+
  gap> AsMealyMachine(n);
  <Mealy machine on alphabet [ 1, 2 ] with 4 states>
  gap> Display(last);
     |  1     2
  ---+-----+-----+
   a | c,2   a,1
   b | c,2   d,1
   c | c,1   c,2
   d | b,2   c,1
  ---+-----+-----+
  gap> Correspondence(last);
  [ 1, 2 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AsMealyMachine (List)}}
\logpage{[ 5, 2, 19 ]}\nobreak
\hyperdef{L}{X80F9A18483F98442}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsMealyMachine({\slshape l})\index{AsMealyMachine@\texttt{AsMealyMachine}!List}
\label{AsMealyMachine:List}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
A Mealy machine constructed out of the FR elements in \mbox{\texttt{\slshape l}}.



 This function constructs a Mealy machine \texttt{r}, with states \mbox{\texttt{\slshape l}} (which must be a state-closed set). Its outputs are the outputs of its
elements, and its transitions are the transitions of its elements; in
particular, \texttt{FRElement(r,i)} is equal to \texttt{l[i]} as an FR element. 

 \texttt{Correspondence(r)} records the argument \mbox{\texttt{\slshape l}}. 

 This function returns \texttt{fail} if \mbox{\texttt{\slshape l}} is not state-closed. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap>  mu := FRElement([[[],[-1]]],[(1,2)],[1]);
  <2|f1>
  gap>
  gap> States(mu);
  [ <2|f1>, <2|identity ...>, <2|f1^-1> ]
  gap> AsMealyMachine(last);
  <Mealy machine on alphabet [ 1, 2 ] with 3 states>
  gap> Display(last);
     |  1     2
  ---+-----+-----+
   a | b,2   c,1
   b | b,1   b,2
   c | a,2   b,1
  ---+-----+-----+
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AsMealyElement}}
\logpage{[ 5, 2, 20 ]}\nobreak
\hyperdef{L}{X7FB3F0A2878DD2CF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsMealyElement({\slshape m})\index{AsMealyElement@\texttt{AsMealyElement}}
\label{AsMealyElement}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
A Mealy element isomorphic to \mbox{\texttt{\slshape m}}.



 This function constructs a Mealy element, which induces the same tree
automorphism as the FR element \mbox{\texttt{\slshape m}}. 

 \mbox{\texttt{\slshape m}} may be a group/monoid/semigroup FR element, or a Mealy element; in which case
the result is returned unchanged. 

 This function is not guaranteed to return; if \mbox{\texttt{\slshape m}} does not have finite states, then it will loop forever. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> mu := FRElement([[[],[-1]]],[(1,2)],[1]);
  <2|f1>
  gap> AsMealyElement(mu);
  <Mealy machine on alphabet [ 1, 2 ] with 3 states, initial state 1>
  gap> [[2,1]]^last;
  [ [ 1, 2 ] ]
  gap> [2,1,2,1]^mu;
  [ 1, 2, 1, 2 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AsIntMealyMachine}}
\logpage{[ 5, 2, 21 ]}\nobreak
\hyperdef{L}{X7FBBBD9A839011C8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsIntMealyMachine({\slshape m})\index{AsIntMealyMachine@\texttt{AsIntMealyMachine}}
\label{AsIntMealyMachine}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsIntMealyElement({\slshape m})\index{AsIntMealyElement@\texttt{AsIntMealyElement}}
\label{AsIntMealyElement}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
A Mealy machine in integer format, isomorphic to \mbox{\texttt{\slshape m}}.



 This function constructs a Mealy machine \texttt{r}, which has similar behaviour as \mbox{\texttt{\slshape m}} while having stateset \texttt{[1..n]} for some natural \texttt{n}. Most \textsf{FR} commands operate efficiently only on Mealy machines of this type. 

 This function is not guaranteed to return; if \mbox{\texttt{\slshape m}} does not have finite states, then it will loop forever. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> g := Group((1,2));; n := MealyMachine(g,g,\*,\*);
  <Mealy machine on alphabet [ (), (1,2) ] with states Group( [ (1,2) ] )>
  gap> Display(n);
         |      ()            (1,2)
  -------+-------------+-------------+
      () |    (),()      (1,2),(1,2)
   (1,2) | (1,2),(1,2)      (),()
  -------+-------------+-------------+
  gap> AsIntMealyMachine(n);
  <Mealy machine on alphabet [ 1, 2 ] with 2 states>
  gap> Display(last);
     |  1     2
  ---+-----+-----+
   a | a,1   b,2
   b | b,2   a,1
  ---+-----+-----+
  gap> Correspondence(last);
  [ 1, 2 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{TopElement}}
\logpage{[ 5, 2, 22 ]}\nobreak
\hyperdef{L}{X8191456B7E586785}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TopElement({\slshape p[, n]})\index{TopElement@\texttt{TopElement}}
\label{TopElement}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
A Mealy machine in integer format, acting on the first symbol of sequences.



 This function constructs a Mealy machine \texttt{r}, which acts as \mbox{\texttt{\slshape p}} on the first letter of sequences and fixes the other letters. The argument \mbox{\texttt{\slshape n}} is the size of the alphabet of \texttt{r}; if it is ommitted, then it is assumed to be the degree of the transformation \mbox{\texttt{\slshape p}}, or the largest moved point of the permutation or trans \mbox{\texttt{\slshape p}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> a := TopElement((1,2));
  <Mealy element on alphabet [ 1, 2 ] with 2 states>
  gap> last=GrigorchukGroup.1;
  true
  gap> a := TopElement((1,2),3);
  <Mealy element on alphabet [ 1, 2, 3 ] with 2 states>
  gap> last in GuptaSidkiGroup;
  false
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ConfinalityClasses}}
\logpage{[ 5, 2, 23 ]}\nobreak
\hyperdef{L}{X7A87ED9D789245E4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ConfinalityClasses({\slshape e})\index{ConfinalityClasses@\texttt{ConfinalityClasses}}
\label{ConfinalityClasses}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsWeaklyFinitaryFRElement({\slshape e})\index{IsWeaklyFinitaryFRElement@\texttt{IsWeaklyFinitaryFRElement}}
\label{IsWeaklyFinitaryFRElement}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
A list describing the non-trivial confinality classes of \mbox{\texttt{\slshape e}}.



 If \mbox{\texttt{\slshape e}} is a bounded element (see \texttt{IsBoundedFRElement} (\ref{IsBoundedFRElement})), there are finitely many infinite sequences that have confinality class
larger that one; i.e. ultimately periodic sequences that are mapped by \mbox{\texttt{\slshape e}} to a sequence with different period. This function returns a list of
equivalence classes of periodic lists, see \texttt{PeriodicList} (\ref{PeriodicList}), which are related under \mbox{\texttt{\slshape e}}. 

 By definition, an element is \emph{weakly finitary} if it has no non-singleton confinality classes. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> g := FRGroup("t=<,,t>(2,3)","u=<u,,>(1,2)","v=<u,t,>");;
  gap> ConfinalityClasses(g.1);
  [ {PeriodicList([  ],[ 2 ])} ]
  gap> List(GeneratorsOfGroup(g),x->Elements(ConfinalityClasses(x)[1]));
  [ [ [/ 2 ], [/ 3 ] ],
    [ [/ 1 ], [/ 2 ] ],
    [ [/ 1 ], [/ 2 ], [/ 3 ] ] ]
  gap> IsWeaklyFinitaryFRElement(BinaryAddingElement);
  false
  gap> IsWeaklyFinitaryFRElement(GuptaSidkiGroup.2);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Germs}}
\logpage{[ 5, 2, 24 ]}\nobreak
\hyperdef{L}{X81592E3D79745A40}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Germs({\slshape e})\index{Germs@\texttt{Germs}}
\label{Germs}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NormOfBoundedFRElement({\slshape e})\index{NormOfBoundedFRElement@\texttt{NormOfBoundedFRElement}}
\label{NormOfBoundedFRElement}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
The germs of the bounded element \mbox{\texttt{\slshape e}}.



 The \emph{germs} of a bounded element are the finitely many ultimately periodic sequences on
which the state of \mbox{\texttt{\slshape e}} does not vanish. This function returns the germs of \mbox{\texttt{\slshape e}}, as a list of pairs; the first entry is a ray described as a periodic
sequence of integers (see \texttt{PeriodicList} (\ref{PeriodicList})), and the second entry is the periodic sequence of states that appear along
that ray. 

 The \emph{norm} of a bounded element is the length of its list of germs. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Germs(BinaryAddingElement);
  [ [ [/ 2 ], [/ 1 ] ] ]
  gap> Germs(GrigorchukGroup.1);
  [  ]
  gap> Germs(GrigorchukGroup.2);
  [ [ [/ 2 ], [/ 1, 3, 5 ] ] ]
  gap> Display(GrigorchukGroup.2);
     |  1     2
  ---+-----+-----+
   a | b,1   c,2
   b | d,2   d,1
   c | b,1   e,2
   d | d,1   d,2
   e | d,1   a,2
  ---+-----+-----+
  Initial state: a
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{HasOpenSetConditionFRElement}}
\logpage{[ 5, 2, 25 ]}\nobreak
\hyperdef{L}{X7F76AF2D7C0279F9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{HasOpenSetConditionFRElement({\slshape e})\index{HasOpenSetConditionFRElement@\texttt{HasOpenSetConditionFRElement}}
\label{HasOpenSetConditionFRElement}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape e}} has the open set condition.



 An FR element \mbox{\texttt{\slshape e}} has the \emph{open set condition} if for every infinite ray in the tree which is fixed by \mbox{\texttt{\slshape e}}, there is an open set around that ray which is also fixed by \mbox{\texttt{\slshape e}}. This function tests for \mbox{\texttt{\slshape e}} to have the open set condition. It currently is implemented only for bounded
elements. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> HasOpenSetConditionFRElement(GrigorchukGroup.1);
  true
  gap> HasOpenSetConditionFRElement(GrigorchukGroup.2);
  false
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{LimitMachine}}
\logpage{[ 5, 2, 26 ]}\nobreak
\hyperdef{L}{X82308064814FEA51}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LimitMachine({\slshape m})\index{LimitMachine@\texttt{LimitMachine}}
\label{LimitMachine}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
The submachine of \mbox{\texttt{\slshape m}} on all recurrent states.



 This command creates a new Mealy machine, with stateset the limit states of \mbox{\texttt{\slshape m}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := MealyMachine([[2,2,3],[2,3,3],[3,3,3]],[(),(),(1,2,3)]);
  <Mealy machine on alphabet [ 1 .. 3 ] with 3 states>
  gap> Display(m);
     |  1     2     3
  ---+-----+-----+-----+
   a | b,1   b,2   c,3
   b | b,1   c,2   c,3
   c | c,2   c,3   c,1
  ---+-----+-----+-----+
  gap> LimitStates(m);
  [ <Mealy element on alphabet [ 1 .. 3 ] with 2 states>,
    <Mealy element on alphabet [ 1 .. 3 ] with 1 state> ]
  gap> LimitMachine(m);
  <Mealy machine on alphabet [ 1 .. 3 ] with 2 states>
  gap> Display(last);
     |  1     2     3
  ---+-----+-----+-----+
   a | a,1   b,2   b,3
   b | b,2   b,3   b,1
  ---+-----+-----+-----+
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{NucleusMachine (FR machine)}}
\logpage{[ 5, 2, 27 ]}\nobreak
\hyperdef{L}{X7F8163B5816969C8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NucleusMachine({\slshape m})\index{NucleusMachine@\texttt{NucleusMachine}!FR machine}
\label{NucleusMachine:FR machine}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
The nucleus of \mbox{\texttt{\slshape m}}.



 This command creates a new Mealy machine \texttt{n}, which is such that \texttt{LimitMachine(m*n)} is isomorphic to \texttt{n}, after minimisation. It is also isomorphic to the \texttt{NucleusMachine} (\ref{NucleusMachine:FR semigroup}) of the state closure of the \texttt{SCSemigroup} (\ref{SCSemigroup}) of \mbox{\texttt{\slshape m}}. (Note that the ordering of the states in the resulting machine is not
necessarily the same as in \mbox{\texttt{\slshape m}}; however, if \mbox{\texttt{\slshape m}} and \texttt{n} are isomorphic, then this command returns \mbox{\texttt{\slshape m}}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := MealyMachine([[2,1,1],[2,2,2]],[(1,2,3),()]);
  <Mealy machine on alphabet [ 1, 2, 3 ] with 2 states>
  gap> Display(m);
     |  1     2     3
  ---+-----+-----+-----+
   a | b,2   a,3   a,1
   b | b,1   b,2   b,3
  ---+-----+-----+-----+
  gap> NucleusMachine(m);
  <Mealy machine on alphabet [ 1, 2, 3 ] with 3 states>
  gap> Display(last);
     |  1     2     3
  ---+-----+-----+-----+
   a | a,1   a,2   a,3
   b | c,3   b,1   c,2
   c | a,2   c,3   c,1
  ---+-----+-----+-----+
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{GuessMealyElement}}
\logpage{[ 5, 2, 28 ]}\nobreak
\hyperdef{L}{X7B29565784A591EC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GuessMealyElement({\slshape p, d, n})\index{GuessMealyElement@\texttt{GuessMealyElement}}
\label{GuessMealyElement}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A Mealy element that probably has the same activity as \mbox{\texttt{\slshape p}}.



 This function receives a permutation or transformation \mbox{\texttt{\slshape p}}, a degree \mbox{\texttt{\slshape d}} and a level \mbox{\texttt{\slshape n}}, and attempts to find a Mealy element on the alphabet \texttt{[1..d]} whose activity on level \mbox{\texttt{\slshape n}} is \mbox{\texttt{\slshape p}}. 

 This function returns \texttt{fail} if it thinks that the given level is not large enough to make a reasonable
guess. In all cases, the function is not guaranteed to return the correct
Mealy machine. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> GuessMealyElement(Activity(GrigorchukGroup.2,6),2,6);
  <Mealy element on alphabet [ 1, 2 ] with 5 states>
  gap> last=GrigorchukGroup.2;
  true
  gap> GuessMealyElement(Activity(GrigorchukGroup.2,5),2,5);
  fail
  gap> ComposeElement([GrigorchukGroup.2,One(GrigorchukGroup)],());
  <Mealy element on alphabet [ 1, 2 ] with 6 states>
  gap> last=GuessMealyElement(Activity(GrigorchukGroup.2,6),2,7);
  true
\end{Verbatim}
 }

 }

 }

 
\chapter{\textcolor{Chapter }{Linear machines and elements}}\label{vector}
\logpage{[ 6, 0, 0 ]}
\hyperdef{L}{X84AD415C872BFB91}{}
{
 \emph{Linear} machines are a special class of FR machines, in which the stateset $Q$ and the alphabet $X$ are vector spaces over a field $\Bbbk$, and the transition map $\phi: Q\otimes X\to X\otimes Q$ is a linear map; furthermore, there is a functional $\pi:Q\to\Bbbk$ called the \emph{output}. 

As before, a choice of initial state $q\in Q$ induces a linear map $q:T(X)\to T(X)$, where $T(X)=\bigoplus X^{\otimes n}$ is the tensor algebra generated by $X$. This map is defined as follows: given $x=x_1\otimes\dots\otimes x_n\in T(X)$, rewrite $q\otimes x$ as a sum of expressions of the form $y\otimes r$ with $y\in T(X)$ and $r\in Q$; then $q$, by definition, maps $x$ to the sum of the $\pi(r)y$. 

 There are two sorts of linear machines: \emph{vector machines}, for which the state space is a finite-dimensional vector space over a field;
and \emph{algebra machines}, for which the state space is a free algebra in a finite set of variables. 

 In a vector machine, the transition and output maps are stored as a matrix and
a vector respectively. Minimization algorithms are implemented, as for Mealy
machines. 

 In an algebra machine, the transition and output maps are stored as words in
the algebra. These machines are natural extensions of group/monoid/semigroup
machines. 

 Linear elements are given by a linear machine and an initial state. They can
be added and multiplied, and act on the tensor algebra of the alphabet,
admitting natural representations as matrices. 
\section{\textcolor{Chapter }{Methods and operations for \texttt{LinearFRMachine}s and \texttt{LinearFRElement}s}}\logpage{[ 6, 1, 0 ]}
\hyperdef{L}{X812C0F7B7A31FCEF}{}
{
 

\subsection{\textcolor{Chapter }{VectorMachine}}
\logpage{[ 6, 1, 1 ]}\nobreak
\hyperdef{L}{X7F1EB8CB87229764}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{VectorMachine({\slshape domain, transitions, output})\index{VectorMachine@\texttt{VectorMachine}}
\label{VectorMachine}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{VectorElement({\slshape domain, transitions, output, init})\index{VectorElement@\texttt{VectorElement}}
\label{VectorElement}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{VectorMachineNC({\slshape fam, transitions, output})\index{VectorMachineNC@\texttt{VectorMachineNC}}
\label{VectorMachineNC}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{VectorElementNC({\slshape fam, transitions, output, init})\index{VectorElementNC@\texttt{VectorElementNC}}
\label{VectorElementNC}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new vector machine/element.



 This function constructs a new linear machine or element, of vector type. 

 \mbox{\texttt{\slshape transitions}} is a matrix of matrices; for \texttt{a,b} indices of basis vectors of the alphabet, \texttt{transitions[a][b]} is a square matrix indexed by the stateset, which is the transition to be
effected on the stateset upon the output $a\to b$. 

 \mbox{\texttt{\slshape output}} and \mbox{\texttt{\slshape init}} are vectors in the stateset. 

 In the "NC" version, no tests are performed to check that the arguments
contain values within bounds, or even of the right type (beyond the simple
checking performed by \textsf{GAP}'s method selection algorithms). The first argument should be the family of
the resulting object. These "NC" methods are mainly used internally by the
package. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> M := VectorMachine(Rationals,[[[[1]],[[2]]],[[[3]],[[4]]]],[1]);
  <Linear machine on alphabet Rationals^2 with 1-dimensional stateset>
  gap> Display(M);
   Rationals | 1 | 2 |
  -----------+---+---+
           1 | 1 | 2 |
  -----------+---+---+
           2 | 3 | 4 |
  -----------+---+---+
  Output: 1
  gap> A := VectorElement(Rationals,[[[[1]],[[2]]],[[[3]],[[4]]]],[1],[1]);
  <Linear element on alphabet Rationals^2 with 1-dimensional stateset>
  gap> Display(Activity(A,2));
  [ [   1,   2,   2,   4 ],
    [   3,   4,   6,   8 ],
    [   3,   6,   4,   8 ],
    [   9,  12,  12,  16 ] ]
  gap> DecompositionOfFRElement(A);
  [ [ <Linear element on alphabet Rationals^2 with 1-dimensional stateset>,
        <Linear element on alphabet Rationals^2 with 1-dimensional stateset> ],
    [ <Linear element on alphabet Rationals^2 with 1-dimensional stateset>,
        <Linear element on alphabet Rationals^2 with 1-dimensional stateset> ] ]
  gap> last=[[A,2*A],[3*A,4*A]];
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AlgebraMachine}}
\logpage{[ 6, 1, 2 ]}\nobreak
\hyperdef{L}{X7F65118683209DC5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AlgebraMachine({\slshape [domain, ]ring, transitions, output})\index{AlgebraMachine@\texttt{AlgebraMachine}}
\label{AlgebraMachine}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AlgebraElement({\slshape [domain, ]ring, transitions, output, init})\index{AlgebraElement@\texttt{AlgebraElement}}
\label{AlgebraElement}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AlgebraMachineNC({\slshape fam, ring, transitions, output})\index{AlgebraMachineNC@\texttt{AlgebraMachineNC}}
\label{AlgebraMachineNC}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AlgebraElementNC({\slshape fam, ring, transitions, output, init})\index{AlgebraElementNC@\texttt{AlgebraElementNC}}
\label{AlgebraElementNC}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new algebra machine/element.



 This function constructs a new linear machine or element, of algebra type. 

 \mbox{\texttt{\slshape ring}} is a free associative algebra, optionally with one. \mbox{\texttt{\slshape domain}} is the vector space on which the alphabet is defined. If absent, this argument
defaults to the \texttt{LeftActingDomain} (\textbf{Reference: LeftActingDomain}) of \mbox{\texttt{\slshape ring}}. 

 \mbox{\texttt{\slshape transitions}} is a list of matrices; for each generator number $i$ of \mbox{\texttt{\slshape ring}}, the matrix \texttt{transitions[i]}, with entries in \mbox{\texttt{\slshape ring}}, describes the decomposition of generator $i$ as a matrix. 

 \mbox{\texttt{\slshape output}} is a vector over \mbox{\texttt{\slshape domain}}, and \mbox{\texttt{\slshape init}} is a vector over \mbox{\texttt{\slshape ring}}. 

 In the "NC" version, no tests are performed to check that the arguments
contain values within bounds, or even of the right type (beyond the simple
checking performed by \textsf{GAP}'s method selection algorithms). The first argument should be the family of
the resulting object. These "NC" methods are mainly used internally by the
package. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> F := FreeAssociativeAlgebraWithOne(Rationals,1);;
  gap> A := AlgebraMachine(F,[[[F.1,F.1^2+F.1],[One(F),Zero(F)]]],[1]);
  <Linear machine on alphabet Rationals^2 with generators [ (1)*x.1 ]>
  gap> Display(A);
   Rationals |     1     |     2     |
  -----------+-----------+-----------+
           1 |       x.1 | x.1+x.1^2 |
  -----------+-----------+-----------+
           2 |         1 |         0 |
  -----------+-----------+-----------+
  Output: 1
  gap> M := AlgebraElement(F,[[[F.1,F.1^2+F.1],[One(F),Zero(F)]]],[1],F.1);
  <Rationals^2|(1)*x.1>
  gap> Display(Activity(M,2));
  [ [  1,  2,  4,  4 ],
    [  1,  0,  2,  2 ],
    [  1,  0,  0,  0 ],
    [  0,  1,  0,  0 ] ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Transition (Linear machine)}}
\logpage{[ 6, 1, 3 ]}\nobreak
\hyperdef{L}{X7A19036B828BBA0C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Transition({\slshape m, s, a, b})\index{Transition@\texttt{Transition}!Linear machine}
\label{Transition:Linear machine}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
An element of \mbox{\texttt{\slshape m}}'s stateset.



 This function returns the state reached by \mbox{\texttt{\slshape m}} when started in state \mbox{\texttt{\slshape s}} and performing output $a\to b$. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> M := AsVectorMachine(Rationals,FRMachine(GuptaSidkiGroup.2));
  <Linear machine on alphabet Rationals^3 with 4-dimensional stateset>
  gap> Transition(M,[1,0,0,0],[1,0,0],[1,0,0]);
  [ 0, 1, 0, 0 ]
  gap> Transition(M,[1,0,0,0],[0,1,0],[0,1,0]);
  [ 0, 0, 1, 0 ]
  gap> Transition(M,[1,0,0,0],[0,0,1],[0,0,1]);
  [ 1, 0, 0, 0 ]
  gap> A := AsVectorElement(Rationals,GuptaSidkiGroup.2);
  <Linear element on alphabet Rationals^3 with 4-dimensional stateset>
  gap> Transition(A,[1,0,0],[1,0,0]);
  [ 0, 1, 0, 0 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Transitions}}
\logpage{[ 6, 1, 4 ]}\nobreak
\hyperdef{L}{X846683198081BA82}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Transitions({\slshape m, s, a})\index{Transitions@\texttt{Transitions}}
\label{Transitions}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
An vector of elements of \mbox{\texttt{\slshape m}}'s stateset.



 This function returns the state reached by \mbox{\texttt{\slshape m}} when started in state \mbox{\texttt{\slshape s}} and receiving input \mbox{\texttt{\slshape a}}. The output is a vector, indexed by the alphabet's basis, of output states. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> M := AsVectorMachine(Rationals,FRMachine(GuptaSidkiGroup.2));
  <Linear machine on alphabet Rationals^3 with 4-dimensional stateset>
  gap> Transitions(M,[1,0,0,0],[1,0,0]);
  [ [ 0, 1, 0, 0 ], [ 0, 0, 0, 0 ], [ 0, 0, 0, 0 ] ]
  gap> A := AsVectorElement(Rationals,GuptaSidkiGroup.2);
  <Linear element on alphabet Rationals^3 with 4-dimensional stateset>
  gap> Transitions(A,[1,0,0]);
  [ [ 0, 1, 0, 0 ], [ 0, 0, 0, 0 ], [ 0, 0, 0, 0 ] ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{NestedMatrixState}}
\logpage{[ 6, 1, 5 ]}\nobreak
\hyperdef{L}{X80F694298399E78D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NestedMatrixState({\slshape e, i, j})\index{NestedMatrixState@\texttt{NestedMatrixState}}
\label{NestedMatrixState}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NestedMatrixCoefficient({\slshape e, i, j})\index{NestedMatrixCoefficient@\texttt{NestedMatrixCoefficient}}
\label{NestedMatrixCoefficient}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A coefficent of an iterated decomposition of \mbox{\texttt{\slshape e}}.



 The first form returns the entry at position $(i,j)$ of \mbox{\texttt{\slshape e}}'s decomposition. Both of \mbox{\texttt{\slshape i,j}} are lists. The second form returns the output of the state. 

 In particular, \texttt{NestedMatrixState(e,[],[])=e}, and \texttt{Activity(e,1)[i][j]=NestedMatrixCoefficient(e,[i],[j])}, and \texttt{DecompositionOfFRElement(e,1)[i][j]=NestedMatrixState(e,[i],[j])}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> A := AsVectorElement(Rationals,GuptaSidkiGroup.2);;
  gap> A=NestedMatrixState(A,[3,3],[3,3]);
  true
  gap> IsOne(NestedMatrixState(A,[3,3,3,3,1,1],[3,3,3,3,1,2]));
  true
  gap> List([1..3],i->List([1..3],j->NestedMatrixCoefficient(A,[i],[j])))=Activity(A,1);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ActivitySparse}}
\logpage{[ 6, 1, 6 ]}\nobreak
\hyperdef{L}{X7FCEE3BF86B02CC6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ActivitySparse({\slshape m, i})\index{ActivitySparse@\texttt{ActivitySparse}}
\label{ActivitySparse}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A sparse matrix.



 \texttt{Activity(m,i)} returns an $n^i\times n^i$ matrix describing the action on the $i$-fold tensor power of the alphabet. This matrix can also be returned as a
sparse matrix, and this is performed by this command. A sparse matrix is
described as a list of expressions of the form \texttt{[[i,j],c]}, representing the elementary matrix with entry $c$ at position $(i,j)$. The activity matrix is then the sum of these elementary matrices. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> A := AsVectorElement(Rationals,GuptaSidkiGroup.2);;
  gap> Display(Activity(A,2));
  [ [  0,  1,  0,  0,  0,  0,  0,  0,  0 ],
    [  0,  0,  1,  0,  0,  0,  0,  0,  0 ],
    [  1,  0,  0,  0,  0,  0,  0,  0,  0 ],
    [  0,  0,  0,  0,  0,  1,  0,  0,  0 ],
    [  0,  0,  0,  1,  0,  0,  0,  0,  0 ],
    [  0,  0,  0,  0,  1,  0,  0,  0,  0 ],
    [  0,  0,  0,  0,  0,  0,  1,  0,  0 ],
    [  0,  0,  0,  0,  0,  0,  0,  1,  0 ],
    [  0,  0,  0,  0,  0,  0,  0,  0,  1 ] ]
  gap> ActivitySparse(A,2);
  [ [ [ 1, 2 ], 1 ], [ [ 2, 3 ], 1 ], [ [ 3, 1 ], 1 ], [ [ 4, 6 ], 1 ],
  [ [ 5, 4 ], 1 ], [ [ 6, 5 ], 1 ], [ [ 7, 7 ], 1 ], [ [ 8, 8 ], 1 ],
  [ [ 9, 9 ], 1 ] ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Activities}}
\logpage{[ 6, 1, 7 ]}\nobreak
\hyperdef{L}{X8436BEA67F1C3C27}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Activities({\slshape m, i})\index{Activities@\texttt{Activities}}
\label{Activities}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
Activities of \mbox{\texttt{\slshape m}} on the first \mbox{\texttt{\slshape i}} levels.



 \texttt{Activity(m,i)} returns an $n^i\times n^i$ matrix describing the action on the $i$-fold tensor power of the alphabet. This command returns \texttt{List([0..i-1],j-{\textgreater}Activity(m,j))}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> A := AsVectorElement(Rationals,GrigorchukGroup.2);;
  gap> Activities(A,3);
  [ [ [ 1 ] ],
    [ [ 1, 0 ], [ 0, 1 ] ],
    [ [ 0, 1, 0, 0 ], [ 1, 0, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 0, 0, 1 ] ] ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsConvergent}}
\logpage{[ 6, 1, 8 ]}\nobreak
\hyperdef{L}{X7EF5B7417AE6B3F8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsConvergent({\slshape e})\index{IsConvergent@\texttt{IsConvergent}}
\label{IsConvergent}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
Whether the linear element \mbox{\texttt{\slshape e}} is convergent.



 A linear element is \emph{convergent} if its state at position $(1,1)$ is equal to itself. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := 3;;
  gap> shift := VectorElement(CyclotomicField(n), [[[[1,0],[0,0]],
       [[0,0],[0,1]]],[[[0,1],[0,0]],[[1,0],[0,0]]]],[1,E(n)],[1,0]);
  <Linear element on alphabet CF(3)^2 with 2-dimensional stateset>
  gap> IsConvergent(shift);
  true
  gap> Display(Activity(shift,2));
  [ [     1,     0,     0,     0 ],
    [  E(3),     1,     0,     0 ],
    [     0,  E(3),     1,     0 ],
    [     0,     0,  E(3),     1 ] ]
  gap> Display(Activity(shift,3));
  [ [     1,     0,     0,     0,     0,     0,     0,     0 ],
    [  E(3),     1,     0,     0,     0,     0,     0,     0 ],
    [     0,  E(3),     1,     0,     0,     0,     0,     0 ],
    [     0,     0,  E(3),     1,     0,     0,     0,     0 ],
    [     0,     0,     0,  E(3),     1,     0,     0,     0 ],
    [     0,     0,     0,     0,  E(3),     1,     0,     0 ],
    [     0,     0,     0,     0,     0,  E(3),     1,     0 ],
    [     0,     0,     0,     0,     0,     0,  E(3),     1 ] ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{TransposedFRElement}}
\logpage{[ 6, 1, 9 ]}\nobreak
\hyperdef{L}{X8136C21885019A4A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TransposedFRElement({\slshape e})\index{TransposedFRElement@\texttt{TransposedFRElement}}
\label{TransposedFRElement}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsSymmetricFRElement({\slshape e})\index{IsSymmetricFRElement@\texttt{IsSymmetricFRElement}}
\label{IsSymmetricFRElement}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsAntisymmetricFRElement({\slshape e})\index{IsAntisymmetricFRElement@\texttt{IsAntisymmetricFRElement}}
\label{IsAntisymmetricFRElement}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsLowerTriangularFRElement({\slshape e})\index{IsLowerTriangularFRElement@\texttt{IsLowerTriangularFRElement}}
\label{IsLowerTriangularFRElement}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsUpperTriangularFRElement({\slshape e})\index{IsUpperTriangularFRElement@\texttt{IsUpperTriangularFRElement}}
\label{IsUpperTriangularFRElement}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsDiagonalFRElement({\slshape e})\index{IsDiagonalFRElement@\texttt{IsDiagonalFRElement}}
\label{IsDiagonalFRElement}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
The elementary matrix operation/property.



 Since linear FR elements may be interpreted as infinite matrices, it makes
sense to transpose them, test whether they're symmetric, antisymmetric,
diagonal, or triangular. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := 3;;
  gap> shift := VectorElement(CyclotomicField(n), [[[[1,0],[0,0]],
       [[0,0],[0,1]]],[[[0,1],[0,0]],[[1,0],[0,0]]]],[1,E(n)],[1,0]);
  <Linear element on alphabet CF(3)^2 with 2-dimensional stateset>
  gap> Display(Activity(shift,2));
  [ [     1,     0,     0,     0 ],
    [  E(3),     1,     0,     0 ],
    [     0,  E(3),     1,     0 ],
    [     0,     0,  E(3),     1 ] ]
  gap> Display(Activity(TransposedFRElement(shift),2));
  [ [     1,  E(3),     0,     0 ],
    [     0,     1,  E(3),     0 ],
    [     0,     0,     1,  E(3) ],
    [     0,     0,     0,     1 ] ]
  gap> IsSymmetricFRElement(shift);
  false
  gap> IsSymmetricFRElement(shift+TransposedFRElement(shift));
  true
  gap> IsLowerTriangularFRElement(shift);
  true
  gap> IsUpperTriangularFRElement(shift);
  false
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{LDUDecompositionFRElement}}
\logpage{[ 6, 1, 10 ]}\nobreak
\hyperdef{L}{X796B736286CACF85}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LDUDecompositionFRElement({\slshape e})\index{LDUDecompositionFRElement@\texttt{LDUDecompositionFRElement}}
\label{LDUDecompositionFRElement}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A factorization $e=LDU$.



 Given a linear element \mbox{\texttt{\slshape e}}, this command attempts to find a decomposition of the form $e=LDU$, where $L$ is lower triangular, $D$ is diagonal, and $U$ is upper triangular (see \texttt{IsLowerTriangularFRElement} (\ref{IsLowerTriangularFRElement}) etc.). 

 The result is returned thas a list with entries $L,D,U$. Note that it is not guaranteed to succeed. For more examples, see Section \ref{bacher}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> List([0..7],s->List([0..7],t->E(4)^ValuationInt(Binomial(s+t,s),2)));;
  gap> A := GuessVectorElement(last);
  <Linear element on alphabet GaussianRationals^2 with 2-dimensional stateset>
  gap> LDU := LDUDecompositionFRElement(A);
  [ <Linear element on alphabet GaussianRationals^2 with 4-dimensional stateset>,
    <Linear element on alphabet GaussianRationals^2 with 3-dimensional stateset>,
    <Linear element on alphabet GaussianRationals^2 with 4-dimensional stateset> ]
  gap> IsLowerTriangularFRElement(LDU[1]); IsDiagonalFRElement(LDU[2]);
  true
  true
  gap> TransposedFRElement(LDU[1])=LDU[3];
  true
  gap> Product(LDU)=A;
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{GuessVectorElement}}
\logpage{[ 6, 1, 11 ]}\nobreak
\hyperdef{L}{X783E8F427A23EAD1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GuessVectorElement({\slshape m})\index{GuessVectorElement@\texttt{GuessVectorElement}}
\label{GuessVectorElement}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
A vector element that acts like \mbox{\texttt{\slshape m}}.



 The arguments to this function include a matrix or list of matrices, and an
optional ring. The return value is a vector element, over the ring if it was
specified, that acts like the sequence of matrices. 

 If a single matrix is specified, then it is assumed to represent a convergent
element (see \texttt{IsConvergent} (\ref{IsConvergent})). 

 This function returns \texttt{fail} if it believes that it does not have enough information to make a reasonable
guess. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := 3;;
  gap> shift := VectorElement(CyclotomicField(n), [[[[1,0],[0,0]],
       [[0,0],[0,1]]],[[[0,1],[0,0]],,[[1,0],[0,0]]]],[1,E(n)],[1,0]);;
  <Linear element on alphabet CF(3)^2 with 2-dimensional stateset>
  gap> GuessVectorElement(Activity(shift,3)); last=shift;
  <Linear element on alphabet CF(3)^2 with 2-dimensional stateset>
  true
  gap> GuessVectorElement(Inverse(Activity(shift,4)));
  fail
  gap> GuessVectorElement(Inverse(Activity(shift,5)));
  <Linear element on alphabet CF(3)^2 with 4-dimensional stateset>
  gap> IsOne(last*shift);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AsLinearMachine}}
\logpage{[ 6, 1, 12 ]}\nobreak
\hyperdef{L}{X865EE2E887ECC079}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsLinearMachine({\slshape r, m})\index{AsLinearMachine@\texttt{AsLinearMachine}}
\label{AsLinearMachine}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsLinearElement({\slshape r, m})\index{AsLinearElement@\texttt{AsLinearElement}}
\label{AsLinearElement}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The linear machine/element associated with \mbox{\texttt{\slshape m}}.



 This command accepts a domain and an ordinary machine/element, and constructs
the corresponding linear machine/element, defined by extending linearly the
action on $[1..d]$ to an action on $r^d$. 

 If \mbox{\texttt{\slshape m}} is a Mealy machine/element, the result is a vector machine/element. If \mbox{\texttt{\slshape m}} is a group/monoid/semigroup machine/element, the result is an algebra
machine/element. To obtain explicitly a vector or algebra machine/element, see \texttt{AsVectorMachine} (\ref{AsVectorMachine}) and \texttt{AsAlgebraMachine} (\ref{AsAlgebraMachine}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Display(I4Machine);
     |  1     2
  ---+-----+-----+
   a | c,2   c,1
   b | a,1   b,1
   c | c,1   c,2
  ---+-----+-----+
  gap> A := AsLinearMachine(Rationals,I4Machine);
  <Linear machine on alphabet Rationals^2 with 3-dimensional stateset>
  Correspondence(A);
  [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ]
  gap> Display(A);
   Rationals |   1   |   2   |
  -----------+-------+-------+
           1 | 0 0 0 | 0 0 1 |
             | 1 0 0 | 0 0 0 |
             | 0 0 1 | 0 0 0 |
  -----------+-------+-------+
           2 | 0 0 1 | 0 0 0 |
             | 0 1 0 | 0 0 0 |
             | 0 0 0 | 0 0 1 |
  -----------+-------+-------+
  Output: 1 1 1
  gap> B := AsLinearMachine(Rationals,AsMonoidFRMachine(I4Machine));
  <Linear machine on alphabet Rationals^2 with generators [ (1)*m1, (1)*m2 ]>
  gap> Correspondence(B);
  MappingByFunction( <free monoid on the generators [ m1, m2 ]>,
  <algebra-with-one over Rationals, with 2 generators>, function( w ) ... end )
  gap> Display(B);
   Rationals | 1  | 2  |
  -----------+----+----+
           1 |  0 |  1 |
             | m1 |  0 |
  -----------+----+----+
           2 |  1 |  0 |
             | m2 |  0 |
  -----------+----+----+
  Output: 1 1
  gap> AsLinearElement(Rationals,I4Monoid.1)*AsLinearElement(Rationals,I4Monoid.2);
  <Linear element on alphabet Rationals^2 with 4-dimensional stateset>
  gap> last=AsLinearElement(Rationals,I4Monoid.1*I4Monoid.2);
  true  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AsVectorMachine}}
\logpage{[ 6, 1, 13 ]}\nobreak
\hyperdef{L}{X82586DFB8458EF05}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsVectorMachine({\slshape r, m})\index{AsVectorMachine@\texttt{AsVectorMachine}}
\label{AsVectorMachine}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsVectorElement({\slshape r, m})\index{AsVectorElement@\texttt{AsVectorElement}}
\label{AsVectorElement}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The vector machine/element associated with \mbox{\texttt{\slshape m}}.



 This command accepts a domain and an ordinary machine/element, and constructs
the corresponding linear machine/element, defined by extending linearly the
action on $[1..d]$ to an action on $r^d$. For this command to succeed, the machine/element \mbox{\texttt{\slshape m}} must be finite state. For examples see \texttt{AsLinearMachine} (\ref{AsLinearMachine}). }

 

\subsection{\textcolor{Chapter }{AsAlgebraMachine}}
\logpage{[ 6, 1, 14 ]}\nobreak
\hyperdef{L}{X7818245A7DABB311}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsAlgebraMachine({\slshape r, m})\index{AsAlgebraMachine@\texttt{AsAlgebraMachine}}
\label{AsAlgebraMachine}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsAlgebraElement({\slshape r, m})\index{AsAlgebraElement@\texttt{AsAlgebraElement}}
\label{AsAlgebraElement}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The algebra machine/element associated with \mbox{\texttt{\slshape m}}.



 This command accepts a domain and an ordinary machine/element, and constructs
the corresponding linear machine/element, defined by extending linearly the
action on $[1..d]$ to an action on $r^d$. For examples see \texttt{AsLinearMachine} (\ref{AsLinearMachine}). }

 

\subsection{\textcolor{Chapter }{AsVectorMachine (Linear machine)}}
\logpage{[ 6, 1, 15 ]}\nobreak
\hyperdef{L}{X7BDD40B27F7541B2}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsVectorMachine({\slshape m})\index{AsVectorMachine@\texttt{AsVectorMachine}!Linear machine}
\label{AsVectorMachine:Linear machine}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsVectorElement({\slshape m})\index{AsVectorElement@\texttt{AsVectorElement}!Linear machine}
\label{AsVectorElement:Linear machine}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The machine/element \mbox{\texttt{\slshape m}} in vector form.



 This command accepts a linear machine, and converts it to vector form. This
command is not guaranteed to terminate. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> A := AsLinearElement(Rationals,I4Monoid.1);
  <Linear element on alphabet Rationals^2 with 2-dimensional stateset>
  gap> B := AsAlgebraElement(A);
  <Rationals^2|(1)*x.1>
  gap> C := AsVectorElement(B);
  gap> A=B; B=C;
  true
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AsAlgebraMachine (Linear machine)}}
\logpage{[ 6, 1, 16 ]}\nobreak
\hyperdef{L}{X8120605981DDE434}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsAlgebraMachine({\slshape m})\index{AsAlgebraMachine@\texttt{AsAlgebraMachine}!Linear machine}
\label{AsAlgebraMachine:Linear machine}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsAlgebraElement({\slshape m})\index{AsAlgebraElement@\texttt{AsAlgebraElement}!Linear machine}
\label{AsAlgebraElement:Linear machine}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The machine/element \mbox{\texttt{\slshape m}} in algebra form.



 This command accepts a linear machine, and converts it to algebra form. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> A := AsLinearElement(Rationals,I4Monoid.1);
  <Linear element on alphabet Rationals^2 with 2-dimensional stateset>
  gap> AsAlgebraElement(A)=AsAlgebraElement(Rationals,I4Monoid.1);
  true
  gap> A=AsAlgebraElement(A);
  true
\end{Verbatim}
 }

 }

 }

 
\chapter{\textcolor{Chapter }{Self-similar groups, monoids and semigroups}}\label{group}
\logpage{[ 7, 0, 0 ]}
\hyperdef{L}{X86C0E6F083DCCDC8}{}
{
 Self-similar groups, monoids and semigroups (below \emph{FR semigroups}) are simply groups, monoids and semigroups whose elements are FR machines.
They naturally act on the alphabet of their elements, and on sequences over
that alphabet. 

 Most non-trivial calculations in FR groups are performed as follows: \textsf{GAP} searches through words of short length in the generating set of a FR group to
find a solution to a group-theoretic question, and at the same time searches
through the finite quotients to prove the inexistence of a solution. Usually
the calculation ends with the answer \texttt{maybe}, which means that no definite answer, neither positive nor negative, could be
found; however, the cases where the calculation actually terminates have been
most useful. 

 The maximal length of words to consider in the search is controlled by the
variable \texttt{FR{\textunderscore}SEARCH.radius} (initially 10), and the maximal depth of the tree in which to search is
controlled by the variable \texttt{FR{\textunderscore}SEARCH.depth} (initially 6). These limits can be modified in any function call using \textsf{GAP}'s options mechanism, e.g. in \texttt{Index(G,H:FRdepth:=5,FRradius:=5)}. 
\section{\textcolor{Chapter }{Creators for FR semigroups}}\logpage{[ 7, 1, 0 ]}
\hyperdef{L}{X80A26BAA7B53C1BD}{}
{
 The most straightforward creation method for FR groups is \texttt{Group()}, applied with FR elements as arguments. There are shortcuts to this somewhat
tedious method: 

\subsection{\textcolor{Chapter }{FRGroup}}
\logpage{[ 7, 1, 1 ]}\nobreak
\hyperdef{L}{X7AE8F92383272329}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRGroup({\slshape \texttt{\symbol{123}}definition, \texttt{\symbol{125}}})\index{FRGroup@\texttt{FRGroup}}
\label{FRGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRMonoid({\slshape \texttt{\symbol{123}}definition, \texttt{\symbol{125}}})\index{FRMonoid@\texttt{FRMonoid}}
\label{FRMonoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRSemigroup({\slshape \texttt{\symbol{123}}definition, \texttt{\symbol{125}}})\index{FRSemigroup@\texttt{FRSemigroup}}
\label{FRSemigroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new self-similar group/monoid/semigroup.



 This function constructs a new FR group/monoid/semigroup, generated by group
FR elements. It receives as argument any number of strings, each of which
represents a generator of the object to be constructed. 

 Each \mbox{\texttt{\slshape definition}} is of the form \texttt{"name=projtrans"}, where each of \texttt{proj} and \texttt{trans} is optional. \texttt{proj} is of the form \texttt{{\textless}w1,...,wd{\textgreater}}, where each \texttt{wi} is a (possibly empty) word in the \texttt{name}s or is 1. \texttt{trans} is either a permutation in disjoint cycle notation, or a list, representing
the images of a permutation. 

 The option \texttt{IsMealyElement}, passed e.g. as in \texttt{FRGroup("a=(1,2)":IsMealyElement)}, asks for the resulting group to be generated by Mealy elements. The
generators must of course be finite-state. Their names ("a",...) are not
remembered in the constructing group (but can be set using \texttt{SetName} (\textbf{Reference: SetName})). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> FRGroup("a=(1,2)","b=(1,2,3,4,5)"); Size(last);
  <self-similar group over [ 1 .. 5 ] with 2 generators>
  120
  gap> Dinfinity := FRGroup("a=(1,2)","b=<a,b>");
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> AssignGeneratorVariables(Dinfinity);
  #I  Assigned the global variables [ a, b ]
  gap> Order(a); Order(b); Order(a*b);
  2
  2
  infinity
  gap> ZZ := FRGroup("t=<,t>[2,1]");
  <self-similar group over [ 1 .. 2 ] with 1 generator>
  tau := FRElement([[[b,1],[1]]],[()],[1]);
  <2|f3>
  gap> IsSubgroup(Dinfinity,ZZ);
  false
  gap> IsSubgroup(Dinfinity^tau,ZZ);
  true
  gap> Index(Dinfinity^tau,ZZ);
  2
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> i4 := FRMonoid("s=(1,2)","f=<s,f>[1,1]");
  <self-similar monoid over [ 1 .. 2 ] with 2 generators>
  gap> f := GeneratorsOfMonoid(i4){[1,2]};;
  gap> for i in [1..10] do Add(f,f[i]*f[i+1]); od;
  gap> f[1]^2=One(m);
  true
  gap> f[2]^3=f[2];
  true
  gap> f[11]*f[10]^2=f[1]*Product(f{[5,7..11]})*f[10];
  true
  gap> f[12]*f[11]^2=f[2]*Product(f{[6,8..12]})*f[11];
  true
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> i2 := FRSemigroup("f0=<f0,f0>(1,2)","f1=<f1,f0>[2,2]");
  <self-similar semigroup over [ 1 .. 2 ] with 2 generators>
  gap> AssignGeneratorVariables(i2);
  #I  Assigned the global variables [ "f0", "f1" ]
  gap> f0^2=One(i2);
  true
  gap> ForAll([0..10],p->(f0*f1)^p*(f1*f0)^p*f1=f1^2*(f0*f1)^p*(f1*f0)^p*f1);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{SCGroup}}
\logpage{[ 7, 1, 2 ]}\nobreak
\hyperdef{L}{X853E3F0680C76F56}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCGroup({\slshape m})\index{SCGroup@\texttt{SCGroup}}
\label{SCGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCGroupNC({\slshape m})\index{SCGroupNC@\texttt{SCGroupNC}}
\label{SCGroupNC}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCMonoid({\slshape m})\index{SCMonoid@\texttt{SCMonoid}}
\label{SCMonoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCMonoidNC({\slshape m})\index{SCMonoidNC@\texttt{SCMonoidNC}}
\label{SCMonoidNC}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCSemigroup({\slshape m})\index{SCSemigroup@\texttt{SCSemigroup}}
\label{SCSemigroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCSemigroupNC({\slshape m})\index{SCSemigroupNC@\texttt{SCSemigroupNC}}
\label{SCSemigroupNC}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The state-closed group/monoid/semigroup generated by the machine \mbox{\texttt{\slshape m}}.



 This function constructs a new FR group/monoid/semigroup \texttt{g}, generated by all the states of the FR machine \mbox{\texttt{\slshape m}}. There is a bijective correspondence between \texttt{GeneratorsOfFRMachine(m)} and the generators of \texttt{g}, which is accessible via \texttt{Correspondence(g)} (See \texttt{Correspondence} (\ref{Correspondence:FR semigroup})); it is a homomorphism from the stateset of \mbox{\texttt{\slshape m}} to \texttt{g}, or a list indicating for each state of \mbox{\texttt{\slshape m}} a corresponding generator index in the generators of \texttt{g} (with negatives for inverses, and 0 for identity). 

 In the non-\texttt{NC} forms, redundant (equal, trivial or mutually inverse) states are removed from
the generating set of \texttt{g}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> b := MealyMachine([[3,2],[3,1],[3,3]],[(1,2),(),()]);; g := SCGroupNC(b);
  <self-similar group over [ 1 .. 2 ] with 3 generators>
  gap> Size(g);
  infinity
  gap> IsOne(Comm(g.2,g.2^g.1));
  true
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> i4machine := MealyMachine([[3,3],[1,2],[3,3]],[(1,2),[1,1],()]);
  <Mealy machine on alphabet [ 1, 2 ] with 3 states>
  gap> IsInvertible(i4machine);
  false
  gap> i4 := SCMonoidNC(i4machine);
  <self-similar monoid over [ 1 .. 2 ] with 3 generators>
  gap> f := GeneratorsOfMonoid(i4){[1,2]};;
  gap> for i in [1..10] do Add(f,f[i]*f[i+1]); od;
  gap> f[1]^2=One(m);
  true
  gap> f[2]^3=f[2];
  true
  gap> f[11]*f[10]^2=f[1]*Product(f{[5,7..11]})*f[10];
  true
  gap> f[12]*f[11]^2=f[2]*Product(f{[6,8..12]})*f[11];
  true
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> i2machine := MealyMachine([[1,1],[2,1]],[(1,2),[2,2]]);
  <Mealy machine on alphabet [ 1, 2 ] with 2 states>
  gap> i2 := SCSemigroupNC(i2machine);
  <self-similar semigroup over [ 1 .. 2 ] with 2 generators>
  gap> f0 := GeneratorsOfSemigroup(i2)[1];; f1 := GeneratorsOfSemigroup(i2)[2];;
  gap> f0^2=One(i2);
  true
  gap> ForAll([0..10],p->(f0*f1)^p*(f1*f0)^p*f1=f1^2*(f0*f1)^p*(f1*f0)^p*f1);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Correspondence (FR semigroup)}}
\logpage{[ 7, 1, 3 ]}\nobreak
\hyperdef{L}{X7F15D57A7959FEF6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Correspondence({\slshape g})\index{Correspondence@\texttt{Correspondence}!FR semigroup}
\label{Correspondence:FR semigroup}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
A correspondence between the generators of the underlying FR machine of \mbox{\texttt{\slshape g}} and \mbox{\texttt{\slshape g}}.



 If \mbox{\texttt{\slshape g}} was created as the state closure of an FR machine \texttt{m}, this attribute records the correspondence between \texttt{m} and \mbox{\texttt{\slshape g}}. 

 If \texttt{m} is a group/monoid/semigroup/algebra FR machine, then \texttt{Correspondence(g)} is a homomorphism from the stateset of \texttt{m} to \mbox{\texttt{\slshape g}}. 

 If \texttt{m} is a Mealy or vector machine, then \texttt{Correspondence(g)} is a list, with in position $i$ the index in the generating set of \mbox{\texttt{\slshape g}} of state number $i$. This index is 0 if there is no corresponding generator because the state is
trivial, and is negative if there is no corresponding generator because the
inverse of state number $i$ is a generator. 

 See \texttt{SCGroupNC} (\ref{SCGroupNC}), \texttt{SCGroup} (\ref{SCGroup}), \texttt{SCMonoidNC} (\ref{SCMonoidNC}), \texttt{SCMonoid} (\ref{SCMonoid}), \texttt{SCSemigroupNC} (\ref{SCSemigroupNC}), \texttt{SCSemigroup} (\ref{SCSemigroup}), \texttt{SCAlgebraNC} (\ref{SCAlgebraNC}), \texttt{SCAlgebra} (\ref{SCAlgebra}), \texttt{SCAlgebraWithOneNC} (\ref{SCAlgebraWithOneNC}), and \texttt{SCAlgebraWithOne} (\ref{SCAlgebraWithOne}) for examples. }

 

\subsection{\textcolor{Chapter }{FullSCGroup}}
\logpage{[ 7, 1, 4 ]}\nobreak
\hyperdef{L}{X7D0B8334786E2802}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FullSCGroup({\slshape ...})\index{FullSCGroup@\texttt{FullSCGroup}}
\label{FullSCGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FullSCMonoid({\slshape ...})\index{FullSCMonoid@\texttt{FullSCMonoid}}
\label{FullSCMonoid}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FullSCSemigroup({\slshape ...})\index{FullSCSemigroup@\texttt{FullSCSemigroup}}
\label{FullSCSemigroup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
A maximal state-closed group/monoid/semigroup on the alphabet \mbox{\texttt{\slshape a}}.



 This function constructs a new FR group, monoid or semigroup, which contains
all transformations with given properties of the tree with given alphabet. 

 The arguments can be, in any order: a semigroup, specifying which vertex
actions are allowed; a set or domain, specifying the alphabet of the tree; an
integer, specifying the maximal depth of elements; and a filter among \texttt{IsFinitaryFRElement} (\ref{IsFinitaryFRElement}), \texttt{IsBoundedFRElement} (\ref{IsBoundedFRElement}), \texttt{IsPolynomialGrowthFRElement} (\ref{IsPolynomialGrowthFRElement}) and \texttt{IsFiniteStateFRElement} (\ref{IsFiniteStateFRElement}). 

 This object serves as a container for all FR elements with alphabet \mbox{\texttt{\slshape a}}. Random elements can be drawn from it; they are Mealy elements with a random
number of states, and with the required properties. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> g := FullSCGroup([1..3]);
  FullSCGroup([ 1 .. 3 ]);
  gap> IsSubgroup(g,GuptaSidkiGroup);
  true
  gap> g := FullSCGroup([1..3],Group((1,2,3)));
  FullSCGroup([ 1 .. 3 ], Group( [ (1,2,3) ] ))
  gap> IsSubgroup(g,GuptaSidkiGroup);
  true
  gap> IsSubgroup(g,GrigorchukGroup);
  false
  gap> Random(g);
  <Mealy element on alphabet [ 1, 2, 3 ] with 2 states, initial state 1>
  gap> Size(FullSCGroup([1,2],3));
  128
  gap> g := FullSCMonoid([1..2]);
  FullSCMonoid([ 1 .. 2 ])
  gap> IsSubset(g,AsTrans(FullSCGroup([1..2])));
  true
  gap> IsSubset(g,AsTrans(GrigorchukGroup));
  true
  gap> g := FullSCSemigroup([1..3]);
  FullSCSemigroup([ 1 .. 3 ])
  gap> h := FullSCSemigroup([1..3],Semigroup(Trans([1,1,1])));
  FullSCSemigroup([ 1 .. 3 ], Semigroup( [ Trans( [ 1, 1, 1 ] ) ] ))
  gap> Size(h);
  1
  gap> IsSubset(g,h);
  true
  gap> g=FullSCMonoid([1..3]);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{FRMachineFRGroup}}
\logpage{[ 7, 1, 5 ]}\nobreak
\hyperdef{L}{X7DB92C34827D513F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRMachineFRGroup({\slshape g})\index{FRMachineFRGroup@\texttt{FRMachineFRGroup}}
\label{FRMachineFRGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRMachineFRMonoid({\slshape g})\index{FRMachineFRMonoid@\texttt{FRMachineFRMonoid}}
\label{FRMachineFRMonoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRMachineFRSemigroup({\slshape g})\index{FRMachineFRSemigroup@\texttt{FRMachineFRSemigroup}}
\label{FRMachineFRSemigroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MealyMachineFRGroup({\slshape g})\index{MealyMachineFRGroup@\texttt{MealyMachineFRGroup}}
\label{MealyMachineFRGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MealyMachineFRMonoid({\slshape g})\index{MealyMachineFRMonoid@\texttt{MealyMachineFRMonoid}}
\label{MealyMachineFRMonoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MealyMachineFRSemigroup({\slshape g})\index{MealyMachineFRSemigroup@\texttt{MealyMachineFRSemigroup}}
\label{MealyMachineFRSemigroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A machine describing all generators of \mbox{\texttt{\slshape g}}.



 This function constructs a new group/monoid/semigroup/Mealy FR machine, with
(at least) one generator per generator of \mbox{\texttt{\slshape g}}. This is done by adding all machines of all generators of \mbox{\texttt{\slshape g}}, and minimizing. 

 In particular, if \mbox{\texttt{\slshape g}} is state-closed, then \texttt{SCGroup(FRMachineFRGroup(g))} gives a group isomorphic to \mbox{\texttt{\slshape g}}, and similarly for monoids and semigroups. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> FRMachineFRGroup(GuptaSidkiGroup);
  <FR machine with alphabet [ 1 .. 3 ] on Group( [ f11, f12 ] )>
  gap> Display(last);
   G   |     1          2        3
  -----+--------+----------+--------+
   f11 | <id>,2     <id>,3   <id>,1
   f12 |  f11,1   f11^-1,2    f12,3
  -----+--------+----------+--------+
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> FRMachineFRMonoid(I4Monoid);
  <FR machine with alphabet [ 1 .. 2 ] on Monoid( [ m11, m12 ], ... )>
  gap> Display(last);
   M   |     1        2
  -----+--------+--------+
   m11 | <id>,2   <id>,1
   m12 |  m11,1    m12,1
  -----+--------+--------+
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> FRMachineFRSemigroup(I2Monoid);
  <FR machine with alphabet [ 1 .. 2 ] on Semigroup( [ s11, s12, s1 ] )>
  gap> Display(last);
   S   |    1       2
  -----+-------+-------+
   s11 | s11,1   s11,2
   s12 | s12,2   s12,1
    s1 |  s1,2   s12,2
  -----+-------+-------+
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsomorphismFRGroup}}
\logpage{[ 7, 1, 6 ]}\nobreak
\hyperdef{L}{X7BF4AC9F830A8E1A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismFRGroup({\slshape g})\index{IsomorphismFRGroup@\texttt{IsomorphismFRGroup}}
\label{IsomorphismFRGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismFRMonoid({\slshape g})\index{IsomorphismFRMonoid@\texttt{IsomorphismFRMonoid}}
\label{IsomorphismFRMonoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismFRSemigroup({\slshape g})\index{IsomorphismFRSemigroup@\texttt{IsomorphismFRSemigroup}}
\label{IsomorphismFRSemigroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
An isomorphism towards a group/monoid/semigroup on a single FR machine.



 This function constructs a new FR group/monoid/semigroup, such that all
elements of the resulting object have the same underlying
group/monoid/semigroup FR machine. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> phi := IsomorphismFRGroup(GuptaSidkiGroup);
  [ <Mealy element on alphabet [ 1, 2, 3 ] with 2 states, initial state 1>,
    <Mealy element on alphabet [ 1, 2, 3 ] with 4 states, initial state 1> ] ->
  [ <3|identity ...>, <3|f1>, <3|f1^-1>, <3|f2> ]
  gap> Display(GuptaSidkiGroup.2);
     |  1     2     3
  ---+-----+-----+-----+
   a | a,1   a,2   a,3
   b | a,2   a,3   a,1
   c | a,3   a,1   a,2
   d | b,1   c,2   d,3
  ---+-----+-----+-----+
  Initial state: d
  gap> Display(GuptaSidkiGroup.2^phi);
      |     1         2        3
  ----+--------+---------+--------+
   f1 | <id>,2    <id>,3   <id>,1
   f2 |   f1,1   f1^-1,2     f2,3
  ----+--------+---------+--------+
  Initial state: f2
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> phi := IsomorphismFRSemigroup(I2Monoid);
  MappingByFunction( I2, <self-similar semigroup over [ 1 .. 2 ] with
  3 generators>, <Operation "AsSemigroupFRElement"> )
  gap> Display(GeneratorsOfSemigroup(I2Monoid)[3]);
     |  1     2
  ---+-----+-----+
   a | a,2   b,2
   b | b,2   b,1
  ---+-----+-----+
  Initial state: a
  gap> Display(GeneratorsOfSemigroup(I2Monoid)[3]^phi);
   S  |   1      2
  ----+------+------+
   s1 | s1,2   s2,2
   s2 | s2,2   s2,1
  ----+------+------+
  Initial state: s1
\end{Verbatim}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> phi := IsomorphismFRMonoid(I4Monoid);
  MappingByFunction( I4, <self-similar monoid over [ 1 .. 2 ] with
  2 generators>, <Operation "AsMonoidFRElement"> )
  gap> Display(GeneratorsOfMonoid(I4Monoid)[1]);
     |  1     2
  ---+-----+-----+
   a | b,2   b,1
   b | b,1   b,2
  ---+-----+-----+
  Initial state: a
  gap> Display(GeneratorsOfMonoid(I4Monoid)[1]^phi);
   M  |     1        2
  ----+--------+--------+
   m1 | <id>,2   <id>,1
  ----+--------+--------+
  Initial state: m1
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsomorphismMealyGroup}}
\logpage{[ 7, 1, 7 ]}\nobreak
\hyperdef{L}{X7DE1CAE981F2825B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismMealyGroup({\slshape g})\index{IsomorphismMealyGroup@\texttt{IsomorphismMealyGroup}}
\label{IsomorphismMealyGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismMealyMonoid({\slshape g})\index{IsomorphismMealyMonoid@\texttt{IsomorphismMealyMonoid}}
\label{IsomorphismMealyMonoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismMealySemigroup({\slshape g})\index{IsomorphismMealySemigroup@\texttt{IsomorphismMealySemigroup}}
\label{IsomorphismMealySemigroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
An isomorphism towards a group/monoid/semigroup all of whose elements are
Mealy machines.



 This function constructs a new FR group/monoid/semigroup, such that all
elements of the resulting object are Mealy machines. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> G := FRGroup("a=(1,2)","b=<a,b>","c=<c,b>");
  <self-similar group over [ 1 .. 2 ] with 3 generators>
  gap> phi := IsomorphismMealyGroup(G);
  [ <2|a>, <2|b>, <2|c> ] ->
  [ <Mealy element on alphabet [ 1, 2 ] with 2 states, initial state 1>,
    <Mealy element on alphabet [ 1, 2 ] with 3 states, initial state 1>,
    <Mealy element on alphabet [ 1, 2 ] with 4 states, initial state 1> ]
  gap> Display(G.3);
     |     1        2
  ---+--------+--------+
   a | <id>,2   <id>,1
   b |    a,1      b,2
   c |    c,1      b,2
  ---+--------+--------+
  Initial state: c
  gap> Display(G.3^phi);
     |  1     2
  ---+-----+-----+
   a | a,1   b,2
   b | c,1   b,2
   c | d,2   d,1
   d | d,1   d,2
  ---+-----+-----+
  Initial state: a
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{FRGroupByVirtualEndomorphism}}
\logpage{[ 7, 1, 8 ]}\nobreak
\hyperdef{L}{X7BB8DDEA83946C73}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRGroupByVirtualEndomorphism({\slshape hom[, transversal]})\index{FRGroupByVirtualEndomorphism@\texttt{FRGroupByVirtualEndomorphism}}
\label{FRGroupByVirtualEndomorphism}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new self-similar group.



 This function constructs a new FR group \texttt{P}, generated by group FR elements. Its first argument is a virtual endomorphism
of a group \texttt{G}, i.e. a homomorphism from a subgroup \texttt{H} to \texttt{G}. The constructed FR group acts on a tree with alphabet a transversal of \texttt{H} in \texttt{G} (represented as \texttt{[1..d]}), and is a homomorphic image of \texttt{G}. The stabilizer of the first-level vertex corresponding to the trivial coset
is the image of \texttt{H}. This function is loosely speaking an inverse of \texttt{VirtualEndomorphism} (\ref{VirtualEndomorphism}). 

 The optional second argument is a transversal of \texttt{H} in \texttt{G}, either of type \texttt{IsRightTransversal} or a list. 

 Furthermore, an option "MealyElement" can be passed to the function, as \texttt{FRGroupByVirtualEndomorphism(f:MealyElement)}, to require the resulting group to be generated by Mealy elements and not FR
elements. The call will succeed, of course, only if the representation of \texttt{G} is finite-state. 

 The resulting FR group has an attribute \texttt{Correspondence(P)} that records a homomorphism from \texttt{G} to \texttt{P}. 

 The example below constructs the binary adding machine, and a non-standard
representation of it. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> G := FreeGroup(1);
  <free group on the generators [ f1 ]>
  gap> f := GroupHomomorphismByImages(Group(G.1^2),G,[G.1^2],[G.1]);
  [ f1^2 ] -> [ f1 ]
  gap> H := FRGroupByVirtualEndomorphism(f);
  <self-similar group over [ 1 .. 2 ] with 1 generator>
  gap> Display(H.1);
      |     1      2
  ----+--------+------+
   x1 | <id>,2   x1,1
  ----+--------+------+
  Initial state: x1
  gap> Correspondence(H);
  [ f1 ] -> [ <2|x1> ]
  gap> H := FRGroupByVirtualEndomorphism(f,[G.1^0,G.1^3]);;
  gap> Display(H.1);
      |      1        2
  ----+---------+--------+
   x1 | x1^-1,2   x1^2,1
  ----+---------+--------+
  Initial state: x1
  gap> H := FRGroupByVirtualEndomorphism(f:MealyElement);
  <self-similar group over [ 1 .. 2 ] with 1 generator>
  gap> Display(H.1);
     |  1     2
  ---+-----+-----+
   a | b,2   a,1
   b | b,1   b,2
  ---+-----+-----+
  Initial state: a
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{TreeWreathProduct (FR group)}}
\logpage{[ 7, 1, 9 ]}\nobreak
\hyperdef{L}{X79D75A7D80DD9AD1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TreeWreathProduct({\slshape g, h, x0, y0})\index{TreeWreathProduct@\texttt{TreeWreathProduct}!FR group}
\label{TreeWreathProduct:FR group}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The tree-wreath product of groups \mbox{\texttt{\slshape g,h}}.



 The tree-wreath product of two FR groups is a group generated by a copy of \mbox{\texttt{\slshape g}} and of \mbox{\texttt{\slshape h}}, in such a way that many conjugates of \mbox{\texttt{\slshape g}} commute. 

 More formally, assume without loss of generality that all generators of \mbox{\texttt{\slshape g}} are states of a machine \texttt{m}, and that all generators of \mbox{\texttt{\slshape h}} are states of a machine \texttt{n}. Then the tree-wreath product is generated by the images of generators of \mbox{\texttt{\slshape g,h}} in \texttt{TreeWreathProduct(m,n,x0,y0)}. 

 For the operation on FR machines see \texttt{TreeWreathProduct} (\ref{TreeWreathProduct:FR machine})). It is described (with small variations, and in lesser generality) in \cite{MR2197828}. For example, in 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> w := TreeWreathProduct(AddingGroup(2),AddingGroup(2),1,1);
  <recursive group over [ 1 .. 4 ] with 2 generators>
  gap> a := w.1; b := w.2;
  <Mealy element on alphabet [ 1 .. 4 ] with 3 states>
  <Mealy element on alphabet [ 1 .. 4 ] with 2 states>
  gap> Order(a); Order(b);
  infinity
  infinity
  gap> ForAll([-100..100],i->IsOne(Comm(a,a^(b^i))));
  true
\end{Verbatim}
 the group \texttt{w} is the wreath product $Z\wr Z$. }

 

\subsection{\textcolor{Chapter }{WeaklyBranchedEmbedding}}
\logpage{[ 7, 1, 10 ]}\nobreak
\hyperdef{L}{X85840A047C04BFC6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WeaklyBranchedEmbedding({\slshape g})\index{WeaklyBranchedEmbedding@\texttt{WeaklyBranchedEmbedding}}
\label{WeaklyBranchedEmbedding}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A embedding of \mbox{\texttt{\slshape g}} in a weakly branched group.



 This function constructs a new FR group, on alphabet the square of the
alphabet of \mbox{\texttt{\slshape g}}. It is generated by the canonical copy of \mbox{\texttt{\slshape g}} and by the tree-wreath product of \mbox{\texttt{\slshape g}} with an adding machine on the same alphabet as \mbox{\texttt{\slshape g}} (see \texttt{TreeWreathProduct} (\ref{TreeWreathProduct:FR group})). The function returns a group homomorphism into this new FR group. 

 The main result of \cite{MR1995624} is that the resulting group $h$ is weakly branched. More precisely, $h'$ contains $|X|^2$ copies of itself. \texttt{ gap{\textgreater} f := WeaklyBranchedEmbedding(BabyAleshinGroup);;
gap{\textgreater} Range(f); {\textless}recursive group over [ 1 .. 4 ] with 8
generators{\textgreater} } constructs a finitely generated branched group containing a free subgroup. }

 }

 
\section{\textcolor{Chapter }{Operations for FR semigroups}}\logpage{[ 7, 2, 0 ]}
\hyperdef{L}{X84E20571841DE1E4}{}
{
 

\subsection{\textcolor{Chapter }{PermGroup}}
\logpage{[ 7, 2, 1 ]}\nobreak
\hyperdef{L}{X7C6D7BA0818A3A3D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PermGroup({\slshape g, l})\index{PermGroup@\texttt{PermGroup}}
\label{PermGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{EpimorphismPermGroup({\slshape g, l})\index{EpimorphismPermGroup@\texttt{EpimorphismPermGroup}}
\label{EpimorphismPermGroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
[An epimorphism to] the permutation group of \mbox{\texttt{\slshape g}}'s action on level \mbox{\texttt{\slshape l}}.



 The first function returns a permutation group on $d^l$ points, where $d$ is the size of \mbox{\texttt{\slshape g}}'s alphabet. It has as many generators as \mbox{\texttt{\slshape g}}, and represents the action of \mbox{\texttt{\slshape g}} on the \mbox{\texttt{\slshape l}}th layer of the tree. 

 The second function returns a homomorphism from \mbox{\texttt{\slshape g}} to this permutation group. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> g := FRGroup("a=(1,2)","b=<a,>"); Size(g);
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  8
  gap> PermGroup(g,2);
  Group([ (1,3)(2,4), (1,2) ])
  gap> PermGroup(g,3);
  Group([ (1,5)(2,6)(3,7)(4,8), (1,3)(2,4) ])
  gap> List([1..6],i->LogInt(Size(PermGroup(GrigorchukGroup,i)),2));
  [ 1, 3, 7, 12, 22, 42 ]
  gap> g := FRGroup("t=<,t>(1,2)"); Size(g);
  <self-similar group over [ 1 .. 2 ] with 1 generator>
  infinity
  gap> pi := EpimorphismPermGroup(g,5);
  MappingByFunction( <self-similar group over [ 1 .. 2 ] with 1 generator,
  of size infinity>, Group([ (1,17,9,25,5,21,13,29,3,19,11,27,7,23,15,31,
  2,18,10,26,6,22,14,30,4,20,12,28,8,24,16,32) ]), function( w ) ... end )
  gap> Order(g.1);
  infinity
  gap> Order(g.1^pi);
  32
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{PcGroup}}
\logpage{[ 7, 2, 2 ]}\nobreak
\hyperdef{L}{X8620BEAF7957FA4D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PcGroup({\slshape g, l})\index{PcGroup@\texttt{PcGroup}}
\label{PcGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{EpimorphismPcGroup({\slshape g, l})\index{EpimorphismPcGroup@\texttt{EpimorphismPcGroup}}
\label{EpimorphismPcGroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
[An epimorphism to] the pc group of \mbox{\texttt{\slshape g}}'s action on level \mbox{\texttt{\slshape l}}.



 The first function returns a polycyclic group representing the action of \mbox{\texttt{\slshape g}} on the \mbox{\texttt{\slshape l}}th layer of the tree. It converts the permutation group \texttt{PermGroup(g,l)} to a Pc group, in which computations are often faster. 

 The second function returns a homomorphism from \mbox{\texttt{\slshape g}} to this pc group. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> g := PcGroup(GrigorchukGroup,7); time;
  <pc group with 5 generators>
  3370
  gap> NormalClosure(g,Group(g.3)); time;
  <pc group with 79 generators>
  240
  gap> g := PermGroup(GrigorchukGroup,7); time;
  <permutation group with 5 generators>
  3
  gap> NormalClosure(g,Group(g.3)); time;
  <permutation group with 5 generators>
  5344
  gap> g := FRGroup("t=<,t>(1,2)"); Size(g);
  <self-similar group over [ 1 .. 2 ] with 1 generator>
  infinity
  gap> pi := EpimorphismPcGroup(g,5);
  MappingByFunction( <self-similar group over [ 1 .. 2 ] with
  1 generator, of size infinity>, Group([ f1, f2, f3, f4, f5 ]), function( w ) ... end )
  gap> Order(g.1);
  infinity
  gap> Order(g.1^pi);
  32
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{TransMonoid}}
\logpage{[ 7, 2, 3 ]}\nobreak
\hyperdef{L}{X79B8CFEA79987E12}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TransMonoid({\slshape g, l})\index{TransMonoid@\texttt{TransMonoid}}
\label{TransMonoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{EpimorphismTransnMonoid({\slshape g, l})\index{EpimorphismTransnMonoid@\texttt{EpimorphismTransnMonoid}}
\label{EpimorphismTransnMonoid}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
[An epimorphism to] the transformation monoid of \mbox{\texttt{\slshape g}}'s action on level \mbox{\texttt{\slshape l}}.



 The first function returns a transformation monoid on $d^l$ points, where $d$ is the size of \mbox{\texttt{\slshape g}}'s alphabet. It has as many generators as \mbox{\texttt{\slshape g}}, and represents the action of \mbox{\texttt{\slshape g}} on the \mbox{\texttt{\slshape l}}th layer of the tree. 

 The second function returns a homomorphism from \mbox{\texttt{\slshape g}} to this transformation monoid. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> i4 := SCMonoid(MealyMachine([[3,3],[1,2],[3,3]],[(1,2),[1,1],()]));
  <self-similar monoid over [ 1 .. 2 ] with 3 generators>
  gap> g := TransMonoid(i4,6);
  <monoid with 3 generators>
  gap> List([1..6],i->Size(TransMonoid(i4,i)));
  [ 4, 14, 50, 170, 570, 1882 ]
  gap> Collected(List(g,RankOfTrans));
  [ [ 1, 64 ], [ 2, 1280 ], [ 4, 384 ], [ 8, 112 ], [ 16, 32 ], [ 32, 8 ], [ 64, 2 ] ]
  gap> pi := EpimorphismTransMonoid(i4,9);
  MappingByFunction( <self-similar monoid over [ 1 .. 2 ] with 3 generators>,
  <monoid with 3 generators>, function( w ) ... end )
  gap> f := GeneratorsOfMonoid(i4){[1,2]};;
  gap> for i in [1..10] do Add(f,f[i]*f[i+1]); od;
  gap> Product(f{[3,5,7,9,11]})=f[11]*f[10];
  false
  gap> Product(f{[3,5,7,9,11]})^pi=(f[11]*f[10])^pi;
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{TransSemigroup}}
\logpage{[ 7, 2, 4 ]}\nobreak
\hyperdef{L}{X82BF1F2579A02C5E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TransSemigroup({\slshape g, l})\index{TransSemigroup@\texttt{TransSemigroup}}
\label{TransSemigroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{EpimorphismTransSemigroup({\slshape g, l})\index{EpimorphismTransSemigroup@\texttt{EpimorphismTransSemigroup}}
\label{EpimorphismTransSemigroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
[An epimorphism to] the transformation semigroup of \mbox{\texttt{\slshape g}}'s action on level \mbox{\texttt{\slshape l}}.



 The first function returns a transformation semigroup on $d^l$ points, where $d$ is the size of \mbox{\texttt{\slshape g}}'s alphabet. It has as many generators as \mbox{\texttt{\slshape g}}, and represents the action of \mbox{\texttt{\slshape g}} on the \mbox{\texttt{\slshape l}}th layer of the tree. 

 The second function returns a homomorphism from \mbox{\texttt{\slshape g}} to this transformation semigroup. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> i2 := SCSemigroup(MealyMachine([[1,1],[2,1]],[(1,2),[2,2]]));
  <self-similar semigroup over [ 1 .. 2 ] with 2 generators>
  gap> g := TransSemigroup(i2,6);
  <semigroup with 2 generators>
  gap> List([1..6],i->Size(TransSemigroup(i2,i)));
  [ 4, 14, 42, 114, 290, 706 ]
  gap> Collected(List(g,RankOfTrans));
  [ [ 1, 64 ], [ 2, 384 ], [ 4, 160 ], [ 8, 64 ], [ 16, 24 ], [ 32, 8 ], [ 64, 2 ] ]
  gap> f0 := GeneratorsOfSemigroup(i2)[1];; f1 := GeneratorsOfSemigroup(i2)[2];;
  gap> pi := EpimorphismTransSemigroup(i2,10);
  MappingByFunction( <self-similar semigroup over [ 1 .. 2 ] with
  2 generators>, <semigroup with 2 generators>, function( w ) ... end )
  gap> (f1*(f1*f0)^10)=((f1*f0)^10);
  false
  gap> (f1*(f1*f0)^10)^pi=((f1*f0)^10)^pi;
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{EpimorphismGermGroup}}
\logpage{[ 7, 2, 5 ]}\nobreak
\hyperdef{L}{X7BDC634086437315}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{EpimorphismGermGroup({\slshape g, l})\index{EpimorphismGermGroup@\texttt{EpimorphismGermGroup}}
\label{EpimorphismGermGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{EpimorphismGermGroup({\slshape g})\index{EpimorphismGermGroup@\texttt{EpimorphismGermGroup}!EGG0}
\label{EpimorphismGermGroup:EGG0}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A homomorphism to a polycyclic group.



 This function returns an epimorphism to a polycyclic group, encoding the
action on the first \mbox{\texttt{\slshape l}} levels of the tree and on the germs below. If \mbox{\texttt{\slshape l}} is omitted, it is assumed to be $0$. 

 Since the elements of \mbox{\texttt{\slshape g}} are finite automata, they map periodic sequences to periodic sequences. The
action on the periods, and in the immediate vicinity of them, is called the \emph{germ action} of \mbox{\texttt{\slshape g}}. This function returns the natural homomorphism from \mbox{\texttt{\slshape g}} to the wreath product of this germ group with the quotient of \mbox{\texttt{\slshape g}} acting on the \mbox{\texttt{\slshape l}}th layer of the tree. 

 The germ group, by default, is abelian. If it is finite, this function returns
a homomorphism to a Pc group; otherwise, a homomorphism to a polycyclic group. 

 The \texttt{GrigorchukEvilTwin} (\ref{GrigorchukEvilTwin}) is, for now, the only example with a hand-coded, non-abelian germ group. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> EpimorphismGermGroup(GrigorchukGroup,0);
  MappingByFunction( GrigorchukGroup, <pc group of size 4 with 2 generators>,
    function( g ) ... end )
  gap> List(GeneratorsOfGroup(GrigorchukGroup),x->x^last);
  [ <identity> of ..., f1, f1*f2, f2 ]
  gap> StructureDescription(Image(last2));
  "C2 x C2"
  gap> g := FRGroup("t=<,t>(1,2)","m=<,m^-1>(1,2)");;
  gap> EpimorphismGermGroup(g,0);
  MappingByFunction( <state-closed, bounded group over [ 1, 2 ] with 2
    generators>, Pcp-group with orders [ 0, 0 ], function( x ) ... end )
  gap> EpimorphismGermGroup(g,1);; Range(last); Image(last2);
  Pcp-group with orders [ 2, 0, 0, 0, 0 ]
  Pcp-group with orders [ 2, 0, 0, 0 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{StabilizerImage}}
\logpage{[ 7, 2, 6 ]}\nobreak
\hyperdef{L}{X87378D53791D0B70}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StabilizerImage({\slshape g, v})\index{StabilizerImage@\texttt{StabilizerImage}}
\label{StabilizerImage}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The group of all states at \mbox{\texttt{\slshape v}} of elements of \mbox{\texttt{\slshape g}}.



 This function constructs a new FR group, containing all states at vertex \mbox{\texttt{\slshape v}} (which can be an integer or a list) of elements of \mbox{\texttt{\slshape g}}. 

 The result is \mbox{\texttt{\slshape g}} itself precisely if \mbox{\texttt{\slshape g}} is recurrent (see \texttt{IsRecurrentFRSemigroup} (\ref{IsRecurrentFRSemigroup})). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> G := FRGroup("t=<,t>(1,2)","u=<,u^-1>(1,2)","b=<u,t>");
  <self-similar group over [ 1 .. 2 ] with 3 generators>
  gap> Stabilizer(G,1);
  <self-similar group over [ 1 .. 2 ] with 5 generators>
  gap> GeneratorsOfGroup(last);
  [ <2|u*t^-1>, <2|b>, <2|t^2>, <2|t*u>, <2|t*b*t^-1> ]
  gap> StabilizerImage(G,1);
  <self-similar group over [ 1 .. 2 ] with 5 generators>
  gap> GeneratorsOfGroup(last);
  [ <2|identity ...>, <2|u>, <2|t>, <2|u^-1>, <2|t> ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{LevelStabilizer}}
\logpage{[ 7, 2, 7 ]}\nobreak
\hyperdef{L}{X7B4CD9CA872BA368}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LevelStabilizer({\slshape g, n})\index{LevelStabilizer@\texttt{LevelStabilizer}}
\label{LevelStabilizer}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The fixator of the \mbox{\texttt{\slshape n}}th level of the tree.



 This function constructs the normal subgroup of \mbox{\texttt{\slshape g}} that fixes the \mbox{\texttt{\slshape n}}th level of the tree. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> G := FRGroup("t=<,t>(1,2)","a=(1,2)");
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> LevelStabilizer(G,2);
  <self-similar group over [ 1 .. 2 ] with 9 generators>
  gap> Index(G,last);
  8
  gap> IsNormal(G,last2);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsStateClosedFRSemigroup}}
\logpage{[ 7, 2, 8 ]}\nobreak
\hyperdef{L}{X7F65F07F85034B3B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsStateClosedFRSemigroup({\slshape g})\index{IsStateClosedFRSemigroup@\texttt{IsStateClosedFRSemigroup}}
\label{IsStateClosedFRSemigroup}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if all states of elements of \mbox{\texttt{\slshape g}} belong to \mbox{\texttt{\slshape g}}.



 This function tests whether \mbox{\texttt{\slshape g}} is a \emph{state-closed} group, i.e. a group such that all states of all elements of \mbox{\texttt{\slshape g}} belong to \mbox{\texttt{\slshape g}}. 

 The smallest state-closed group containing \mbox{\texttt{\slshape g}} is computed with \texttt{StateClosure} (\ref{StateClosure}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Dinfinity := FRGroup("a=(1,2)","b=<a,b>");
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> AssignGeneratorVariables(Dinfinity);
  #I  Assigned the global variables [ a, b ]
  gap> IsStateClosedFRSemigroup(Group(a));
       IsStateClosedFRSemigroup(Group(b));
       IsStateClosedFRSemigroup(Dinfinity);
  true
  false
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{StateClosure}}
\logpage{[ 7, 2, 9 ]}\nobreak
\hyperdef{L}{X79246DB482BEAF2D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StateClosure({\slshape g})\index{StateClosure@\texttt{StateClosure}}
\label{StateClosure}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The smallest state-closed group containing \mbox{\texttt{\slshape g}}.



 This function computes the smallest group containing all states of all
elements of \mbox{\texttt{\slshape g}}, i.e. the smallest group containing \mbox{\texttt{\slshape g}} and for which \texttt{IsStateClosedFRSemigroup} (\ref{IsStateClosedFRSemigroup}) returns \texttt{true}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Dinfinity := FRGroup("a=(1,2)","b=<a,b>");
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> AssignGeneratorVariables(Dinfinity);
  #I  Assigned the global variables [ a, b ]
  gap> StateStateClosure(Group(a))=Dinfinity; StateClosure(Group(b))=Dinfinity;
  false
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsRecurrentFRSemigroup}}
\logpage{[ 7, 2, 10 ]}\nobreak
\hyperdef{L}{X7E2F34417EBB7673}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsRecurrentFRSemigroup({\slshape g})\index{IsRecurrentFRSemigroup@\texttt{IsRecurrentFRSemigroup}}
\label{IsRecurrentFRSemigroup}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape g}} is a recurrent group.



 This function returns \texttt{true} if \mbox{\texttt{\slshape g}} is a \emph{recurrent} group, i.e. if, for every vertex \texttt{v}, all elements of \mbox{\texttt{\slshape g}} appear as states at \texttt{v} of elements fixing \texttt{v}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Dinfinity := FRGroup("a=(1,2)","b=<a,b>");
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> AssignGeneratorVariables(Dinfinity);
  #I  Assigned the global variables [ a, b ]
  gap> IsRecurrentFRSemigroup(Group(a)); IsRecurrentFRSemigroup(Group(b));
  false
  false
  gap> IsRecurrentFRSemigroup(Dinfinity);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsLevelTransitive (FR group)}}
\logpage{[ 7, 2, 11 ]}\nobreak
\hyperdef{L}{X7FBF56737D9063F4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsLevelTransitive({\slshape g})\index{IsLevelTransitive@\texttt{IsLevelTransitive}!FR group}
\label{IsLevelTransitive:FR group}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape g}} is a level-transitive group.



 This function returns \texttt{true} if \mbox{\texttt{\slshape g}} is a \emph{level-transitive} group, i.e. if the action of \mbox{\texttt{\slshape g}} is transitive at every level of the tree on which it acts. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Dinfinity := FRGroup("a=(1,2)","b=<a,b>");
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> AssignGeneratorVariables(Dinfinity);
  #I  Assigned the global variables [ a, b ]
  gap> IsLevelTransitive(Group(a)); IsLevelTransitive(Group(b));
       IsLevelTransitive(Dinfinity);
  false
  false
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsInfinitelyTransitive}}
\logpage{[ 7, 2, 12 ]}\nobreak
\hyperdef{L}{X7D95219481AEDD20}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsInfinitelyTransitive({\slshape g})\index{IsInfinitelyTransitive@\texttt{IsInfinitelyTransitive}}
\label{IsInfinitelyTransitive}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape g}} is infinitely transitive.



 This function returns \texttt{true} if \mbox{\texttt{\slshape g}} is an \emph{infinitely transitive} group. This means that \mbox{\texttt{\slshape g}} is the state-closed group of a bireversible Mealy machine (see \texttt{IsBireversible} (\ref{IsBireversible})), that this Mealy machine has an involution on its alphabet (see \texttt{AlphabetInvolution} (\ref{AlphabetInvolution})), and that the action of the set of reduced words of any given length over
the alphabet (where "reduced" means no successive letters related by the
involution) is transitive. 

 This notion is of fundamental importance for the study of lattices in a
product of trees. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> !!!
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsFinitaryFRSemigroup}}
\logpage{[ 7, 2, 13 ]}\nobreak
\hyperdef{L}{X7A6CB30181662C77}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFinitaryFRSemigroup({\slshape g})\index{IsFinitaryFRSemigroup@\texttt{IsFinitaryFRSemigroup}}
\label{IsFinitaryFRSemigroup}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsWeaklyFinitaryFRSemigroup({\slshape g})\index{IsWeaklyFinitaryFRSemigroup@\texttt{IsWeaklyFinitaryFRSemigroup}}
\label{IsWeaklyFinitaryFRSemigroup}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsBoundedFRSemigroup({\slshape g})\index{IsBoundedFRSemigroup@\texttt{IsBoundedFRSemigroup}}
\label{IsBoundedFRSemigroup}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsPolynomialGrowthFRSemigroup({\slshape g})\index{IsPolynomialGrowthFRSemigroup@\texttt{IsPolynomialGrowthFRSemigroup}}
\label{IsPolynomialGrowthFRSemigroup}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFiniteStateFRSemigroup({\slshape g})\index{IsFiniteStateFRSemigroup@\texttt{IsFiniteStateFRSemigroup}}
\label{IsFiniteStateFRSemigroup}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if all elements of \mbox{\texttt{\slshape g}} have the required property.



 This function returns \texttt{true} if all elements of \mbox{\texttt{\slshape g}} have the required property, as FR elements; see \texttt{IsFinitaryFRElement} (\ref{IsFinitaryFRElement}), \texttt{IsWeaklyFinitaryFRElement} (\ref{IsWeaklyFinitaryFRElement}), \texttt{IsBoundedFRElement} (\ref{IsBoundedFRElement}), \texttt{IsPolynomialGrowthFRElement} (\ref{IsPolynomialGrowthFRElement}) and \texttt{IsFiniteStateFRElement} (\ref{IsFiniteStateFRElement}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> G := FRGroup("a=(1,2)","b=<a,b>","c=<c,b>","d=<d,d>(1,2)");
  <self-similar group over [ 1 .. 2 ] with 4 generators>
  gap> L := [Group(G.1),Group(G.1,G.2),Group(G.1,G.2,G.3),G];;
  gap> List(L,IsFinitaryFRSemigroup);
  [ true, false, false, false ]
  gap> List(L,IsBoundedFRSemigroup);
  [ true, true, false, false ]
  gap> List(L,IsPolynomialGrowthFRSemigroup);
  [ true, true, true, false ]
  gap> List(L,IsFiniteStateFRSemigroup);
  [ true, true, true, true ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Degree (FR semigroup)}}
\logpage{[ 7, 2, 14 ]}\nobreak
\hyperdef{L}{X791BCD9D782C6237}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Degree({\slshape g})\index{Degree@\texttt{Degree}!FR semigroup}
\label{Degree:FR semigroup}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DegreeOfFRSemigroup({\slshape g})\index{DegreeOfFRSemigroup@\texttt{DegreeOfFRSemigroup}}
\label{DegreeOfFRSemigroup}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Depth({\slshape g})\index{Depth@\texttt{Depth}!FR semigroup}
\label{Depth:FR semigroup}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DepthOfFRSemigroup({\slshape g})\index{DepthOfFRSemigroup@\texttt{DepthOfFRSemigroup}}
\label{DepthOfFRSemigroup}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
The maximal degree/depth of elements of \mbox{\texttt{\slshape g}}.



 This function returns the maximal degree/depth of elements of \mbox{\texttt{\slshape g}}; see \texttt{Degree} (\ref{Degree:FR element}) and \texttt{Depth} (\ref{Depth:FR element}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> G := FRGroup("a=(1,2)","b=<a,b>","c=<c,b>");
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> Degree(Group(G.1)); Degree(Group(G.1,G.2)); Degree(G);
  0
  1
  2
  gap> Depth(Group(G.1)); Depth(Group(G.1,G.2)); Depth(G);
  1
  infinity
  infinity
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{HasOpenSetConditionFRSemigroup}}
\logpage{[ 7, 2, 15 ]}\nobreak
\hyperdef{L}{X7FA67E4387C91BD8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{HasOpenSetConditionFRSemigroup({\slshape e})\index{HasOpenSetConditionFRSemigroup@\texttt{HasOpenSetConditionFRSemigroup}}
\label{HasOpenSetConditionFRSemigroup}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape g}} has the open set condition.



 This function returns \texttt{true} if all elements of \mbox{\texttt{\slshape g}} have the \emph{open set condition}, see \texttt{HasOpenSetConditionFRElement} (\ref{HasOpenSetConditionFRElement}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> HasOpenSetConditionFRSemigroup(GrigorchukGroup);
  false
  gap> HasOpenSetConditionFRSemigroup(BinaryAddingGroup);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsContracting}}
\logpage{[ 7, 2, 16 ]}\nobreak
\hyperdef{L}{X7EAB4B5B843C0EC5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsContracting({\slshape g})\index{IsContracting@\texttt{IsContracting}}
\label{IsContracting}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape g}} is a contracting semigroup.



 This function returns \texttt{true} if \mbox{\texttt{\slshape g}} is a \emph{contracting} semigroup, i.e. if there exists a finite subset \texttt{n} of \mbox{\texttt{\slshape g}} such that the \texttt{LimitStates} (\ref{LimitStates}) of every element of \mbox{\texttt{\slshape g}} belong to \mbox{\texttt{\slshape n}}. 

 The minimal such \texttt{n} can be computed with \texttt{NucleusOfFRSemigroup} (\ref{NucleusOfFRSemigroup}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Dinfinity := FRGroup("a=(1,2)","b=<a,b>");
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> IsContracting(Dinfinity);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{NucleusOfFRSemigroup}}
\logpage{[ 7, 2, 17 ]}\nobreak
\hyperdef{L}{X7CA062A67C1554BB}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NucleusOfFRSemigroup({\slshape g})\index{NucleusOfFRSemigroup@\texttt{NucleusOfFRSemigroup}}
\label{NucleusOfFRSemigroup}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
The nucleus of the contracting semigroup \mbox{\texttt{\slshape g}}.



 This function returns the \emph{nucleus} of the contracting semigroup \mbox{\texttt{\slshape g}}, i.e. the smallest subset \texttt{n} of \mbox{\texttt{\slshape g}} such that the \texttt{LimitStates} (\ref{LimitStates}) of every element of \mbox{\texttt{\slshape g}} belong to \texttt{n}. 

 This function returns \texttt{fail} if no such \texttt{n} exists. Usually, it loops forever without being able to decide whether \texttt{n} is finite or infinite. It succeeds precisely when \texttt{IsContracting(g)} succeeds. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Dinfinity := FRGroup("a=(1,2)","b=<a,b>");
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> NucleusOfFRSemigroup(Dinfinity);
  [ <2|identity ...>, <2|b>, <2|a> ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{NucleusMachine (FR semigroup)}}
\logpage{[ 7, 2, 18 ]}\nobreak
\hyperdef{L}{X8443D711796F06E4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NucleusMachine({\slshape g})\index{NucleusMachine@\texttt{NucleusMachine}!FR semigroup}
\label{NucleusMachine:FR semigroup}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
The nucleus machine of the contracting semigroup \mbox{\texttt{\slshape g}}.



 This function returns the \emph{nucleus} of the contracting semigroup \mbox{\texttt{\slshape g}}, see \texttt{NucleusOfFRSemigroup} (\ref{NucleusOfFRSemigroup}), in the form of a Mealy machine. 

 Since all states of the nucleus are elements of the nucleus, the transition
and output function may be restricted to the nucleus, defining a Mealy
machine. Finitely generated recurrent groups are generated by their nucleus
machine. 

 This function returns \texttt{fail} if no such \texttt{n} exists. Usually, it loops forever without being able to decide whether \texttt{n} is finite or infinite. It succeeds precisely when \texttt{IsContracting(g)} succeeds. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Dinfinity := FRGroup("a=(1,2)","b=<a,b>");
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> M := NucleusMachine(Dinfinity);
  <Mealy machine on alphabet [ 1, 2 ] with 3 states>
  gap> Display(M);
     |  1     2
  ---+-----+-----+
   a | a,1   a,2
   b | c,1   b,2
   c | a,2   a,1
  ---+-----+-----+
  gap> Dinfinity=SCGroup(M);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{BranchingSubgroup}}
\logpage{[ 7, 2, 19 ]}\nobreak
\hyperdef{L}{X7A874A107D4944E1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BranchingSubgroup({\slshape g})\index{BranchingSubgroup@\texttt{BranchingSubgroup}}
\label{BranchingSubgroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A branching subgroup of \mbox{\texttt{\slshape g}}.



 This function searches for a subgroup $k$ of \mbox{\texttt{\slshape g}}, such that $k$ contains $k \times \cdots \times k$. 

 It searches for elements in larger and larger balls in \mbox{\texttt{\slshape g}}, calling \texttt{FindBranchingSubgroup} (\ref{FindBranchingSubgroup}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> K := BranchingSubgroup(GrigorchukGroup);
  <self-similar group over [ 1 .. 2 ] with 9 generators>
  gap> IsBranchingSubgroup(K);
  true
  gap> IsBranched(GrigorchukGroup);
  true
  gap> Index(GrigorchukGroup,K);
  16
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{FindBranchingSubgroup}}
\logpage{[ 7, 2, 20 ]}\nobreak
\hyperdef{L}{X78ADACCD8586D3C7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindBranchingSubgroup({\slshape g, l, r})\index{FindBranchingSubgroup@\texttt{FindBranchingSubgroup}}
\label{FindBranchingSubgroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A branching subgroup of \mbox{\texttt{\slshape g}}.



 This function searches for a subgroup $k$ of \mbox{\texttt{\slshape g}}, such that $k$ contains $k \times \cdots \times k$. 

 The second argument \mbox{\texttt{\slshape l}} specifies the level at which branching must occur; i.e. asks to search for a
subgroup $k$ such that \mbox{\texttt{\slshape g}} contains $k^{d^l}$ where $d$ is the size of the alphabet. If \texttt{l=infinity}, the resulting $k$ will be a regularly branched subgroup. 

 The third argument \mbox{\texttt{\slshape r}} specifies the radius to explore in \mbox{\texttt{\slshape g}} and all branching subgroups at levels smaller than \mbox{\texttt{\slshape l}} for elements with all level-1 states trivial except one. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> FindBranchingSubgroup(GrigorchukGroup,1,4);
  <self-similar group over [ 1 .. 2 ] with 8 generators>
  gap> Index(GrigorchukGroup,last);
  8
  gap> FindBranchingSubgroup(GrigorchukGroup,2,4);
  <self-similar group over [ 1 .. 2 ] with 6 generators>
  gap> Index(GrigorchukGroup,last);
  16
  gap> FindBranchingSubgroup(GrigorchukGroup,3,4);
  <self-similar group over [ 1 .. 2 ] with 9 generators>
  gap> Index(GrigorchukGroup,last);
  16
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsBranched (FR group)}}
\logpage{[ 7, 2, 21 ]}\nobreak
\hyperdef{L}{X832D98E47ACA099C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsBranched({\slshape g})\index{IsBranched@\texttt{IsBranched}!FR group}
\label{IsBranched:FR group}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape g}} has a finite-index branching subgroup.



 This function returns \texttt{true} if \mbox{\texttt{\slshape g}} has a finite-index subgroup $k$, such that $k$ contains $k \times \cdots \times k$. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  <Example><![CDATA[
  gap> K := BranchingSubgroup(GrigorchukGroup);
  <self-similar group over [ 1 .. 2 ] with 9 generators>
  gap> IsBranchingSubgroup(K);
  true
  gap> IsBranched(GrigorchukGroup);
  true
  gap> Index(GrigorchukGroup,K);
  16
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsBranchingSubgroup (FR semigroup)}}
\logpage{[ 7, 2, 22 ]}\nobreak
\hyperdef{L}{X7A905CE87B49213F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsBranchingSubgroup({\slshape k})\index{IsBranchingSubgroup@\texttt{IsBranchingSubgroup}!FR semigroup}
\label{IsBranchingSubgroup:FR semigroup}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape k}} is a branching subgroup.



 This function returns \texttt{true} if \mbox{\texttt{\slshape k}} contains $k \times \cdots \times k$. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> K := BranchingSubgroup(GrigorchukGroup);
  <self-similar group over [ 1 .. 2 ] with 9 generators>
  gap> IsBranchingSubgroup(K);
  true
  gap> IsBranched(GrigorchukGroup);
  true
  gap> Index(GrigorchukGroup,K);
  16
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{TopVertexTransformations}}
\logpage{[ 7, 2, 23 ]}\nobreak
\hyperdef{L}{X8749E0797A99F531}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TopVertexTransformations({\slshape g})\index{TopVertexTransformations@\texttt{TopVertexTransformations}}
\label{TopVertexTransformations}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
The transformations at the root under the action of \mbox{\texttt{\slshape g}}.



 This function returns the permutation group, or the transformation
group/semigroup/monoid, of all activities of all elements under the root
vertex of the tree on which \mbox{\texttt{\slshape g}} acts. 

 It is a synonym for \texttt{PermGroup(g,1)} or \texttt{TransMonoid(g,1)} or \texttt{TransSemigroup(g,1)}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> TopVertexTransformations(GrigorchukGroup);
  Group([ (), (1,2) ])
  gap> IsTransitive(last,AlphabetOfFRSemigroup(GrigorchukGroup));
  true
  gap> TopVertexTransformations(FullSCMonoid([1..3]));
  <monoid with 3 generators>
  gap> Size(last);
  27
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{VertexTransformations (FR semigroup)}}
\logpage{[ 7, 2, 24 ]}\nobreak
\hyperdef{L}{X7C56C90086070A2E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{VertexTransformations({\slshape g})\index{VertexTransformations@\texttt{VertexTransformations}!FR semigroup}
\label{VertexTransformations:FR semigroup}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
The transformations at all vertices under the action of \mbox{\texttt{\slshape g}}.



 This function returns the permutation group, or the transformation
group/monoid/semigroup, of all activities of all elements under all vertices
of the tree on which \mbox{\texttt{\slshape g}} acts. 

 This is the smallest group/monoid/semigroup \texttt{P} such that \mbox{\texttt{\slshape g}} is a subset of \texttt{FullSCGroup(AlphabetOfFRSemigroup(g),P)} or \texttt{FullSCMonoid(AlphabetOfFRSemigroup(g),P)} or \texttt{FullSCSemigroup(AlphabetOfFRSemigroup(g),P)}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> VertexTransformations(GuptaSidkiGroup);
  Group([ (), (1,2,3), (1,3,2) ])
  gap> TopVertexTransformations(Group(GuptaSidkiGroup.2));
  Group(())
  gap> VertexTransformations(Group(GuptaSidkiGroup.2));
  Group([ (), (1,2,3), (1,3,2) ])
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{VirtualEndomorphism}}
\logpage{[ 7, 2, 25 ]}\nobreak
\hyperdef{L}{X7DF2D9838625CDED}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{VirtualEndomorphism({\slshape g, v})\index{VirtualEndomorphism@\texttt{VirtualEndomorphism}}
\label{VirtualEndomorphism}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The virtual endomorphism at vertex \mbox{\texttt{\slshape v}}.



 This function returns the homomorphism from \texttt{Stabilizer(g,v)} to \mbox{\texttt{\slshape g}}, defined by computing the state at \mbox{\texttt{\slshape v}}. It is loosely speaking an inverse of \texttt{FRGroupByVirtualEndomorphism} (\ref{FRGroupByVirtualEndomorphism}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> A := SCGroup(MealyMachine([[2,1],[2,2]],[(1,2),()]));
  <self-similar group over [ 1 .. 2 ] with 1 generator>
  gap> f := VirtualEndomorphism(A,1);
  MappingByFunction( <self-similar group over [ 1 .. 2 ] with
  1 generator>, <self-similar group over [ 1 .. 2 ] with
  1 generator>, function( g ) ... end )
  gap> ((A.1)^2)^f=A.1;
  true
  gap> B := FRGroupByVirtualEndomorphism(f);
  <self-similar group over [ 1 .. 2 ] with 1 generator>
  gap> A=B;
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{EpimorphismFromFpGroup}}
\logpage{[ 7, 2, 26 ]}\nobreak
\hyperdef{L}{X7C81CB1C7F0D7A90}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{EpimorphismFromFpGroup({\slshape g, l})\index{EpimorphismFromFpGroup@\texttt{EpimorphismFromFpGroup}}
\label{EpimorphismFromFpGroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
An epimorphism from a finitely presented group to \mbox{\texttt{\slshape g}}.



 For some examples of self-similar groups, a recursive presentation of the
group is coded into \textsf{FR}, and an approximate presentation is returned by this command, together with a
map onto the group \mbox{\texttt{\slshape g}}. The argument \mbox{\texttt{\slshape l}} roughly means the number of iterates of an endomorphism were applied to a
finite set of relators. An isomorphic group would be obtained by setting \texttt{l=infinity}; for that purpose, see \texttt{IsomorphismSubgroupFpGroup} (\ref{IsomorphismSubgroupFpGroup}). 

 Preimages can be computed, with \texttt{PreImagesRepresentative}. They are usually reasonably short words, though by no means guaranteed to be
of minimal length. 

 Currently this command is implemented through an ad hoc method for \texttt{BinaryKneadingGroup} (\ref{BinaryKneadingGroup}), \texttt{GrigorchukGroup} (\ref{GrigorchukGroup}) and \texttt{GrigorchukOverGroup} (\ref{GrigorchukOverGroup}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> f := EpimorphismFromFpGroup(GrigorchukGroup,1);
  MappingByFunction( <fp group on the generators
  [ a, b, c, d ]>, GrigorchukGroup, function( w ) ... end )
  4 gap> RelatorsOfFpGroup(Source(f));
  [ a^2, b^2, c^2, d^2, b*c*d, a*d*a*d*a*d*a*d, a^-1*c*a*c*a^-1*c*a*c*a^-1*c*a*c*a^
      -1*c*a*c, a^-1*c^-1*a*b*a^-1*c*a*b*a^-1*c^-1*a*b*a^-1*c*a*b*a^-1*c^-1*a*b*a^-1*
      c*a*b*a^-1*c^-1*a*b*a^-1*c*a*b, a*d*a*c*a*c*a*d*a*c*a*c*a*d*a*c*a*c*a*d*a*c*a*c,
    a^-1*c*a*c*a^-1*c*a*b*a^-1*c*a*b*a^-1*c*a*c*a^-1*c*a*b*a^-1*c*a*b*a^-1*c*a*c*a^
      -1*c*a*b*a^-1*c*a*b*a^-1*c*a*c*a^-1*c*a*b*a^-1*c*a*b ]
  gap> PreImagesRepresentative(f,Comm(GrigorchukGroup.1,GrigorchukGroup.2));
  a*c*a*d*a*d*a*c
  gap> Source(f).4^f=GrigorchukGroup.4;
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsomorphismSubgroupFpGroup}}
\logpage{[ 7, 2, 27 ]}\nobreak
\hyperdef{L}{X8740656382656D63}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismSubgroupFpGroup({\slshape g})\index{IsomorphismSubgroupFpGroup@\texttt{IsomorphismSubgroupFpGroup}}
\label{IsomorphismSubgroupFpGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsSubgroupFpGroup({\slshape g})\index{AsSubgroupFpGroup@\texttt{AsSubgroupFpGroup}}
\label{AsSubgroupFpGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismLpGroup({\slshape g})\index{IsomorphismLpGroup@\texttt{IsomorphismLpGroup}}
\label{IsomorphismLpGroup}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsLpGroup({\slshape g})\index{AsLpGroup@\texttt{AsLpGroup}}
\label{AsLpGroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
An isomorphism to a subgroup of a finitely presented group, or an L-presented
group.



 For some examples of self-similar groups, a recursive presentation of the
group is coded into \textsf{FR}, and is returned by this command. The group \mbox{\texttt{\slshape g}} itself sits as a subgroup of a finitely presented group. To obtain a finitely
presented group approximating \mbox{\texttt{\slshape g}}, see \texttt{EpimorphismFromFpGroup} (\ref{EpimorphismFromFpGroup}). PreImages can also be computed; it is usually better to use \texttt{PreImageElm}, since the word problem may not be solvable by \textsf{GAP} in the f.p. group. 

 Currently this command is implemented through an ad hoc method for \texttt{BinaryKneadingGroup} (\ref{BinaryKneadingGroup}), \texttt{GrigorchukGroup} (\ref{GrigorchukGroup}), \texttt{GrigorchukOverGroup} (\ref{GrigorchukOverGroup}), generalized \texttt{GuptaSidkiGroups} (\ref{GuptaSidkiGroups}) and generalized \texttt{FabrykowskiGuptaGroups} (\ref{FabrykowskiGuptaGroups}). 

 The second form returns an isomorphism to an L-presented group (see \cite{MR2009317} and \cite{eick-hartung}. It requires the package \textsf{NQL}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> f := IsomorphismSubgroupFpGroup(BasilicaGroup);
  MappingByFunction( BasilicaGroup, Group([ a^-1, a*t^-1*a^-1*t*a^-1
   ]), function( g ) ... end, function( w ) ... end )
  gap> Range(f);
  Group([ a^-1, a*t^-1*a^-1*t*a^-1 ])
  gap> c := Comm(BasilicaGroup.1,BasilicaGroup.2);
  <Mealy element on alphabet [ 1, 2 ] with 9 states, initial state 1>
  gap> c^f;
  t^-2*a*t^-1*a*t*a^-2*t*a*t^-2*a*t^-1*a*t*a^-1*t*a*t^-1*a*t^-2*
  a^-1*t*a*t^-1*a*t^-1*a^-1*t*a^-1*t^5*a*t^-1*a^-1*t*a^-1
  gap> PreImageElm(f,last);
  <Mealy element on alphabet [ 1, 2 ] with 9 states, initial state 1>
  gap> last=c;
  true
\end{Verbatim}
 }

 }

 
\section{\textcolor{Chapter }{Properties for infinite groups}}\logpage{[ 7, 3, 0 ]}
\hyperdef{L}{X7E8485A081EBB3AA}{}
{
 

\subsection{\textcolor{Chapter }{IsTorsionGroup}}
\logpage{[ 7, 3, 1 ]}\nobreak
\hyperdef{L}{X840ED7D279ECAB7F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsTorsionGroup({\slshape g})\index{IsTorsionGroup@\texttt{IsTorsionGroup}}
\label{IsTorsionGroup}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape g}} is a torsion group.



 This function returns \texttt{true} if \mbox{\texttt{\slshape g}} is a torsion group, i.e. if every element in \mbox{\texttt{\slshape g}} has finite order; and \texttt{false} if \mbox{\texttt{\slshape g}} contains an element of infinite order. 

 This method is quite rudimentary, and is not guaranteed to terminate. At the
minimum, \mbox{\texttt{\slshape g}} should be a group in which \texttt{Order()} succeeds in computing element orders; e.g. a bounded group in Mealy machine
format. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Dinfinity := FRGroup("a=(1,2)","b=<a,b>":IsMealyElement);
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> IsTorsionGroup(Dinfinity);
  false
  gap> IsTorsionGroup(GrigorchukGroup); IsTorsionGroup(GuptaSidkiGroup);
  true
  true
  gap> IsTorsionGroup(FabrykowskiGuptaGroup);
  false
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsTorsionFreeGroup}}
\logpage{[ 7, 3, 2 ]}\nobreak
\hyperdef{L}{X7914F2D68077F503}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsTorsionFreeGroup({\slshape g})\index{IsTorsionFreeGroup@\texttt{IsTorsionFreeGroup}}
\label{IsTorsionFreeGroup}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape g}} is a torsion-free group.



 This function returns \texttt{true} if \mbox{\texttt{\slshape g}} is a torsion-free group, i.e. if no element in \mbox{\texttt{\slshape g}} has finite order; and \texttt{false} if \mbox{\texttt{\slshape g}} contains an element of finite order. 

 This method is quite rudimentary, and is not guaranteed to terminate. At the
minimum, \mbox{\texttt{\slshape g}} should be a group in which \texttt{Order()} succeeds in computing element orders; e.g. a bounded group in Mealy machine
format. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Dinfinity := FRGroup("a=(1,2)","b=<a,b>":IsMealyElement);
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> IsTorsionFreeGroup(Dinfinity);
  false
  gap> IsTorsionFreeGroup(BasilicaGroup);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsAmenableGroup}}
\logpage{[ 7, 3, 3 ]}\nobreak
\hyperdef{L}{X87E93FFC820ED40E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsAmenableGroup({\slshape g})\index{IsAmenableGroup@\texttt{IsAmenableGroup}}
\label{IsAmenableGroup}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape g}} is an amenable group.



 Amenable groups, introduced by von Neumann \cite{vneumann}, are those groups that admit a finitely additive, translation-invariant
measure. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> IsAmenableGroup(FreeGroup(2));
  false
  gap> IsAmenableGroup(BasilicaGroup);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsVirtuallySimpleGroup}}
\logpage{[ 7, 3, 4 ]}\nobreak
\hyperdef{L}{X873C0A7C8422C0C9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsVirtuallySimpleGroup({\slshape g})\index{IsVirtuallySimpleGroup@\texttt{IsVirtuallySimpleGroup}}
\label{IsVirtuallySimpleGroup}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape g}} admits a finite-index simple subgroup.



 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsResiduallyFinite}}
\logpage{[ 7, 3, 5 ]}\nobreak
\hyperdef{L}{X79A3A0CF82B6F089}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsResiduallyFinite({\slshape obj})\index{IsResiduallyFinite@\texttt{IsResiduallyFinite}}
\label{IsResiduallyFinite}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is residually finite.



 A object is \emph{residually finite} if it can be approximated arbitrarily well by finite quotients; i.e. if for
every $g\neq h\in X$ there exists a finite quotient $\pi:X\to Q$ such that $g^\pi\neq h^\pi$. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> IsResiduallyFinite(FreeGroup(2));
  true
  gap> IsResiduallyFinite(BasilicaGroup);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsSQUniversal}}
\logpage{[ 7, 3, 6 ]}\nobreak
\hyperdef{L}{X86E1182E7EEFAADB}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsSQUniversal({\slshape obj})\index{IsSQUniversal@\texttt{IsSQUniversal}}
\label{IsSQUniversal}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is SQ-universal.



 An object \mbox{\texttt{\slshape obj}} is \emph{SQ-universal} if every countable object of the same category as \mbox{\texttt{\slshape obj}} is a subobject of a quotient of \mbox{\texttt{\slshape obj}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> IsSQUniversal(FreeGroup(2));
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsJustInfinite}}
\logpage{[ 7, 3, 7 ]}\nobreak
\hyperdef{L}{X7FDAEAFF78A5E7D2}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsJustInfinite({\slshape obj})\index{IsJustInfinite@\texttt{IsJustInfinite}}
\label{IsJustInfinite}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is just-infinite.



 An object \mbox{\texttt{\slshape obj}} is \emph{just-infinite} if \mbox{\texttt{\slshape obj}} is infinite, but every quotient of \mbox{\texttt{\slshape obj}} is finite. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> IsJustInfinite(FreeGroup(2));
  false
  gap> IsJustInfinite(FreeGroup(1));
  true
  gap> IsJustInfinite(GrigorchukGroup); time
  true
  8284
\end{Verbatim}
 }

 }

 }

 
\chapter{\textcolor{Chapter }{Algebras}}\label{algebras}
\logpage{[ 8, 0, 0 ]}
\hyperdef{L}{X7DDBF6F47A2E021C}{}
{
 Self-similar algebras and algebras with one (below \emph{FR algebras}) are simply algebras [with one] whose elements are linear FR machines. They
naturally act on the alphabet of their elements, which is a vector space. 

 Elements may be added, subtracted and multiplied. They can be vector or
algebra linear elements; the vector elements are in general preferable, for
efficiency reasons. 

 Finite-dimensional approximations of self-similar algebras can be computed;
they are given as matrix algebras. 
\section{\textcolor{Chapter }{Creators for FR algebras}}\logpage{[ 8, 1, 0 ]}
\hyperdef{L}{X842EE9427C63F92E}{}
{
 The most straightforward creation method for FR algebras is \texttt{Algebra()}, applied with linear FR elements as arguments. There are shortcuts to this
somewhat tedious method: 

\subsection{\textcolor{Chapter }{FRAlgebra}}
\logpage{[ 8, 1, 1 ]}\nobreak
\hyperdef{L}{X812FEA6778152E49}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRAlgebra({\slshape ring, \texttt{\symbol{123}}definition, \texttt{\symbol{125}}})\index{FRAlgebra@\texttt{FRAlgebra}}
\label{FRAlgebra}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRAlgebraWithOne({\slshape ring, \texttt{\symbol{123}}definition, \texttt{\symbol{125}}})\index{FRAlgebraWithOne@\texttt{FRAlgebraWithOne}}
\label{FRAlgebraWithOne}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A new self-similar algebra [with one].



 This function constructs a new FR algebra [with one], generated by linear FR
elements. It receives as argument any number of strings, each of which
represents a generator of the object to be constructed. 

 \mbox{\texttt{\slshape ring}} is the acting domain of the vector space on which the algebra will act. 

 Each \mbox{\texttt{\slshape definition}} is of the form \texttt{"name=[[...],...,[...]]"} or of the form \texttt{"name=[[...],...,[...]]:out"}, namely a matrix whose entries are algebraic expressions in the \texttt{names}, possibly using \texttt{0,1}, optionally followed by a scalar. The matrix entries specify the
decomposition of the element being defined, and the optional scalar specifies
the output of that element, by default assumed to be one. 

 The option \texttt{IsVectorElement}, passed e.g. as in \texttt{FRAlgebra(Rationals,"a=[[a,1],[a,0]]":IsVectorElement)}, asks for the resulting algebra to be generated by vector elements. The
generators must of course be finite-state. Their names ("a",...) are not
remembered in the constructing algebra (but can be set using \texttt{SetName} (\textbf{Reference: SetName})). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := FRAlgebra(Rationals,"a=[[1,a],[a,0]]");
  <self-similar algebra on alphabet Rationals^2 with 1 generator>
  gap> Display(Activity(m.1,2));
  [ [  1,  0,  1,  1 ],
    [  0,  1,  1,  0 ],
    [  1,  1,  0,  0 ],
    [  1,  0,  0,  0 ] ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{SCAlgebra}}
\logpage{[ 8, 1, 2 ]}\nobreak
\hyperdef{L}{X844B890F7BF56236}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCAlgebra({\slshape m})\index{SCAlgebra@\texttt{SCAlgebra}}
\label{SCAlgebra}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCAlgebraWithOne({\slshape m})\index{SCAlgebraWithOne@\texttt{SCAlgebraWithOne}}
\label{SCAlgebraWithOne}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCAlgebraNC({\slshape m})\index{SCAlgebraNC@\texttt{SCAlgebraNC}}
\label{SCAlgebraNC}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SCAlgebraWithOneNC({\slshape m})\index{SCAlgebraWithOneNC@\texttt{SCAlgebraWithOneNC}}
\label{SCAlgebraWithOneNC}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The state-closed algebra [with one] generated by the machine \mbox{\texttt{\slshape m}}.



 This function constructs a new FR algebra [vith one] \texttt{a}, generated by all the states of the FR machine \mbox{\texttt{\slshape m}}. There is a bijective correspondence between \texttt{GeneratorsOfFRMachine(m)} and the generators of \texttt{a}, which is accessible via \texttt{Correspondence(a)} (See \texttt{Correspondence} (\ref{Correspondence:FR semigroup})); it is a homomorphism from the stateset of \mbox{\texttt{\slshape m}} to \texttt{a}, or a list indicating for each state of \mbox{\texttt{\slshape m}} a corresponding generator index in the generators of \texttt{a} (with 0 for identity). 

 In the non-\texttt{NC} forms, redundant (equal, zero or one) states are removed from the generating
set of \texttt{a}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> a := SCAlgebra(AsLinearMachine(Rationals,I4Machine));
  <self-similar algebra on alphabet Rationals^2 with 3 generators>
  gap> a.1 = AsLinearElement(Rationals,I4Monoid.1);
  true
\end{Verbatim}
 }

 }

 
\section{\textcolor{Chapter }{Operations for FR algebras}}\logpage{[ 8, 2, 0 ]}
\hyperdef{L}{X7EFB4F2E7E908B9F}{}
{
 

\subsection{\textcolor{Chapter }{MatrixQuotient}}
\logpage{[ 8, 2, 1 ]}\nobreak
\hyperdef{L}{X8115B018871FD364}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MatrixQuotient({\slshape a, l})\index{MatrixQuotient@\texttt{MatrixQuotient}}
\label{MatrixQuotient}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{EpimorphismMatrixQuotient({\slshape a, l})\index{EpimorphismMatrixQuotient@\texttt{EpimorphismMatrixQuotient}}
\label{EpimorphismMatrixQuotient}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The matrix algebra of \mbox{\texttt{\slshape a}}'s action on level \mbox{\texttt{\slshape l}}.



 The first function returns the matrix algebra generated by the activities of \mbox{\texttt{\slshape a}} on level \mbox{\texttt{\slshape l}} (see the examples in \ref{ActivitySparse}). The second functon returns an algebra homomorphism from \mbox{\texttt{\slshape a}} to the matrix algebra. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> a := ThinnedAlgebraWithOne(GF(2),GrigorchukGroup);
  <self-similar algebra-with-one on alphabet GF(2)^2 with 4 generators>
  gap> List([0..4],i->Dimension(MatrixQuotient(a,i)));
  [ 1, 2, 6, 22, 78 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ThinnedAlgebra}}
\logpage{[ 8, 2, 2 ]}\nobreak
\hyperdef{L}{X8150FC4E84D208C6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ThinnedAlgebra({\slshape r, g})\index{ThinnedAlgebra@\texttt{ThinnedAlgebra}}
\label{ThinnedAlgebra}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ThinnedAlgebraWithOne({\slshape r, g})\index{ThinnedAlgebraWithOne@\texttt{ThinnedAlgebraWithOne}}
\label{ThinnedAlgebraWithOne}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The thinned algebra [with one] associated with \mbox{\texttt{\slshape g}}.



 The first function returns the thinned algebra of a FR group/monoid/semigroup \mbox{\texttt{\slshape g}}, over the domain \mbox{\texttt{\slshape r}}. This is the linear envelope of \mbox{\texttt{\slshape g}} in its natural action on sequences. 

 The embedding of \mbox{\texttt{\slshape g}} in its thinned algebra is returned by \texttt{Embedding(g,a)}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> a := ThinnedAlgebraWithOne(GF(2),GrigorchukGroup);
  <self-similar algebra on alphabet GF(2)^2 with 5 generators>
  gap> a.1 = GrigorchukGroup.1^Embedding(GrigorchukGroup,a);
  true
  gap> Dimension(VectorSpace(GF(2),[One(a),a.2,a.3,a.4]));
  3
\end{Verbatim}
 }

 }

 }

 
\chapter{\textcolor{Chapter }{Iterated monodromy groups}}\label{img}
\logpage{[ 9, 0, 0 ]}
\hyperdef{L}{X798DE1297EC58F59}{}
{
 Iterated monodromy machines are a special class of group FR machines (see
Section \ref{frmachines}) with attribute \texttt{IMGRelator} (\ref{IMGRelator}). This attribute records a cyclic ordering of the generators of the machine
whose product is trivial. 

 The interpretation is the following: the machine encodes a \emph{Thurston map}, i.e. a post-critically finite topological branched self-covering of the
sphere $S^2$. Generators of the machine correspond to loops in the fundamental group of
the sphere (punctured at post-critical points), that circle once
counter-clockwise around a post-critical point. For more details on the
connection between self-similar groups and Thurston maps, see \cite{MR2162164}. 

 IMG FR elements are a bit different from group FR elements: while we said a
group FR element is trivial if and only if its action on sequences is trivial,
we say that an IMG FR element $g$ is trivial if there exists an integer $N$ such that unfolding $N$ times the recursion for $g$ yields only trivial states (as elements of the underlying free group). 
\section{\textcolor{Chapter }{Creators and operations for IMG FR machines}}\logpage{[ 9, 1, 0 ]}
\hyperdef{L}{X7CA23C95828C2A3E}{}
{
 

\subsection{\textcolor{Chapter }{IMGFRMachine (FR machine)}}
\logpage{[ 9, 1, 1 ]}\nobreak
\hyperdef{L}{X79C411167D97F0F9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IMGFRMachine({\slshape m[, w]})\index{IMGFRMachine@\texttt{IMGFRMachine}!FR machine}
\label{IMGFRMachine:FR machine}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
An IMG FR machine.



 This function creates a new IMG FR machine, starting from a group FR machine \mbox{\texttt{\slshape m}}. If a state \mbox{\texttt{\slshape w}} is specified, it is used as IMG relator; otherwise, if some ordering of the
generators is trivial, it is used as a relator; in other cases, an additional
generator is added to the machine in such a way that a product of generators
is trivial. 

 A standard FR machine can be recovered from an IMG FR machine by \texttt{AsGroupFRMachine} (\ref{AsGroupFRMachine}), \texttt{AsMonoidFRMachine} (\ref{AsMonoidFRMachine}), and \texttt{AsSemigroupFRMachine} (\ref{AsSemigroupFRMachine}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  !!!
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IMGRelator}}
\logpage{[ 9, 1, 2 ]}\nobreak
\hyperdef{L}{X7BCE03F2827DAA0A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IMGRelator({\slshape m})\index{IMGRelator@\texttt{IMGRelator}}
\label{IMGRelator}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
The relator of the IMG FR machine.



 This attribute stores the product of generators that is trivial. In essence,
it records an ordering of the generators whose product is trivial in the
punctured sphere's fundamental group. }

 

\subsection{\textcolor{Chapter }{Mating}}
\logpage{[ 9, 1, 3 ]}\nobreak
\hyperdef{L}{X7AB029AE8590964E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Mating({\slshape m1, m2[, w1, w2]})\index{Mating@\texttt{Mating}}
\label{Mating}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
An IMG FR machine.



 This function mates two IMG FR machines. The arguments \mbox{\texttt{\slshape w1,w2}} are IMG FR elements that represent adding elements; they may be omitted if \mbox{\texttt{\slshape m1,m2}} contain pre-specified adding machines (through the attribute \texttt{AddingElement} (\ref{AddingElement})). The elements \mbox{\texttt{\slshape w1}} and \mbox{\texttt{\slshape w2}} must satisfy the same recursion. 

 The mating is defined as follows: one removes a disc around the adding machine
in \mbox{\texttt{\slshape m1}} and \mbox{\texttt{\slshape m2}}; one applies complex conjugation to \mbox{\texttt{\slshape m2}}; and one glues the hollowed spheres along their boundary circle. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  !!!
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{PolynomialFRMachine}}
\logpage{[ 9, 1, 4 ]}\nobreak
\hyperdef{L}{X7D71EBDA7D7C3474}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PolynomialFRMachine({\slshape d, per, pre})\index{PolynomialFRMachine@\texttt{PolynomialFRMachine}}
\label{PolynomialFRMachine}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PolynomialIMGMachine({\slshape d, per, pre})\index{PolynomialIMGMachine@\texttt{PolynomialIMGMachine}}
\label{PolynomialIMGMachine}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PolynomialMealyMachine({\slshape d, per, pre})\index{PolynomialMealyMachine@\texttt{PolynomialMealyMachine}}
\label{PolynomialMealyMachine}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
An IMG FR machine.



 This function creates a group, IMG or Mealy machine that describes a
topological polynomial. The polynomial is described symbolically in the
language of \emph{external angles}. For more details, see \cite{MR762431} and \cite{MR812271} (in the quadratic case), \cite{MR1149891} (in the preperiodic case), and \cite{math.DS/9305207} (in the general case). 

 \mbox{\texttt{\slshape d}} is the degree of the polynomial. \mbox{\texttt{\slshape per}} and \mbox{\texttt{\slshape pre}} are lists of angles or preangles. In what follows, angles are rational
numbers, considered modulo 1. Each entry in \mbox{\texttt{\slshape per}} or \mbox{\texttt{\slshape pre}} is either a rational (interpreted as an angle), or a list of angles $[a_1,\dots,a_i]$ such that $da_1=\dots=da_i$. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> PolynomialIMGMachine(2,[0],[]); # the adding machine
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ f1, f2 ] )/[ f2*f1 ]>
  gap> Display(last);
   G  |     1        2
  ----+--------+--------+
   f1 | <id>,2     f1,1
   f2 |   f2,2   <id>,1
  ----+--------+--------+
  Relator: f2*f1
  gap> Display(PolynomialIMGMachine(2,[1/3],[])); # the Basilica
   G  |      1         2
  ----+---------+---------+
   f1 | f1^-1,2   f2*f1,1
   f2 |    f1,1    <id>,2
   f3 |    f3,2    <id>,1
  ----+---------+---------+
  Relator: f3*f2*f1
  gap> Display(PolynomialIMGMachine(2,[],[1/6])); # z^2+I
   G  |            1         2
  ----+---------------+---------+
   f1 | f1^-1*f2^-1,2   f2*f1,1
   f2 |          f1,1      f3,2
   f3 |          f2,1    <id>,2
   f4 |          f4,2    <id>,1
  ----+---------------+---------+
  Relator: f4*f3*f2*f1
  gap> PolynomialIMGMachine(3,[[0,1/3],[5/9,8/9]],[]);
  <FR machine with alphabet [ 1 .. 3 ] on Group( [ f1, f2, f3 ] )/[ f3*f2*f1 ]>
  gap> PolynomialIMGMachine(3,[[0,1/3]],[[5/9,8/9]]);
  <FR machine with alphabet [ 1 .. 3 ] on Group( [ f1, f2, f3, f4 ] )/[ f4*f3*f2*f1 ]>
\end{Verbatim}
 The following construct the examples in Poirier's paper: 
\begin{Verbatim}[fontsize=\small,frame=single,label=]
  PoirierExamples := function(arg)
      if arg=[1] then
          return PolynomialIMGMachine(2,[1/7],[]);
      elif arg=[2] then
          return PolynomialIMGMachine(2,[],[1/2]);
      elif arg=[3,1] then
          return PolynomialIMGMachine(2,[],[5/12]);
      elif arg=[3,2] then
          return PolynomialIMGMachine(2,[],[7/12]);
      elif arg=[4,1] then
          return PolynomialIMGMachine(3,[[3/4,1/12],[1/4,7/12]],[]);
      elif arg=[4,2] then
          return PolynomialIMGMachine(3,[[7/8,5/24],[5/8,7/24]],[]);
      elif arg=[4,3] then
          return PolynomialIMGMachine(3,[[1/8,19/24],[3/8,17/24]],[]);
      elif arg=[5] then
          return PolynomialIMGMachine(3,[[3/4,1/12],[3/8,17/24]],[]);
      elif arg=[6,1] then
          return PolynomialIMGMachine(4,[],[[1/4,3/4],[1/16,13/16],[5/16,9/16]]);
      elif arg=[6,2] then
          return PolynomialIMGMachine(4,[],[[1/4,3/4],[3/16,15/16],[7/16,11/16]]);
      elif arg=[7] then
          return PolynomialIMGMachine(5,[[0,4/5],[1/5,2/5,3/5]],[[1/5,4/5]]);
      elif arg=[9,1] then
          return PolynomialIMGMachine(3,[[0,1/3],[5/9,8/9]],[]);
      elif arg=[9,2] then
          return PolynomialIMGMachine(3,[[0,1/3]],[[5/9,8/9]]);
      fi;
  end;
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{DBRationalIMGGroup}}
\logpage{[ 9, 1, 5 ]}\nobreak
\hyperdef{L}{X82F0B23486F2E3AC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DBRationalIMGGroup({\slshape sequence, or, rational, map})\index{DBRationalIMGGroup@\texttt{DBRationalIMGGroup}}
\label{DBRationalIMGGroup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
An IMG group from Dau's database.



 This function returns the iterated monodromy group from a database of groups
associated to quadratic rational maps. This database has been compiled by Dau
Truong Tan \cite{tan:database}. 

 When called with no arguments, this command returns the database contents in
raw form. 

 The argments can be a sequence; the first integer is the size of the
postcritical set, the second argument is an index for the postcritical graph,
and sometimes a third argument distinguishes between maps with same
post-critical graph. 

 If the argument is a rational map, the command returns the IMG group of that
map, assuming its \texttt{CanonicalQuadraticRational} (\ref{CanonicalQuadraticRational}) form exists in the database. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> DBRationalIMGGroup(z^2-1);
  IMG((z-1)^2)
  gap> DBRationalIMGGroup(z^2+1); # not post-critically finite
  fail
  gap> DBRationalIMGGroup(4,1,1);
  IMG((z/h+1)^2|2h^3+2h^2+2h+1=0,h~-0.64)
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ValueRational}}
\logpage{[ 9, 1, 6 ]}\nobreak
\hyperdef{L}{X7A32EC907B726CF7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ValueRational({\slshape f, x})\index{ValueRational@\texttt{ValueRational}}
\label{ValueRational}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The value of \mbox{\texttt{\slshape f}} at \mbox{\texttt{\slshape x}}.



 This function is almost identical to \texttt{Value(f,x)}. It accepts \texttt{infinity} as an argument, and may return \texttt{infinity} as a value. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> z := Indeterminate(Rationals,"z");;
  gap> ValueRational(1/z,infinity);
  0
  gap> ValueRational(1/z,0);
  infinity
  gap> ValueRational(1/z,1/2);
  2
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{CriticalValuesQuadraticRational}}
\logpage{[ 9, 1, 7 ]}\nobreak
\hyperdef{L}{X789111E786DF284D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CriticalValuesQuadraticRational({\slshape f})\index{CriticalValuesQuadraticRational@\texttt{CriticalValuesQuadraticRational}}
\label{CriticalValuesQuadraticRational}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The critical values of \mbox{\texttt{\slshape f}}.



 This function returns, as a list, the values of \mbox{\texttt{\slshape f}} at places where the derivative of \mbox{\texttt{\slshape f}} vanishes. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> z := Indeterminate(Rationals,"z");;
  gap> CriticalValuesQuadraticRational(z^2);
  [ 0, infinity ]
  gap> CriticalValuesQuadraticRational(z^2+1);
  [ 1, infinity ]
  gap> CriticalValuesQuadraticRational((z^2+1)/(z^2-1));
  [ -1, 1 ]
  gap> CriticalValuesQuadraticRational((z^2+1)/(z^2-z-1));
  [ 2/5*E(5)-2/5*E(5)^2-2/5*E(5)^3+2/5*E(5)^4, -2/5*E(5)+2/5*E(5)^2+2/5*E(5)^3-2/5*E(5)^4 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{CanonicalQuadraticRational}}
\logpage{[ 9, 1, 8 ]}\nobreak
\hyperdef{L}{X7EA768B886A5C7F2}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CanonicalQuadraticRational({\slshape f})\index{CanonicalQuadraticRational@\texttt{CanonicalQuadraticRational}}
\label{CanonicalQuadraticRational}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The canonical forms of the quadratic rational map \mbox{\texttt{\slshape f}}.



 This function puts the quadratic rational map \mbox{\texttt{\slshape f}} in canonical form, that is, in form $((az+b)/(cz+d))^2$, such that its critical values are \texttt{0} and \texttt{infinity}. Furthermore, it attempts to make \texttt{f(infinity)=1}, and if this is impossible to make \texttt{f(0)=1}. 

 The command returns the set of all maps with these properties. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> z := Indeterminate(Rationals,"z");;
  gap> CanonicalQuadraticRational(z^2);
  [ z^2 ]
  gap> CanonicalQuadraticRational(z^2+1);
  [ (z^2)/(z^2+2*z+1), z^2+2*z+1 ]
  gap> CanonicalQuadraticRational((z^2+1)/(z^2-1));
  [ (1/2*z^2+z+1/2)/(1/2*z^2-z+1/2), (-1/2*z^2+z-1/2)/(-1/2*z^2-z-1/2) ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{PostCriticalMachine}}
\logpage{[ 9, 1, 9 ]}\nobreak
\hyperdef{L}{X8365719F7E03B7C3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PostCriticalMachine({\slshape f})\index{PostCriticalMachine@\texttt{PostCriticalMachine}}
\label{PostCriticalMachine}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The Mealy machine of \mbox{\texttt{\slshape f}}'s post-critical orbit.



 This function constructs a Mealy machine \texttt{P} on the alphabet \texttt{[1]}, which describes the post-critical set of \mbox{\texttt{\slshape f}}. It is in fact an oriented graph with constant out-degree 1. It is most
conveniently passed to \texttt{Draw} (\ref{Draw}). 

 The attribute \texttt{Correspondence(P)} is the list of values associated with the stateset of \texttt{P}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> z := Indeterminate(Rationals,"z");;
  gap> m := PostCriticalMachine(z^2);
  <Mealy machine on alphabet [ 1 ] with 2 states>
  gap> Display(m);
     |  1
  ---+-----+
   a | a,1
   b | b,1
  ---+-----+
  gap> Correspondence(m);
  [ 0, infinity ]
  gap> m := PostCriticalMachine(z^2-1);; Display(m); Correspondence(m);
     |  1
  ---+-----+
   a | c,1
   b | b,1
   c | a,1
  ---+-----+
  [ -1, infinity, 0 ]
\end{Verbatim}
 }

 }

 
\section{\textcolor{Chapter }{Spiders}}\logpage{[ 9, 2, 0 ]}
\hyperdef{L}{X7C73C74D87428A33}{}
{
 

\subsection{\textcolor{Chapter }{RationalFunction}}
\logpage{[ 9, 2, 1 ]}\nobreak
\hyperdef{L}{X7CC0BBAD807D1A45}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RationalFunction({\slshape m})\index{RationalFunction@\texttt{RationalFunction}}
\label{RationalFunction}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A rational function.



 !!! 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  !!!
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IMGFRMachine (rational function)}}
\logpage{[ 9, 2, 2 ]}\nobreak
\hyperdef{L}{X7ED04E0884385D54}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IMGFRMachine({\slshape m})\index{IMGFRMachine@\texttt{IMGFRMachine}!rational function}
\label{IMGFRMachine:rational function}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
An IMG FR machine.



 !!! 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  !!!
\end{Verbatim}
 }

 }

 }

 
\chapter{\textcolor{Chapter }{Examples}}\label{frexamples}
\logpage{[ 10, 0, 0 ]}
\hyperdef{L}{X7A489A5D79DA9E5C}{}
{
 \textsf{FR} predefines a large collection of machines and groups. The groups are, whenever
possible, defined as state closures of corresponding Mealy machines. 
\section{\textcolor{Chapter }{Examples of groups}}\logpage{[ 10, 1, 0 ]}
\hyperdef{L}{X7AF5DEF08531AFA5}{}
{
 

\subsection{\textcolor{Chapter }{FullBinaryGroup}}
\logpage{[ 10, 1, 1 ]}\nobreak
\hyperdef{L}{X7D774B847D81E6DE}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FullBinaryGroup\index{FullBinaryGroup@\texttt{FullBinaryGroup}}
\label{FullBinaryGroup}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FiniteDepthBinaryGroup({\slshape l})\index{FiniteDepthBinaryGroup@\texttt{FiniteDepthBinaryGroup}}
\label{FiniteDepthBinaryGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FinitaryBinaryGroup\index{FinitaryBinaryGroup@\texttt{FinitaryBinaryGroup}}
\label{FinitaryBinaryGroup}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BoundedBinaryGroup\index{BoundedBinaryGroup@\texttt{BoundedBinaryGroup}}
\label{BoundedBinaryGroup}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PolynomialGrowthBinaryGroup\index{PolynomialGrowthBinaryGroup@\texttt{PolynomialGrowthBinaryGroup}}
\label{PolynomialGrowthBinaryGroup}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FiniteStateBinaryGroup\index{FiniteStateBinaryGroup@\texttt{FiniteStateBinaryGroup}}
\label{FiniteStateBinaryGroup}
}\hfill{\scriptsize (global variable)}}\\


 These are the finitary, bounded, polynomial-growth, finite-state, or
unrestricted groups acting on the binary tree. They are respectively shortcuts
for \texttt{FullSCGroup([1..2])}, \texttt{FullSCGroup([1..2],l)}, \texttt{FullSCGroup([1..2],IsFinitaryFRSemigroup)}, \texttt{FullSCGroup([1..2],IsBoundedFRSemigroup)}, \texttt{FullSCGroup([1..2],IsPolynomialGrowthFRSemigroup)}, and \texttt{FullSCGroup([1..2],IsFiniteStateFRSemigroup)}. 

 They may be used to draw random elements, or to test membership. }

 

\subsection{\textcolor{Chapter }{BinaryKneadingGroup}}
\logpage{[ 10, 1, 2 ]}\nobreak
\hyperdef{L}{X813F53C57F41F5F5}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BinaryKneadingGroup({\slshape angle/ks})\index{BinaryKneadingGroup@\texttt{BinaryKneadingGroup}}
\label{BinaryKneadingGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BinaryKneadingMachine({\slshape angle/ks})\index{BinaryKneadingMachine@\texttt{BinaryKneadingMachine}}
\label{BinaryKneadingMachine}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The [machine generating the] iterated monodromy group of a quadratic
polynomial.



 The first function constructs a Mealy machine whose state closure is the
binary kneading group. 

 The second function constructs a new FR group \texttt{G}, which is the iterated monodromy group of a quadratic polynomial, either
specified by its angle or by its kneading sequence(s). 

 If the argument is a (rational) angle, the attribute \texttt{Correspondence(G)} is a function returning, for any rational, the corresponding generator of \texttt{G}. 

 If there is one argument, which is a list or a string, it is treated as the
kneading sequence of a periodic (superattracting) polynomial. The sequence is
implicity assumed to end by '*'. The attribute \texttt{Correspondence(G)} is a list of the generators of \texttt{G}. 

 If there are two arguments, which are lists or strings, they are treated as
the preperiod and period of the kneading sequence of a preperiodic polynomial.
The last symbol of the arguments must differ. The attribute \texttt{Correspondence(G)} is a pair of lists of generators; \texttt{Correspondence(G)[1]} is the preperiod, and \texttt{Correspondence(G)[2]} is the period. The attribute \texttt{KneadingSequence(G)} returns the kneading sequence, as a pair of strings representing preperiod and
period respectively. 

 As particular examples, \texttt{BinaryKneadingMachine()} is the adding machine; \texttt{BinaryKneadingGroup()} is the adding machine; and \texttt{BinaryKneadingGroup("1")} is \texttt{BasilicaGroup} (\ref{BasilicaGroup}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> BinaryKneadingGroup()=AddingGroup(2);
  true
  gap> BinaryKneadingGroup(1/3)=BasilicaGroup;
  true
  gap> g := BinaryKneadingGroup([0,1],[0]);
  BinaryKneadingGroup("01","0")
  gap> ForAll(Correspondence(g)[1],IsFinitaryFRElement);
  true
  gap> ForAll(Correspondence(g)[2],IsFinitaryFRElement);
  false
  gap> ForAll(Correspondence(g)[2],IsBoundedFRElement);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{BasilicaGroup}}
\logpage{[ 10, 1, 3 ]}\nobreak
\hyperdef{L}{X7B8D49D079D336E8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BasilicaGroup\index{BasilicaGroup@\texttt{BasilicaGroup}}
\label{BasilicaGroup}
}\hfill{\scriptsize (global variable)}}\\


 The \emph{Basilica group}. This is a shortcut for \texttt{BinaryKneadingGroup("1")}. It is the first-discovered amenable group that is not subexponentially
amenable, see \cite{MR2176547} and \cite{MR1902367}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> IsBoundedFRSemigroup(BasilicaGroup);
  true
  gap> pi := EpimorphismFromFreeGroup(BasilicaGroup); F := Source(pi);;
  [ x1, x2 ] -> [ a, b ]
  gap> sigma := GroupHomomorphismByImages(F,F,[F.1,F.2],[F.2,F.1^2]);
  [ x1, x2 ] -> [ x2, x1^2 ]
  gap> ForAll([0..10],i->IsOne(Comm(F.2,F.2^F.1)^(sigma^i*pi)));
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AddingGroup}}
\logpage{[ 10, 1, 4 ]}\nobreak
\hyperdef{L}{X85F4FDF787173863}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AddingGroup({\slshape n})\index{AddingGroup@\texttt{AddingGroup}}
\label{AddingGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AddingMachine({\slshape n})\index{AddingMachine@\texttt{AddingMachine}}
\label{AddingMachine}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AddingElement({\slshape n})\index{AddingElement@\texttt{AddingElement}}
\label{AddingElement}
}\hfill{\scriptsize (function)}}\\


 The second function constructs the adding machine on the alphabet \texttt{[1..n]}. This machine has a trivial state 1, and a non-trivial state 2. It implements
the operation "add 1 with carry" on sequences. 

 The third function constructs the Mealy element on the adding machine, with
initial state 2. 

 The first function constructs the state-closed group generated by the adding
machine on \texttt{[1..n]}. This group is isomorphic to the \texttt{Integers}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Display(AddingElement(3));
     |  1     2     3
  ---+-----+-----+-----+
   a | a,1   a,2   a,3
   b | a,2   a,3   b,1
  ---+-----+-----+-----+
  Initial state: b
  gap> Activity(FRElement(AddingMachine(3),2),2);
  (1,4,7,2,5,8,3,6,9)
  gap> G := AddingGroup(3);
  <self-similar group over [ 1 .. 3 ] with 1 generator>
  gap> Size(G);
  infinity
  gap> IsRecurrent(G);
  true
  gap> IsLevelTransitive(G);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{BinaryAddingGroup}}
\logpage{[ 10, 1, 5 ]}\nobreak
\hyperdef{L}{X7A4BB24A805CDF63}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BinaryAddingGroup\index{BinaryAddingGroup@\texttt{BinaryAddingGroup}}
\label{BinaryAddingGroup}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BinaryAddingMachine\index{BinaryAddingMachine@\texttt{BinaryAddingMachine}}
\label{BinaryAddingMachine}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BinaryAddingElement\index{BinaryAddingElement@\texttt{BinaryAddingElement}}
\label{BinaryAddingElement}
}\hfill{\scriptsize (global variable)}}\\


 These are respectively the same as \texttt{AddingGroup(2)}, \texttt{AddingMachine(2)} and \texttt{AddingElement(2)}. }

 

\subsection{\textcolor{Chapter }{MixerGroup}}
\logpage{[ 10, 1, 6 ]}\nobreak
\hyperdef{L}{X78AFA63B86C94227}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MixerGroup({\slshape A, B, f[, g]})\index{MixerGroup@\texttt{MixerGroup}}
\label{MixerGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MixerMachine({\slshape A, B, f[, g]})\index{MixerMachine@\texttt{MixerMachine}}
\label{MixerMachine}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
A Mealy "mixer" machine/group.



 The second function constructs a Mealy "mixer" machine \texttt{m}. This is a machine determined by a permutation group \mbox{\texttt{\slshape A}}, a finitely generated group \mbox{\texttt{\slshape B}}, and a matrix of homomorphisms from \mbox{\texttt{\slshape B}} to \mbox{\texttt{\slshape A}}. If \mbox{\texttt{\slshape A}} acts on \texttt{[1..d]}, then each row of \mbox{\texttt{\slshape f}} contains at most $d-1$ homomorphisms. The optional last argument is an endomorphism of \mbox{\texttt{\slshape B}}. If absent, it is treated as the identity map on \mbox{\texttt{\slshape B}}. 

 The states of the machine are 1, followed by some elements \texttt{a} of \mbox{\texttt{\slshape A}}, followed by as many copies of some elements \texttt{b} of \mbox{\texttt{\slshape B}} as there are rows in \mbox{\texttt{\slshape f}}. The elements in \mbox{\texttt{\slshape B}} that are taken is the smallest sublist of \mbox{\texttt{\slshape B}} containing its generators and closed under \mbox{\texttt{\slshape g}}. The elements in \mbox{\texttt{\slshape A}} that are taken are the generators of \mbox{\texttt{\slshape A}} and all images of all taken elements of \mbox{\texttt{\slshape B}} under maps in \mbox{\texttt{\slshape f}}. 

 The transitions from \texttt{a} are towards 1 and the outputs are the permutations in \mbox{\texttt{\slshape A}}. The transitions from \texttt{b} are periodically given by \mbox{\texttt{\slshape f}}, completed by trivial elements, and finally by $b^g$; the output of \texttt{b} is trivial. 

 This construction is described in more detail in \cite{MR1856923} and \cite{MR2035113}. 

 \texttt{Correspondence(m)} is a list, with in first position the subset of the states that correspond to \mbox{\texttt{\slshape A}}, in second position the states that correspond to the first copy of \mbox{\texttt{\slshape B}}, etc. 

 The first function constructs the group generated by the mixer machine. For
examples see \texttt{GrigorchukGroups} (\ref{GrigorchukGroups}), \texttt{NeumannGroup} (\ref{NeumannGroup}), \texttt{GuptaSidkiGroups} (\ref{GuptaSidkiGroups}), and \texttt{OtherSpinalGroup} (\ref{OtherSpinalGroup}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> grigorchukgroup := MixerGroup(Group((1,2)),Group((1,2)),
       [[IdentityMapping(Group((1,2)))],[IdentityMapping(Group((1,2)))],[]]));
  <self-similar group over [ 1 .. 2 ] with 4 generators>
  gap> IdGroup(Group(grigorchukgroup.1,grigorchukgroup.2));
  [ 32, 18 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{SunicGroup}}
\logpage{[ 10, 1, 7 ]}\nobreak
\hyperdef{L}{X84C97E0687F119C0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SunicGroup({\slshape phi})\index{SunicGroup@\texttt{SunicGroup}}
\label{SunicGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Sunicmachine({\slshape phi})\index{Sunicmachine@\texttt{Sunicmachine}}
\label{Sunicmachine}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The Sunic machine associated with the polynomial \mbox{\texttt{\slshape phi}}.



 A "Sunic machine" is a special kind of \texttt{MixerMachine} (\ref{MixerMachine}), in which the group $A$ is a finite field $GF(q)$, the group $B$ is an extension $A[x]/(\phi)$, where $\phi$ is a monic polynomial; there is a map $f:B\to A$, given say by evaluation; and there is an endomorphism of $g:B\to B$ given by multiplication by $\phi$. 

 These groups were described in \cite{MR2318546}. In particular, the case $q=2$ and $\phi=x^2+x+1$ gives the original \texttt{GrigorchukGroup} (\ref{GrigorchukGroup}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> x := Indeterminate(GF(2));;
  gap> g := SunicGroup(x^2+x+1);
  SunicGroup(x^2+x+Z(2)^0)
  gap> g = GrigorchukGroup;
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{GrigorchukMachines}}
\logpage{[ 10, 1, 8 ]}\nobreak
\hyperdef{L}{X79E3F3BE80F34590}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GrigorchukMachines({\slshape omega})\index{GrigorchukMachines@\texttt{GrigorchukMachines}}
\label{GrigorchukMachines}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GrigorchukGroups({\slshape omega})\index{GrigorchukGroups@\texttt{GrigorchukGroups}}
\label{GrigorchukGroups}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
One of the Grigorchuk groups.



 This function constructs the Grigorchuk machine or group associated with the
infinite sequence \mbox{\texttt{\slshape omega}}, which is assumed (pre)periodic; \mbox{\texttt{\slshape omega}} is either a periodic list (see \texttt{PeriodicList} (\ref{PeriodicList})) or a plain list describing the period. Entries in the list are integers in \texttt{[1..3]}. 

 These groups are \texttt{MixerGroup} (\ref{MixerGroup})s. The most famous example is \texttt{GrigorchukGroups([1,2,3])}, which is also called \texttt{GrigorchukGroup} (\ref{GrigorchukGroup}). 

 These groups are all 4-generated and infinite. They are described in \cite{MR764305}. \texttt{GrigorchukGroups([1])} is infinite dihedral. If \mbox{\texttt{\slshape omega}} contains at least 2 different digits, \texttt{GrigorchukGroups([1])} has intermediate word growth. If \mbox{\texttt{\slshape omega}} contains all 3 digits, \texttt{GrigorchukGroups([1])} is torsion. 

 The growth of \texttt{GrigorchukGroups([1,2])} has been studied in \cite{MR2144977}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> G := GrigorchukGroups([1]);
  <self-similar group over [ 1 .. 2 ] with 4 generators>
  gap> Index(G,DerivedSubgroup(G)); IsAbelian(DerivedSubgroup(G));
  4
  true
  gap> H := GrigorchukGroups([1,2]);
  <self-similar group over [ 1 .. 2 ] with 4 generators>
  gap> Order(H.1*H.2);
  8
  gap> Order(H.1*H.4);
  infinity
  gap> IsSubgroup(H,G);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{GrigorchukMachine}}
\logpage{[ 10, 1, 9 ]}\nobreak
\hyperdef{L}{X85BAE48780E665A4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GrigorchukMachine\index{GrigorchukMachine@\texttt{GrigorchukMachine}}
\label{GrigorchukMachine}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GrigorchukGroup\index{GrigorchukGroup@\texttt{GrigorchukGroup}}
\label{GrigorchukGroup}
}\hfill{\scriptsize (global variable)}}\\


 This is Grigorchuk's first group, introduced in \cite{MR565099}. It is a 4-generated infinite torsion group, and has intermediate word
growth. It could have been defined as \texttt{FRGroup("a=(1,2)","b={\textless}a,c{\textgreater}","c={\textless}a,d{\textgreater}","d={\textless},b{\textgreater}")}, but is rather defined using Mealy elements. 

 The command \texttt{EpimorphismFromFpGroup(GrigorchukGroup,n)} will will construct an approximating presentation for the Grigorchuk group, as
proven in \cite{MR819415}. Adding the relations \texttt{Image(sigma\texttt{\symbol{94}}(n-2),(a*d)\texttt{\symbol{94}}2)}, \texttt{Image(sigma\texttt{\symbol{94}}(n-1),(a*b)\texttt{\symbol{94}}2)} and \texttt{Image(sigma\texttt{\symbol{94}}(n-2),(a*c)\texttt{\symbol{94}}4)} yields the quotient acting on $2^n$ points, as a finitely presented group. }

 

\subsection{\textcolor{Chapter }{GrigorchukOverGroup}}
\logpage{[ 10, 1, 10 ]}\nobreak
\hyperdef{L}{X800640597E9C707D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GrigorchukOverGroup\index{GrigorchukOverGroup@\texttt{GrigorchukOverGroup}}
\label{GrigorchukOverGroup}
}\hfill{\scriptsize (global variable)}}\\


 This is a group strictly containing the Grigorchuk group (see \texttt{GrigorchukGroup} (\ref{GrigorchukGroup})). It also has intermediate growth (see \cite{MR1899368}, but it contains elements of infinite order. It could have been defined as \texttt{FRGroup("a=(1,2)","b={\textless}a,c{\textgreater}","c={\textless},d{\textgreater}","d={\textless},b{\textgreater}")}, but is rather defined using Mealy elements. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> IsSubgroup(GrigorchukOverGroup,GrigorchukGroup);
  true
  gap> Order(Product(GeneratorsOfGroup(GrigorchukOverGroup)));
  infinity
  gap> GrigorchukGroup.2=GrigorchukSuperGroup.2*GrigorchukSuperGroup.3;
  true
\end{Verbatim}
 

 The command \texttt{EpimorphismFromFpGroup(GrigorchukOverGroup,n)} will will construct an approximating presentation for the Grigorchuk
overgroup, as proven in \cite{MR2009317}. }

 

\subsection{\textcolor{Chapter }{GrigorchukEvilTwin}}
\logpage{[ 10, 1, 11 ]}\nobreak
\hyperdef{L}{X7C58F33D825A473A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GrigorchukEvilTwin\index{GrigorchukEvilTwin@\texttt{GrigorchukEvilTwin}}
\label{GrigorchukEvilTwin}
}\hfill{\scriptsize (global variable)}}\\


 This is a group with same closure as the Grigorchuk group (see \texttt{GrigorchukGroup} (\ref{GrigorchukGroup})), but not isomorphic to it. It could have been defined as \texttt{FRGroup("a=(1,2)","x={\textless}y,a{\textgreater}","y={\textless}a,z{\textgreater}","z={\textless},x{\textgreater}")}, but is rather defined using Mealy elements. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> AbelianInvariants(GrigorchukEvilTwin);
  [ 2, 2, 2, 2 ]
  gap> AbelianInvariants(GrigorchukGroup);
  [ 2, 2, 2 ]
  gap> PermGroup(GrigorchukGroup,8)=PermGroup(GrigorchukEvilTwin,8);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{BrunnerSidkiVieiraGroup}}
\logpage{[ 10, 1, 12 ]}\nobreak
\hyperdef{L}{X7F93EC437B5AE276}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BrunnerSidkiVieiraGroup\index{BrunnerSidkiVieiraGroup@\texttt{BrunnerSidkiVieiraGroup}}
\label{BrunnerSidkiVieiraGroup}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BrunnerSidkiVieiraMachine\index{BrunnerSidkiVieiraMachine@\texttt{BrunnerSidkiVieiraMachine}}
\label{BrunnerSidkiVieiraMachine}
}\hfill{\scriptsize (global variable)}}\\


 This machine is the sum of two adding machines, one in standard form and one
conjugated by the element \texttt{d} described below. The group that it generates is described in \cite{MR1656573}. It could have been defined as \texttt{FRGroup("tau={\textless},tau{\textgreater}(1,2)","mu={\textless},mu\texttt{\symbol{94}}-1{\textgreater}(1,2)")}, but is rather defined using Mealy elements. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> V := FRGroup("d=<e,e>(1,2)","e=<d,d>");
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> Elements(V);
  [ <2|identity ...>, <2|e>, <2|d>, <2|e*d> ]
  gap> AssignGeneratorVariables(BrunnerSidkiVieiraGroup);
  #I  Assigned the global variables [ "tau", "mu", "" ]
  gap> List(V,x->tau^x)=[tau,mu,mu^-1,tau^-1];
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AleshinGroups}}
\logpage{[ 10, 1, 13 ]}\nobreak
\hyperdef{L}{X7F8A028B799946D3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AleshinGroups({\slshape l})\index{AleshinGroups@\texttt{AleshinGroups}}
\label{AleshinGroups}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AleshinMachines({\slshape l})\index{AleshinMachines@\texttt{AleshinMachines}}
\label{AleshinMachines}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The Aleshin machine with \texttt{Length(l)} states.



 This function constructs the bireversible machines introduced by Aleshin in \cite{MR713968}. The argument \mbox{\texttt{\slshape l}} is a list of permutations, either \texttt{()} or \texttt{(1,2)}. The groups that they generate are contructed as \texttt{AleshinGroups}. 

 If \texttt{l=[(1,2),(1,2),()]}, this is \texttt{AleshinGroup} (\ref{AleshinGroup}). More generally, if \texttt{l=[(1,2,(1,2),(),...,()]} has odd length, this is a free group of rank \texttt{Length(l)}, see \cite{vorobets}. 

 If \texttt{l=[(1,2),(1,2),...]} has even length and contains an even number of \texttt{()}'s, then this is also a free group of rank \texttt{Length(l)}, see \cite{steinberg-vorobets}. 

 If \texttt{l=[(),(),(1,2)]}, this is \texttt{BabyAleshinGroup} (\ref{BabyAleshinGroup}). more generally, if \texttt{l=[(),(),...]} has even length and contains an even number of \texttt{(1,2)}'s, then this is the free product of \texttt{Length(l)} copies of the order-2 group. }

 

\subsection{\textcolor{Chapter }{AleshinGroup}}
\logpage{[ 10, 1, 14 ]}\nobreak
\hyperdef{L}{X7C286D3A84790ECE}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AleshinGroup\index{AleshinGroup@\texttt{AleshinGroup}}
\label{AleshinGroup}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AleshinMachine\index{AleshinMachine@\texttt{AleshinMachine}}
\label{AleshinMachine}
}\hfill{\scriptsize (global variable)}}\\


 This is the first example of non-abelian free group. It is the group generated
by \texttt{AleshinMachine([(1,2),(1,2),()])}. It could have been defined as \texttt{FRGroup("a={\textless}b,c{\textgreater}(1,2)","b={\textless}c,b{\textgreater}(1,2)","c={\textless}a,a{\textgreater}")}, but is rather defined using Mealy elements. }

 

\subsection{\textcolor{Chapter }{BabyAleshinGroup}}
\logpage{[ 10, 1, 15 ]}\nobreak
\hyperdef{L}{X7E024B4D7BA411B1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BabyAleshinGroup\index{BabyAleshinGroup@\texttt{BabyAleshinGroup}}
\label{BabyAleshinGroup}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{BabyAleshinMachine\index{BabyAleshinMachine@\texttt{BabyAleshinMachine}}
\label{BabyAleshinMachine}
}\hfill{\scriptsize (global variable)}}\\


 There are only two connected, transitive bireversible machines on a 2-letter
alphabet, with 3 generators: \texttt{AleshinMachine(3)} and the baby Aleshin machine. 

 The group generated by this machine is abstractly the free product of three $C_2$'s, see \cite[1.10.3]{MR2162164}. It could have been defined as \texttt{FRGroup("a={\textless}b,c{\textgreater}","b={\textless}c,b{\textgreater}","c={\textless}a,a{\textgreater}(1,2)")}, but is rather defined here using Mealy elements. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> K := Kernel(GroupHomomorphismByImagesNC(BabyAleshinGroup,Group((1,2)),
                   GeneratorsOfGroup(BabyAleshinGroup),[(1,2),(1,2),(1,2)]));
  <self-similar group over [ 1 .. 2 ] with 4 generators>
  gap> Index(BabyAleshinGroup,K);
  2
  gap> IsSubgroup(AleshinGroup,K);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{SidkiFreeGroup}}
\logpage{[ 10, 1, 16 ]}\nobreak
\hyperdef{L}{X8108E3A8872A6FFE}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SidkiFreeGroup\index{SidkiFreeGroup@\texttt{SidkiFreeGroup}}
\label{SidkiFreeGroup}
}\hfill{\scriptsize (global variable)}}\\


 This is a group suggested by Sidki as an example of a non-abelian state-closed
free group. Nothing is known about that group: whether it is free as
conjectured; whether generator \mbox{\texttt{\slshape a}} is state-closed, etc. It is defined as \texttt{FRGroup("a={\textless}a\texttt{\symbol{94}}2,a\texttt{\symbol{94}}t{\textgreater}","t={\textless},t{\textgreater}(1,2)")]]{\textgreater}}. }

 

\subsection{\textcolor{Chapter }{GuptaSidkiGroups}}
\logpage{[ 10, 1, 17 ]}\nobreak
\hyperdef{L}{X82D3CB6A7C189C78}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GuptaSidkiGroups({\slshape n})\index{GuptaSidkiGroups@\texttt{GuptaSidkiGroups}}
\label{GuptaSidkiGroups}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GeneralizedGuptaSidkiGroups({\slshape n})\index{GeneralizedGuptaSidkiGroups@\texttt{GeneralizedGuptaSidkiGroups}}
\label{GeneralizedGuptaSidkiGroups}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GuptaSidkiMachines({\slshape n})\index{GuptaSidkiMachines@\texttt{GuptaSidkiMachines}}
\label{GuptaSidkiMachines}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The Gupta-Sidki machine on an \mbox{\texttt{\slshape n}}-letter alphabet.



 This function constructs the machines introduced by Gupta and Sidki in \cite{MR696534}. They generate finitely generated infinite torsion groups: the exponent of
every element divides some power of \mbox{\texttt{\slshape n}}. The special case $n=3$ is defined as \texttt{GuptaSidkiGroup} (\ref{GuptaSidkiGroup}) and \texttt{GuptaSidkiMachine} (\ref{GuptaSidkiMachine}). 

 For $n>3$, there are (at least) two natural ways to generalize the Gupta-Sidki
construction: the original one involves the recursion \texttt{"t={\textless}a,a\texttt{\symbol{94}}-1,1,...,1,t{\textgreater}"}, while the second (called here `generalized') involves the recursion \texttt{"t={\textless}a,a\texttt{\symbol{94}}2,...,a\texttt{\symbol{94}}-1,t{\textgreater}"}. A finite L-presentation for the latter is implemented. It is not as
computationally efficient as the L-presentation of the normal closure of \texttt{t} (a subgroup of index $p$), which is an ascending L-presented group. The inclusion of that subgroup may
be recoverd via \texttt{EmbeddingOfAscendingSubgroup(GuptaSidkiGroup)}. }

 

\subsection{\textcolor{Chapter }{GuptaSidkiGroup}}
\logpage{[ 10, 1, 18 ]}\nobreak
\hyperdef{L}{X83E59288860EF661}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GuptaSidkiGroup\index{GuptaSidkiGroup@\texttt{GuptaSidkiGroup}}
\label{GuptaSidkiGroup}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GuptaSidkiMachine\index{GuptaSidkiMachine@\texttt{GuptaSidkiMachine}}
\label{GuptaSidkiMachine}
}\hfill{\scriptsize (global variable)}}\\


 This is an infinite, 2-generated, torsion 3-group. It could have been defined
as \texttt{FRGroup("a=(1,2,3)","t={\textless}a,a\texttt{\symbol{94}}-1,t{\textgreater}")}, but is rather defined using Mealy elements. }

 

\subsection{\textcolor{Chapter }{NeumannGroup}}
\logpage{[ 10, 1, 19 ]}\nobreak
\hyperdef{L}{X8521B4FF7BA189B2}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NeumannGroup({\slshape P})\index{NeumannGroup@\texttt{NeumannGroup}}
\label{NeumannGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NeumannMachine({\slshape P})\index{NeumannMachine@\texttt{NeumannMachine}}
\label{NeumannMachine}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The Neumann machine/group on the permutation group \mbox{\texttt{\slshape P}}.



 The first function constructs the Neumann machine associated to the
permutation group \mbox{\texttt{\slshape P}}. It is a shortcut for \texttt{MixerMachine(P,P,[[IdentityMapping(P)]])}. 

 The second function constructs the Neumann group on the permutation group \mbox{\texttt{\slshape P}}. These groups were first considered in \cite{MR840129}. In particular, \texttt{NeumannGroup(PSL(3,2))} is a group of non-uniform exponential growth (see \cite{MR1981466}), and \texttt{NeumannGroup(Group((1,2,3)))} is \texttt{FabrykowskiGuptaGroup} (\ref{FabrykowskiGuptaGroup}). 

 The attribute \texttt{Correspondence(G)} is set to a list of homomorphisms from \mbox{\texttt{\slshape P}} to the \texttt{A} and \texttt{B} copies of \texttt{P}. }

 

\subsection{\textcolor{Chapter }{FabrykowskiGuptaGroup}}
\logpage{[ 10, 1, 20 ]}\nobreak
\hyperdef{L}{X878D1C7080EA9797}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FabrykowskiGuptaGroup\index{FabrykowskiGuptaGroup@\texttt{FabrykowskiGuptaGroup}}
\label{FabrykowskiGuptaGroup}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FabrykowskiGuptaGroups({\slshape p})\index{FabrykowskiGuptaGroups@\texttt{FabrykowskiGuptaGroups}}
\label{FabrykowskiGuptaGroups}
}\hfill{\scriptsize (function)}}\\


 This is an infinite, 2-generated group of intermediate word growth. It was
studied in \cite{MR942349} and \cite{MR1153150}. It could have been defined as \texttt{FRGroup("a=(1,2,3)","t={\textless}a,,t{\textgreater}")}, but is rather defined using Mealy elements. It has a torsion-free subgroup
of index 3 and is branched. 

 The natural generalization, replacing 3 by $p$, is constructed by the second form. It is a specific case of Neumann group
(see \texttt{NeumannGroup} (\ref{NeumannGroup})), for which an ascending L-presentation is known. }

 

\subsection{\textcolor{Chapter }{OtherSpinalGroup}}
\logpage{[ 10, 1, 21 ]}\nobreak
\hyperdef{L}{X864A87957D1E1AF6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{OtherSpinalGroup\index{OtherSpinalGroup@\texttt{OtherSpinalGroup}}
\label{OtherSpinalGroup}
}\hfill{\scriptsize (global variable)}}\\


 This is an infinite, 2-generated group, which was studied in \cite{MR1899368}. It has a torsion-free subgroup of index 3, and is virtually branched but not
branched. It could have been defined as \texttt{FRGroup("a=(1,2,3)","t={\textless}a,a,t{\textgreater}")}, but is rather defined using Mealy elements. }

 

\subsection{\textcolor{Chapter }{GammaPQMachine}}
\logpage{[ 10, 1, 22 ]}\nobreak
\hyperdef{L}{X7A0319827CB51ED0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GammaPQMachine({\slshape p, q})\index{GammaPQMachine@\texttt{GammaPQMachine}}
\label{GammaPQMachine}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GammaPQGroup({\slshape p, q})\index{GammaPQGroup@\texttt{GammaPQGroup}}
\label{GammaPQGroup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The quaternion-based machine / SC group.



 The first function constructs a bireversible (see \texttt{IsBireversible} (\ref{IsBireversible})) Mealy machine based on quaternions, see \cite{MR1839488} and \cite{MR1839489}. This machine has $p+1$ states indexed by integer quaternions of norm \mbox{\texttt{\slshape p}}, and an alphabet of size $q+1$ indexed by quaternions of norm \mbox{\texttt{\slshape q}}. These quaternions are congruent to $1\pmod 2$ or $i\pmod 2$ depending on whether the odd prime $p$ or $q$ is $1$ or $3\pmod 4$. 

 The structure of the machine is such that there is a transition from $(q,a)$ to $(q',a')$ precisely when $qa'=\pm q'a$. In particular, the relations of the \texttt{StructuralGroup} (\ref{StructuralGroup}) hold up to a sign, when the alphabet/state letters are substituted for the
appropriate quaternions. 

 The quaternions themselves can be recovered through \texttt{Correspondence} (\ref{Correspondence:FR machine}), which is a list with in first position the quaternions of norm $p$ and in second those of norm $q$. 

 The second function constructs the quaternion lattice that is the \texttt{StructuralGroup} (\ref{StructuralGroup}) of that machine. It has actions on two trees, given by \texttt{VerticalAction} (\ref{VerticalAction}) and \texttt{HorizontalAction} (\ref{HorizontalAction}); the ranges of these actions are groups generated by automata, which are
infinitely-transitive (see \texttt{IsInfinitelyTransitive} (\ref{IsInfinitelyTransitive})) and free by \cite[Proposition 3.3]{MR2155175}; see also \cite{MR713968}. }

 

\subsection{\textcolor{Chapter }{HanoiGroup}}
\logpage{[ 10, 1, 23 ]}\nobreak
\hyperdef{L}{X7A0BE9F57B401C5C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{HanoiGroup({\slshape n})\index{HanoiGroup@\texttt{HanoiGroup}}
\label{HanoiGroup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The Hanoi group on an \mbox{\texttt{\slshape n}} pegs.



 This function constructs the Hanoi group on \mbox{\texttt{\slshape n}} pegs. Generators of the group correspond to moving a peg, and tree vertices
correspond to peg configurations. This group is studied in \cite{MR2217913}. }

 

\subsection{\textcolor{Chapter }{DahmaniGroup}}
\logpage{[ 10, 1, 24 ]}\nobreak
\hyperdef{L}{X7C7A0EEF7EFF8B99}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DahmaniGroup\index{DahmaniGroup@\texttt{DahmaniGroup}}
\label{DahmaniGroup}
}\hfill{\scriptsize (global variable)}}\\


 This is an example of a non-contracting weakly branched group. It was first
studied in \cite{MR2140091}. It could have been defined as \texttt{FRGroup("a={\textless}c,a{\textgreater}(1,2)","b={\textless}b,a{\textgreater}(1,2)","c={\textless}b,c{\textgreater}")}, but is rather defined using Mealy elements. 

 It has relators $abc$, $[a^2c,[a,c]]$, $[cab,a^{-1}c^{-1}ab]$ and $[ac^2,c^{-1}b^{-1}c^2]$ among others. 

 It admits an endomorphism on its derived subgroup. Indeed \texttt{FRElement(1,Comm(a,b))=Comm(c\texttt{\symbol{94}}-1,b/a)}, \texttt{FRElement(1,Comm(a,c))=Comm(a/b,c)}, \texttt{FRElement(1,Comm(b,c))=Comm(c,(a/b)\texttt{\symbol{94}}c)}. }

 

\subsection{\textcolor{Chapter }{MamaghaniGroup}}
\logpage{[ 10, 1, 25 ]}\nobreak
\hyperdef{L}{X7C958AB78484E256}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MamaghaniGroup\index{MamaghaniGroup@\texttt{MamaghaniGroup}}
\label{MamaghaniGroup}
}\hfill{\scriptsize (global variable)}}\\


 This group was studied in \cite{MR2139928}. It is fractal, but not contracting. It could have been defined as \texttt{FRGroup("a={\textless},b{\textgreater}(1,2)","b={\textless}a,c{\textgreater}","c={\textless}a,a\texttt{\symbol{94}}-1{\textgreater}(1,2)")]]{\textgreater}}, but is rather defined using Mealy elements. It partially admits branching on
its subgroup \texttt{Subgroup(G,[a\texttt{\symbol{94}}2,(a\texttt{\symbol{94}}2)\texttt{\symbol{94}}b,(a\texttt{\symbol{94}}2)\texttt{\symbol{94}}c])}, and, setting \texttt{x=Comm(a\texttt{\symbol{94}}2,b)}, on \texttt{Subgroup(G,[x,x\texttt{\symbol{94}}a,x\texttt{\symbol{94}}b,x\texttt{\symbol{94}}(b*a),x\texttt{\symbol{94}}(b/a)])}. One has \texttt{FRElement(1,x)=(x\texttt{\symbol{94}}-1)\texttt{\symbol{94}}b/x}. }

 

\subsection{\textcolor{Chapter }{WeierstrassGroup}}
\logpage{[ 10, 1, 26 ]}\nobreak
\hyperdef{L}{X86D952E8784E4D97}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WeierstrassGroup\index{WeierstrassGroup@\texttt{WeierstrassGroup}}
\label{WeierstrassGroup}
}\hfill{\scriptsize (global variable)}}\\


 This is the iterated monodromy group associated with the Weierstrass $\wp$-function. 

 Some relators in the group: $(atbt)^4$, $((atbt)(bt)^4n)^4$, $((atbt)^2(bt)^4n)^2$. 

 Set $x=[a,t]$, $y=[b,t]$, $z=[c,t]$, and $w=[x,y]$. Then $G'=\langle x,y,z\rangle$ of index 8, and $\gamma_3=\langle[\{x,y,z\},\{a,b,c\}]\rangle$ of index 32, and $\gamma_4=G''=\langle w\rangle^G$, of index 256, and $G''>(G'')^4$ since $[[t^a,t],[t^b,t]]=(w,1,1,1)$. 

 The Schreier graph is obtained in the complex plane as the image of a $2^n\times 2^n$ lattice in the torus, via Weierstrass's $\wp$-function. 

 The element $at$ has infinite order. 

 $[c,t,b][b,t,c][a,t,c][c,t,a]$ has order 2, and belongs to $G''$; so there exist elements of arbitrary large finite order in the group.  }

 

\subsection{\textcolor{Chapter }{FRAffineGroup}}
\logpage{[ 10, 1, 27 ]}\nobreak
\hyperdef{L}{X86B124758135DFBD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRAffineGroup({\slshape d, R, u[, transversal]})\index{FRAffineGroup@\texttt{FRAffineGroup}}
\label{FRAffineGroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The \mbox{\texttt{\slshape d}}-dimensional affine group over \mbox{\texttt{\slshape R}}.



 This function constructs a new FR group \texttt{G}, which is finite-index subgroup of the \mbox{\texttt{\slshape d}}-dimensional affine group over $R_u$, the local ring over \mbox{\texttt{\slshape R}} in which all non-multiples of \mbox{\texttt{\slshape u}} are invertible. Since no generators of \texttt{G} are known, \texttt{G} is in fact returned as a full SC group; only its attribute \texttt{Correspondence(G)}, which is a homomorphism from $GL_{d+1}(R_u)$ to \texttt{G}, is relevant. 

 The affine group can also be described as a subgroup of $GL_{d+1}(R_u)$, consisting of those matrices $M$ with $M_{i,d+1}=0$ and $M_{d+1,d+1}=1$. The finite-index subgroup is defined by the conditions $u|M_{i,j}$ for all $j<i$. 

 The only valid arguments are \texttt{R=Integers} and \texttt{R=PolynomialRing(S)} for a finite ring \texttt{S}. The alphabet of the affine group is $R/RuR$; an explicit transversal of $RuR$ be specified as last argument. 

 The following examples construct the "Baumslag-Solitar group" $\mathbb Z[\frac12]\rtimes_2\mathbb Z$ first introduced in \cite{MR0142635}, the "lamplighter group" $(\mathbb Z/2)\wr\mathbb Z$, and a 2-dimensional affine group. Note that the lamplighter group may also
be defined via \texttt{CayleyGroup} (\ref{CayleyGroup}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> A := FRAffineGroup(1,Integers,3);
  <self-similar group over [ 1 .. 3 ]>
  gap> f := Correspondence(A);
  MappingByFunction( ( Integers^
  [ 2, 2 ] ), <self-similar group over [ 1 .. 3 ]>, function( mat ) ... end )
  gap> BaumslagSolitar := Group([[2,0],[0,1]]^f,[[1,0],[1,1]]^f);
  <self-similar group over [ 1 .. 3 ] with 2 generators>
  gap> BaumslagSolitar.2^BaumslagSolitar.1=BaumslagSolitar.2^2;
  true
  gap> R := PolynomialRing(GF(2));;
  gap> A := FRAffineGroup(1,R,R.1);;
  gap> f := Correspondence(A);;
  gap> Lamplighter := Group(([[1+R.1,0],[0,1]]*One(R))^f,([[1,0],[1,1]]*One(R))^f);
  <self-similar group over [ 1 .. 2 ] with 2 generators>
  gap> Lamplighter = CayleyGroup(Group((1,2)));
  true
  gap> StructureDescription(Group(Lamplighter.2,Lamplighter.2^Lamplighter.1));    
  "C2 x C2"
  gap> ForAll([1..10],i->IsOne(Comm(Lamplighter.2,Lamplighter.2^(Lamplighter.1^i))));
  true
  gap> A := FRAffineGroup(2,Integers,2);;
  gap> f := Correspondence(A);;
  gap> a := [[1,4,0],[2,3,0],[1,0,1]];
  [ [ 1, 4, 0 ], [ 2, 3, 0 ], [ 1, 0, 1 ] ]
  gap> b := [[1,2,0],[4,3,0],[0,1,1]];
  [ [ 1, 2, 0 ], [ 4, 3, 0 ], [ 0, 1, 1 ] ]
  gap> Display(b^f);
      |   1      2
  ----+------+------+
    a |  b,1    c,2
    b |  d,2    e,1
    c |  a,2    f,1
  ...
   bh | cb,1   be,2
   ca | bd,1   bf,2
   cb | ae,2   bh,1
  ----+------+------+
  Initial state:  a
  gap> a^f*b^f=(a*b)^f;
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{CayleyGroup}}
\logpage{[ 10, 1, 28 ]}\nobreak
\hyperdef{L}{X7CFBE31A78F2681B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CayleyGroup({\slshape G})\index{CayleyGroup@\texttt{CayleyGroup}}
\label{CayleyGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CayleyMachine({\slshape G})\index{CayleyMachine@\texttt{CayleyMachine}}
\label{CayleyMachine}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LamplighterGroup({\slshape G})\index{LamplighterGroup@\texttt{LamplighterGroup}}
\label{LamplighterGroup}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The Cayley machine/group of the group \mbox{\texttt{\slshape G}}.



 The \emph{Cayley machine} of a group \mbox{\texttt{\slshape G}} is a machine with alphabet and stateset equal to \mbox{\texttt{\slshape G}}, and with output and transition functions given by multiplication in the
group, in the order \texttt{state*letter}. 

 The second function constructs a new FR group $CG$, which acts on \texttt{[1..Size(G)]}. Its generators are in bijection with the elements of \mbox{\texttt{\slshape G}}, and have as output the corresponding permutation of \mbox{\texttt{\slshape G}} induced by right multiplication, and as transitions all elements of \mbox{\texttt{\slshape G}}; see \texttt{CayleyMachine}. This construction was introduced in \cite{MR2197829}. 

 If \mbox{\texttt{\slshape G}} is an abelian group, $CG$ is the wreath product $G\wr\mathbb Z$; it is created by the constructor \texttt{LamplighterGroup(IsFRGroup,G)}. 

 The attribute \texttt{Correspondence(CG)} is a list. Its first entry is a homomorphism from \mbox{\texttt{\slshape G}} into \texttt{CG}. Its second entry is the generator of \texttt{CG} that has trivial output. \texttt{CG} is generated \texttt{Correspondence(CG)[2]} and the image of \texttt{Correspondence(CG)[1]}. 

 In the example below, recall the definition of \texttt{Lamplighter} in the example of \texttt{FRAffineGroup} (\ref{FRAffineGroup}). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> L := CayleyGroup(Group((1,2)));
  CayleyGroup(Group( [ (1,2) ] ))
  gap> L=LamplighterGroup(IsFRGroup,CyclicGroup(2));
  true
  gap> (1,2)^Correspondence(L)[1];
  <Mealy element on alphabet [ 1, 2 ] with 2 states, initial state 1>
  gap> IsFinitaryFRElement(last); Display(last2);
  true
     |  1     2
  ---+-----+-----+
   a | b,2   b,1
   b | b,1   b,2
  ---+-----+-----+
  Initial state: a
\end{Verbatim}
 }

 }

 
\section{\textcolor{Chapter }{Examples of semigroups}}\logpage{[ 10, 2, 0 ]}
\hyperdef{L}{X81B82FA1811AAF8D}{}
{
 

\subsection{\textcolor{Chapter }{I2Machine}}
\logpage{[ 10, 2, 1 ]}\nobreak
\hyperdef{L}{X87541DA582705033}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{I2Machine\index{I2Machine@\texttt{I2Machine}}
\label{I2Machine}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{I2Monoid\index{I2Monoid@\texttt{I2Monoid}}
\label{I2Monoid}
}\hfill{\scriptsize (global variable)}}\\


 The Mealy machine $I_2$, and the monoid that it generates. This is the smallest Mealy machine
generating a monoid of intermediate word growth; see \cite{MR2194959}. 

 For sample calculations in this monoid see \texttt{SCSemigroup} (\ref{SCSemigroup}). }

 

\subsection{\textcolor{Chapter }{I4Machine}}
\logpage{[ 10, 2, 2 ]}\nobreak
\hyperdef{L}{X7B32ED3D8715FA4B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{I4Machine\index{I4Machine@\texttt{I4Machine}}
\label{I4Machine}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{I4Monoid\index{I4Monoid@\texttt{I4Monoid}}
\label{I4Monoid}
}\hfill{\scriptsize (global variable)}}\\


 The Mealy machine generating $I_4$, and the monoid that it generates. This is a very small Mealy machine
generating a monoid of intermediate word growth; see \cite{bartholdi-reznykov}. 

 For sample calculations in this monoid see \texttt{SCMonoid} (\ref{SCMonoid}). }

 }

 
\section{\textcolor{Chapter }{Bacher's determinant identities}}\label{bacher}
\logpage{[ 10, 3, 0 ]}
\hyperdef{L}{X7989134C83AF38AE}{}
{
 In his paper \cite{bacher}, Roland Bacher exhibits striking formulas for determinants of matrices
obtained from binomial coefficients. 

 The general construction is as follows: let $P$ be an infinite matrix, and let $P(n)$ be its upper $n\times n$ corner. To evaluate $\det P(n)$, decompose $P=LDR$ where $L,D,R$ are respectively lower triangular, diagonal, and upper triangular, with 1's on
the diagonals of $L$ and $R$. Then that determinant is the product of the first $n$ entries of $D$. 

 Bacher considers some natural examples of matrices arising from binomial
coefficients, and notes that the matrix $P$ is the limit of a convergent vector element (see \texttt{IsConvergent} (\ref{IsConvergent})). He also notes that the decomposition $P=LDR$ may be achieved within vector elements. 

 As a first example, consider the $n\times n$ matrix $P(n)$ with coefficients $P_{s,t}={s+t \choose s}\pmod 2$. Here and below, indices start at 0. Let also $ds(n)$ denote the digit-sum of the integer $n$. Then 
\[\det(P(n))=\cases{ (-1)^{n/2} & if $n$ is even,\cr (-1)^{(n-1)/2+ds((n-1)/2)}
& if $n$ is odd.} \]
 For the proof, note that $P$ is a convergent infinite matrix; it may be presented as a self-similar linear
element by \texttt{FRAlgebra("P=[[P,P],[P,0]]")}. It then suffices to construct an LR decomposition of $P$ within FR vector elements, following Bacher: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> AssignGeneratorVariables(FRAlgebra(Rationals,
      "P=[[P,P],[P,0]]","L=[[L,0],[L,L]]","D=[[D,0],[0,-D]]"));
  gap> L*D*TransposedFRElement(L)=P;
  true
\end{Verbatim}
 and to analyse the elements of the diagonal matrix $D$. 

 For a more complicated example, let $v_2$ denote 2-valuation of a rational, and construct the $n\times n$ matrix $V(n)$ with coefficients $V_{s,t}=i^{v_2({s+t \choose s})}$. Then 
\[\det(V(n))=\det(P(n))\prod_{k=1}^{n-1}(1-f(k)i),\]
 where $f(k)$ is the regular paper-folding sequence defined by $f(2^n)=1$ and $f(2^n+a)=-f(2^n-a)$ for $1\le a<2^n$. 

 This is again proved by noticing that $V$ is a corner in a self-similar element, namely 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> AssignGeneratorVariables(FRAlgebra(GaussianRationals,
       "V1=[[V1,V2],[V2,E(4)*V1]]",
       "V2=[[V1,-E(4)*V1+(1+E(4))*V2],[-E(4)*V1+(1+E(4))*V2,-V1]]"));
  gap> Activity(V1,3)=
       List([0..7],s->List([0..7],t->E(4)^ValuationInt(Binomial(s+t,s),2)));
  true
\end{Verbatim}
 The LR decomposition of $V=V1$ can be checked as follows: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> AssignGeneratorVariables(FRAlgebra(GaussianRationals,
       "L1=[[L1,0],[L3,L4]]",
       "L2=[[0,-E(4)*L2],[-L1+L3,-E(4)*L2-E(4)*L4]]:0",
       "L3=[[L1,L2],[-E(4)*L1+(1+E(4))*L3,L2+(1+E(4))*L4]]",
       "L4=[[L1,0],[(1-E(4))*L1+E(4)*L3,L4]]",
       "D1=[[D1,0],[0,D2]]",
       "D2=[[D3,0],[0,2*D1-D2+2*D3]]:-1+E(4)",
       "D3=[[D3,0],[0,-D2]]:-1+E(4)"));
  gap> L1*D1*TransposedFRElement(L1)=V1;
  true
\end{Verbatim}
 The LR decomposition can also, in favourable situations, be discovered by \textsf{FR} through the command \texttt{LDUDecompositionFRElement} (\ref{LDUDecompositionFRElement}). This approach will be followed below. 

 For the next example, consider "Beeblebrox reduction" $\beta(4k\pm1)=\pm1,\beta(2k)=0$, and construct the $n\times n$ matrix $Z(n)$ (named after Zaphod Beeblebrox) with coefficients $Z_{s,t}=\beta({s+t \choose s})$. Then 
\[\det(Z(n))=\prod_{k=1}^{n-1}g(k),\]
 where $g(\sum a_i2^i)=(-1)^{a_0}3^{\#\{i:a_i=a_{i+1}=1\}-\#\{i:a_i\neq a_{i+1}=1\}}$ with all $a_i\in\{0,1\}$. 

 This is again proved by noticing that $Z$ is a corner in a self-similar element, namely 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> beta := n->Jacobi(-1,n)*(n mod 2);;
  gap> Zaphod := GuessVectorElement(List([0..7],i->List([0..7],j->beta(Binomial(i+j,j)))));
  <Linear element on alphabet Rationals^2 with 3-dimensional stateset>
  gap> Display(Zaphod);
   Rationals |    1     |    2     |
  -----------+----------+----------+
           1 |  1  0  0 |  0  1  0 |
             |  1  0  0 |  0  1  0 |
             |  1  0  0 |  0 -1  0 |
  -----------+----------+----------+
           2 |  0  0  1 |  0  0  0 |
             |  0  0 -1 |  0  0  0 |
             |  0  0  1 |  0  0  0 |
  -----------+----------+----------+
  Output:  1  1  1
  Initial state:  1  0  0
  gap> LDUDecompositionFRElement(guessZ);
  [ <Linear element on alphabet Rationals^2 with 4-dimensional stateset>,
    <Linear element on alphabet Rationals^2 with 2-dimensional stateset>,
    <Linear element on alphabet Rationals^2 with 4-dimensional stateset> ]
  gap> Display(last[2]);
   Rationals |    1    |    2    |
  -----------+---------+---------+
           1 |   1   0 |   0   0 |
             |   3   0 |   0   0 |
  -----------+---------+---------+
           2 |   0   0 |   0   1 |
             |   0   0 |   0 1/3 |
  -----------+---------+---------+
  Output:   1  -1
  Initial state:   1   0
\end{Verbatim}
 and now the recursion read on this diagonal self-similar matrix gives
immediately Bacher's recursion for $\det(Z(n))$. 

 Bacher notes that the group generated by $a=L_1,b=L_2/2,c=L_3,d=L_4$ in the last example may be of interest. A quick check produces the following
relations (slightly rewritten): 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> AssignGeneratorVariables(FRAlgebra(Rationals,
       "a=[[a,0],[c,d]]","b=[[-1/3*a,2*b],[1/3*c,d]]",
       "c=[[a,2*b],[c,d]]","d=[[a,0],[1/3*c,d]]"));
  gap> g := Group(List([a,b,c,d], x->Activity(x,3)));
  <matrix group with 4 generators>
  gap> FindShortGroupRelations(g,10);
  [ b*d^-1*c*a^-1,
    c*a^-1*c*a^-1,
    c*a*d^-1*a^-1*d^2*a^-1*b^-1,
    c*a*d^-1*c^-1*b*d*a^-1*b^-1,
    c*d*a^-2*d*a*d^-1*b^-1,
    c*a^2*d^-1*a^-2*d*a*d*a^-2*b^-1,
    d^2*a*d^-2*b^-1*c*a*d*a^-3,
    c*d*a*d^-2*a^-1*d*a*d*a^-2*b^-1 ]
\end{Verbatim}
 Consider next the "triangular Beeblebrox matrix" with entries $L_{s,t}=\beta({s \choose t})$. The recurrence is now given by 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> A := FRAlgebra(Rationals,
       "L1=[[L1,0],[L2,L3]]",
       "L2=[[L1,0],[L2,-L3]]",
       "L3=[[L1,0],[-L2,L3]]");
  <self-similar algebra on alphabet Rationals^2 with 3 generators>
\end{Verbatim}
 and it is striking that $A$ is a graded algebra, with $L_1,L_2,L_3$ homogeneous of degree 1, and each homogeneous component is 3-dimensional; all
of $L_1,L_2,L_3$ are invertible (with inverses have degree $-1$), and generate a group that admits a faithful $3\times 3$ linear representation. As a final example, Bacher considers the "Jacobi
character" $\chi(8{\ensuremath{\mathbb Z}}\pm1)=1,\chi(8{\ensuremath{\mathbb
Z}}\pm3)=-1,\chi(2{\ensuremath{\mathbb Z}})=0$, and the associated matrix $J_{s,t}=\chi({s+t \choose s})$. He gives an easily-computed, but complicated formula for $\det(J(n))$. We can recover this formula, as before, by "guessing" an LR decomposition
for $J$, which is self-similar and convergent: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> chi := function(x)
          if x mod 8 in [1,7] then return 1;
          elif x mod 8 in [3,5] then return -1;
          else return 0; fi;
       end;;
  gap> m := List([0..63],i->List([0..63],j->chi(Binomial(i+j,j))));;
  gap> J := GuessVectorElement(m,2);
  <Linear element on alphabet Rationals^2 with 9-dimensional stateset>
  gap> LDUDecompositionFRElement(J);
  [ <Linear element on alphabet Rationals^2 with 20-dimensional stateset>,
    <Linear element on alphabet Rationals^2 with 4-dimensional stateset>,
    <Linear element on alphabet Rationals^2 with 20-dimensional stateset> ]
  gap> time;
  26869
  gap> Display(last2[2]);
   Rationals |        1        |        2        |
  -----------+-----------------+-----------------+
           1 |   1   0   0   0 |   0   0   0   0 |
             |   0   0   1   0 |   0   0   0   0 |
             |   3   0   0   0 |   0   0   0   0 |
             |   0   0   3   0 |   0   0   0   0 |
  -----------+-----------------+-----------------+
           2 |   0   0   0   0 |   0   1   0   0 |
             |   0   0   0   0 |   0   0   0   1 |
             |   0   0   0   0 |   0 1/3   0   0 |
             |   0   0   0   0 |   0   0   0 1/3 |
  -----------+-----------------+-----------------+
  Output:   1  -1   3 -1/3
  Initial state:   1   0   0   0
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{VH groups}}\label{vhgroups}
\logpage{[ 10, 4, 0 ]}
\hyperdef{L}{X7C4A51947E1609A8}{}
{
 [!!! introduction to do] 

\subsection{\textcolor{Chapter }{VHStructure}}
\logpage{[ 10, 4, 1 ]}\nobreak
\hyperdef{L}{X7E0071D4838B239D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{VHStructure({\slshape g})\index{VHStructure@\texttt{VHStructure}}
\label{VHStructure}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsVHGroup({\slshape g})\index{IsVHGroup@\texttt{IsVHGroup}}
\label{IsVHGroup}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
A VH-structure for the group \mbox{\texttt{\slshape g}}.



 A \emph{VH-structure} on a group \mbox{\texttt{\slshape g}} is a partition of the generators in two sets $V,H$ such that every relator of \mbox{\texttt{\slshape g}} is of the form $vhv'h'$, and such that for all $v\in V,h\in H$ there exist unique $v'\in V,h'\in H$ such that $vhv'h'=1$. 

 The VH structure is stored as a record with fields \texttt{v,h} containing lists of generators, and integer matrices \texttt{transitions,output} such that \texttt{transitions[v][h']=v'} and \texttt{output[v][h']=h}. 

 The filter recognizes groups with a VH structure. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{VerticalAction}}
\logpage{[ 10, 4, 2 ]}\nobreak
\hyperdef{L}{X7F852A357D7E2E76}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{VerticalAction({\slshape g})\index{VerticalAction@\texttt{VerticalAction}}
\label{VerticalAction}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{HorizontalAction({\slshape g})\index{HorizontalAction@\texttt{HorizontalAction}}
\label{HorizontalAction}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
A homomorphism to an FR group.



 A group with VH structure admits a \emph{vertical action} of its subgroup $\langle V\rangle$; this is the group generated by the automaton \texttt{MealyMachine(trans,out)}. The function returns the group homomorphism from the subgroup $\langle V\rangle$ to that FR group. 

 The horizontal action is that of the dual automaton (see \texttt{DualMachine} (\ref{DualMachine})). 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{VHGroup}}
\logpage{[ 10, 4, 3 ]}\nobreak
\hyperdef{L}{X86B1C2F079FE8D82}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{VHGroup({\slshape l1, l2, ...})\index{VHGroup@\texttt{VHGroup}}
\label{VHGroup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
A new VH group.



 This function constructs the VH group specified by the squares \mbox{\texttt{\slshape l1, l2, ...}}. Each \mbox{\texttt{\slshape li}} is a list of length 4, of the form \texttt{[v,h,v',h']}. Here the entries are indices of vertical, respectively horizontal
generators, if positive; and their inverses if negative. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsIrreducibleVHGroup}}
\logpage{[ 10, 4, 4 ]}\nobreak
\hyperdef{L}{X7D1FCB877D1B96EA}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsIrreducibleVHGroup({\slshape g})\index{IsIrreducibleVHGroup@\texttt{IsIrreducibleVHGroup}}
\label{IsIrreducibleVHGroup}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
Whether \mbox{\texttt{\slshape g}} is an irreducible lattice.



 A VH group is \emph{irreducible} if its projections on both trees is dense. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{MaximalSimpleSubgroup}}
\logpage{[ 10, 4, 5 ]}\nobreak
\hyperdef{L}{X84DB7FA4846075A7}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MaximalSimpleSubgroup({\slshape g})\index{MaximalSimpleSubgroup@\texttt{MaximalSimpleSubgroup}}
\label{MaximalSimpleSubgroup}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
A maximal simple subgroup of \mbox{\texttt{\slshape g}}, if possible.



 A VH group is never simple, but in favourable cases it admits a finite-index
simple subgroup, see \cite{MR1446574}. This function attempts to construct such a subgroup. It returns \texttt{fail} if no such subgroup can be found. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  true
\end{Verbatim}
 }

 }

 }

 
\chapter{\textcolor{Chapter }{FR implementation details}}\logpage{[ 11, 0, 0 ]}
\hyperdef{L}{X86D6616E868AF75C}{}
{
 \textsf{FR} creates new categories for the various objects considered in the package. The
first category is \texttt{FRObject}; all objects are in this category, and have an \texttt{Alphabet} method. 

 There are two categories below: \texttt{FRMachine} and \texttt{FRElement}. An \texttt{FRMachine} must have a \texttt{StateSet}, and methods for \texttt{Output} and a \texttt{Transition}. An \texttt{FRElement} must have an underlying \texttt{FRMachine} and \texttt{InitialState}, and \texttt{Output} and a \texttt{Transition} that use the initial state. 

 A self-similar group is simply a collections category of FR elements which is
also a group. 
\section{\textcolor{Chapter }{The family of FR objects}}\logpage{[ 11, 1, 0 ]}
\hyperdef{L}{X79719CD17A948933}{}
{
 All FR objects have an associated \texttt{AlphabetOfFRObject} (\ref{AlphabetOfFRObject}). 

\subsection{\textcolor{Chapter }{FRMFamily}}
\logpage{[ 11, 1, 1 ]}\nobreak
\hyperdef{L}{X7F5497A47F8C81DD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRMFamily({\slshape obj})\index{FRMFamily@\texttt{FRMFamily}}
\label{FRMFamily}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
the family of FR machines on alphabet \mbox{\texttt{\slshape obj}}.



 The family of an FR object is the arity of the tree on which elements cat act;
in other words, there is one family for each alphabet. }

 

\subsection{\textcolor{Chapter }{FREFamily}}
\logpage{[ 11, 1, 2 ]}\nobreak
\hyperdef{L}{X7C6A63427F6DB4C6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FREFamily({\slshape obj})\index{FREFamily@\texttt{FREFamily}}
\label{FREFamily}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
the family of FR elements on alphabet \mbox{\texttt{\slshape obj}}.



 The family of an FR object is the arity of the tree on which elements cat act;
in other words, there is one family for each alphabet. 

 The argument may be an FR machine, an alphabet, or a family of FR machines. }

 

\subsection{\textcolor{Chapter }{AlphabetOfFRObject}}
\logpage{[ 11, 1, 3 ]}\nobreak
\hyperdef{L}{X7BC9CD3685C26823}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AlphabetOfFRObject({\slshape obj})\index{AlphabetOfFRObject@\texttt{AlphabetOfFRObject}}
\label{AlphabetOfFRObject}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
the alphabet associated with \mbox{\texttt{\slshape obj}}.



 This command applies to the family of any FR object, or to the object
themselves. Alphabets are returned as lists, and in pratice are generally of
the form \texttt{[1..n]}. }

 

\subsection{\textcolor{Chapter }{AsPermutation (FR object)}}
\logpage{[ 11, 1, 4 ]}\nobreak
\hyperdef{L}{X793E0E1283BE7C73}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsPermutation({\slshape o})\index{AsPermutation@\texttt{AsPermutation}!FR object}
\label{AsPermutation:FR object}
}\hfill{\scriptsize (method)}}\\


 This method takes as argument an FR object \mbox{\texttt{\slshape o}}: machine, element, or group, and produces an equivalent object whose outputs
are permutations. In particular, it converts Mealy machines from domain
representation to int representation. 

 If this is not possible, the method returns \texttt{fail}. }

 

\subsection{\textcolor{Chapter }{AsTransformation (FR object)}}
\logpage{[ 11, 1, 5 ]}\nobreak
\hyperdef{L}{X7B41902D87A48EDB}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AsTransformation({\slshape o})\index{AsTransformation@\texttt{AsTransformation}!FR object}
\label{AsTransformation:FR object}
}\hfill{\scriptsize (method)}}\\


 This method takes as argument an FR object \mbox{\texttt{\slshape o}}: machine, element, or group, and produces an equivalent object whose outputs
are transformations. In particular, it converts Mealy machines from domain
representation to int representation. 

 Since transformations can never be inverted by \textsf{GAP}, even when they are invertible, this function returns a monoid when applied
to a full SC group. }

 }

 
\section{\textcolor{Chapter }{Filters for \texttt{FRObject}s}}\logpage{[ 11, 2, 0 ]}
\hyperdef{L}{X856A3AD87C93FC1F}{}
{
 

\subsection{\textcolor{Chapter }{IsGroupFRMachine}}
\logpage{[ 11, 2, 1 ]}\nobreak
\hyperdef{L}{X7CC0BFD67CE7060E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsGroupFRMachine({\slshape obj})\index{IsGroupFRMachine@\texttt{IsGroupFRMachine}}
\label{IsGroupFRMachine}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsMonoidFRMachine({\slshape obj})\index{IsMonoidFRMachine@\texttt{IsMonoidFRMachine}}
\label{IsMonoidFRMachine}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsSemigroupFRMachine({\slshape obj})\index{IsSemigroupFRMachine@\texttt{IsSemigroupFRMachine}}
\label{IsSemigroupFRMachine}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is an FR machine whose stateset is a free group/monoid/semigroup.



 This function is the acceptor for those functionally recursive machines whose
stateset (accessible via \texttt{StateSet} (\ref{StateSet:FR machine})) is a free group, monoid or semigroup. The generating set of its stateset is
accessible via \texttt{GeneratorsOfFRMachine} (\ref{GeneratorsOfFRMachine}). }

 

\subsection{\textcolor{Chapter }{IsFRMachineStrRep}}
\logpage{[ 11, 2, 2 ]}\nobreak
\hyperdef{L}{X8157AE587CBA24C4}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFRMachineStrRep({\slshape obj})\index{IsFRMachineStrRep@\texttt{IsFRMachineStrRep}}
\label{IsFRMachineStrRep}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is a standard (group,monoid,semigroup) FR machine.



 There is a free object \texttt{free}, of rank $N$, a list \texttt{transitions} of length $N$, each entry a list, indexed by the alphabet, of elements of \texttt{free}, and a list \texttt{output} of length \texttt{N} of transformations or permutations of the alphabet. }

 

\subsection{\textcolor{Chapter }{IsMealyMachine}}
\logpage{[ 11, 2, 3 ]}\nobreak
\hyperdef{L}{X79C2395A7D65214B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsMealyMachine({\slshape obj})\index{IsMealyMachine@\texttt{IsMealyMachine}}
\label{IsMealyMachine}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is a Mealy machine.



 This function is the acceptor for the \emph{Mealy machine} subcategory of \emph{FR machine}s. }

 

\subsection{\textcolor{Chapter }{IsMealyElement}}
\logpage{[ 11, 2, 4 ]}\nobreak
\hyperdef{L}{X7C86614187606A4C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsMealyElement({\slshape obj})\index{IsMealyElement@\texttt{IsMealyElement}}
\label{IsMealyElement}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is a Mealy element.



 This function is the acceptor for the \emph{Mealy element} subcategory of \emph{FR element}s. }

 

\subsection{\textcolor{Chapter }{IsMealyMachineIntRep}}
\logpage{[ 11, 2, 5 ]}\nobreak
\hyperdef{L}{X78E206B28015A395}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsMealyMachineIntRep({\slshape obj})\index{IsMealyMachineIntRep@\texttt{IsMealyMachineIntRep}}
\label{IsMealyMachineIntRep}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is a Mealy machine in integer representation.



 A Mealy machine in \emph{integer} representation has components \texttt{nrstates}, \texttt{transitions}, \texttt{output} and optionally \texttt{initial}. 

 Its stateset is \texttt{[1..nrstates]}, its transitions is a matrix with \texttt{transitions[s][x]} the transition from state \texttt{s} with input \texttt{x}, its output is a list of transformations or permutations, and its initial
state is an integer. }

 

\subsection{\textcolor{Chapter }{IsMealyMachineDomainRep}}
\logpage{[ 11, 2, 6 ]}\nobreak
\hyperdef{L}{X7AE5B4257E2DB7E6}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsMealyMachineDomainRep({\slshape obj})\index{IsMealyMachineDomainRep@\texttt{IsMealyMachineDomainRep}}
\label{IsMealyMachineDomainRep}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is a Mealy machine in domain representation.



 A Mealy machine in \emph{domain} representation has components \texttt{states}, \texttt{transitions}, \texttt{output} and optionally \texttt{initial}. 

 Its states is a domain, its transitions is a function with \texttt{transitions(s,x)} the transition from state \texttt{s} with input \texttt{x}, its output is a function with \texttt{output(s,x)} the output from input \texttt{x} in state \texttt{s}, and its initial state is an elemnent of \texttt{states}. }

 

\subsection{\textcolor{Chapter }{IsVectorFRMachineRep}}
\logpage{[ 11, 2, 7 ]}\nobreak
\hyperdef{L}{X8087EE9F79E8E339}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsVectorFRMachineRep({\slshape obj})\index{IsVectorFRMachineRep@\texttt{IsVectorFRMachineRep}}
\label{IsVectorFRMachineRep}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is a vector machine



 A \emph{vector machine} is a representation of a linear machine by a finite-dimensional vector space
(implicit in the structure), a transition tensor (represented as a matrix of
matrices), and an output vector (represented as a list). }

 

\subsection{\textcolor{Chapter }{IsAlgebraFRMachineRep}}
\logpage{[ 11, 2, 8 ]}\nobreak
\hyperdef{L}{X7859869E7FEDA49F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsAlgebraFRMachineRep({\slshape obj})\index{IsAlgebraFRMachineRep@\texttt{IsAlgebraFRMachineRep}}
\label{IsAlgebraFRMachineRep}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is an algebra machine



 An \emph{algebra machine} is a representation of a linear machine by a finitely generated free algebra,
a tensor of transitions, indexed by generator index and two alphabet indices,
and an output vector, indexed by a generator index. 

 The transition tensor's last two entries are the 0 and 1 matrix over the free
algebra, and the output tensor's last two entries are the 0 and 1 elements of
the left acting domain. }

 

\subsection{\textcolor{Chapter }{IsLinearFRMachine}}
\logpage{[ 11, 2, 9 ]}\nobreak
\hyperdef{L}{X877B1EBD80170001}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsLinearFRMachine({\slshape obj})\index{IsLinearFRMachine@\texttt{IsLinearFRMachine}}
\label{IsLinearFRMachine}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is a linear machine.



 This function is the acceptor for the \emph{linear machine} subcategory of \emph{FR machine}s. }

 

\subsection{\textcolor{Chapter }{IsLinearFRElement}}
\logpage{[ 11, 2, 10 ]}\nobreak
\hyperdef{L}{X823F46A67D458AAD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsLinearFRElement({\slshape obj})\index{IsLinearFRElement@\texttt{IsLinearFRElement}}
\label{IsLinearFRElement}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is a linear element.



 This function is the acceptor for the \emph{linear element} subcategory of \emph{FR element}s. }

 

\subsection{\textcolor{Chapter }{IsFRElement}}
\logpage{[ 11, 2, 11 ]}\nobreak
\hyperdef{L}{X7966F9B982B1DFE1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFRElement({\slshape obj})\index{IsFRElement@\texttt{IsFRElement}}
\label{IsFRElement}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is an FR element.



 This function is the acceptor for the \emph{functionally recursive element} category. 

 It implies that \mbox{\texttt{\slshape obj}} has an underlying FR machine, may act on sequences, and has a recursive \texttt{DecompositionOfFRElement} (\ref{DecompositionOfFRElement}). }

 

\subsection{\textcolor{Chapter }{IsFRObject}}
\logpage{[ 11, 2, 12 ]}\nobreak
\hyperdef{L}{X785D09F27DBDF6A8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFRObject({\slshape obj})\index{IsFRObject@\texttt{IsFRObject}}
\label{IsFRObject}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is an FR machine or element.



 This function is the acceptor for the most general FR category (which splits
up as \texttt{IsFRMachine} (\ref{IsFRMachine}) and \texttt{IsFRElement} (\ref{IsFRElement})). 

 It implies that \mbox{\texttt{\slshape obj}} has an attribute \texttt{AlphabetOfFRObject} (\ref{AlphabetOfFRObject}). }

 

\subsection{\textcolor{Chapter }{IsFRMachine}}
\logpage{[ 11, 2, 13 ]}\nobreak
\hyperdef{L}{X7C22A1A28058F754}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFRMachine({\slshape obj})\index{IsFRMachine@\texttt{IsFRMachine}}
\label{IsFRMachine}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is an FR machine.



 This function is the acceptor for the \emph{functionally recursive machine} category. It splits up as \texttt{IsGroupFRMachine} (\ref{IsGroupFRMachine}), \texttt{IsSemigroupFRMachine} (\ref{IsSemigroupFRMachine}), \texttt{IsMonoidFRMachine} (\ref{IsMonoidFRMachine}) and \texttt{IsMealyMachine} (\ref{IsMealyMachine})). 

 It implies that \mbox{\texttt{\slshape obj}} has attributes \texttt{StateSet} (\ref{StateSet:FR machine}), \texttt{GeneratorsOfFRMachine} (\ref{GeneratorsOfFRMachine}), and \texttt{WreathRecursion} (\ref{WreathRecursion}); the last two are usually not used for Mealy machines. }

 

\subsection{\textcolor{Chapter }{IsInvertible}}
\logpage{[ 11, 2, 14 ]}\nobreak
\hyperdef{L}{X83AEFB8184F4B023}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsInvertible({\slshape m})\index{IsInvertible@\texttt{IsInvertible}}
\label{IsInvertible}
}\hfill{\scriptsize (property)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape m}} is an invertible FR machine.



 This function accepts invertible FR machines, i.e. machines \mbox{\texttt{\slshape machine}} such that $(machine,q)$ is an invertible transformation of the alphabet for all $q$ in the stateset of \mbox{\texttt{\slshape machine}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> m := FRMachine([[[],[]]],[(1,2)]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ f1 ] )>
  gap> IsInvertible(m);
  true
  gap> m := FRMachine([[[],[]]],[[1,1]]);
  <FR machine with alphabet [ 1 .. 2 ] on Monoid( [ m1 ], ... )>
  gap> IsInvertible(m);
  false
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsFRGroup}}
\logpage{[ 11, 2, 15 ]}\nobreak
\hyperdef{L}{X81D717E187305F2A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFRGroup({\slshape obj})\index{IsFRGroup@\texttt{IsFRGroup}}
\label{IsFRGroup}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFRMonoid({\slshape obj})\index{IsFRMonoid@\texttt{IsFRMonoid}}
\label{IsFRMonoid}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFRSemigroup({\slshape obj})\index{IsFRSemigroup@\texttt{IsFRSemigroup}}
\label{IsFRSemigroup}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is a FR group/monoid/semigroup.



 These functions accept \emph{self-similar groups/monoids/semigroups}, i.e. groups/monoids/semigroups whose elements are FR elements. }

 

\subsection{\textcolor{Chapter }{IsFRAlgebra}}
\logpage{[ 11, 2, 16 ]}\nobreak
\hyperdef{L}{X853B16B381CB5366}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFRAlgebra({\slshape obj})\index{IsFRAlgebra@\texttt{IsFRAlgebra}}
\label{IsFRAlgebra}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFRAlgebraWithOne({\slshape obj})\index{IsFRAlgebraWithOne@\texttt{IsFRAlgebraWithOne}}
\label{IsFRAlgebraWithOne}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape obj}} is a FR algebra [with one].



 These functions accept \emph{self-similar algebras [with one]}, i.e. algebras whose elements are linear FR elements. }

 }

 
\section{\textcolor{Chapter }{Some of the algorithms implemented}}\logpage{[ 11, 3, 0 ]}
\hyperdef{L}{X7E97015E8153F782}{}
{
 Few calculations with infinite groups can be guaranteed to terminate --- and
especially to terminate within reasonable time. This section describes some of
the algorithms implemented in \textsf{FR}. 

\subsection{\textcolor{Chapter }{FRMachineRWS}}
\logpage{[ 11, 3, 1 ]}\nobreak
\hyperdef{L}{X84278D6F7AAD101F}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FRMachineRWS({\slshape m})\index{FRMachineRWS@\texttt{FRMachineRWS}}
\label{FRMachineRWS}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
A record containing a rewriting system for \mbox{\texttt{\slshape m}}.



 Elements of an FR machine are compared using a rewriting system, which records
all known relations among states of the machine. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> n := FRMachine(["a","b"],[[[],[2]],[[],[1]]],[(1,2),()]);
  <FR machine with alphabet [ 1 .. 2 ] on Group( [ a, b ] )>
  gap> FRMachineRWS(n);
  rec( rws := Knuth Bendix Rewriting System for Monoid( [ a^-1, a, b^-1, b
       ], ... ) with rules
      [ [ a^-1*a, <identity ...> ], [ a*a^-1, <identity ...> ],
        [ b^-1*b, <identity ...> ], [ b*b^-1, <identity ...> ] ],
    tzrules := [ [ [ 1, 2 ], [  ] ], [ [ 2, 1 ], [  ] ], [ [ 3, 4 ], [  ] ],
        [ [ 4, 3 ], [  ] ] ], letterrep := function( w ) ... end,
    pi := function( w ) ... end, reduce := function( w ) ... end,
    addgprule := function( w ) ... end, commit := function(  ) ... end,
    restart := function(  ) ... end )
\end{Verbatim}
 }

 
\subsection{\textcolor{Chapter }{Order of FR elements}}\logpage{[ 11, 3, 2 ]}
\hyperdef{L}{X84B4FF607DA18152}{}
{
 

 The order of an FR element \texttt{e} is computed as follows: the tree is traversed recursively, filling it as
follows. For each cycle of \texttt{e} on the first level, the product of the states on that cycle are computed. The
method continues recursively with that product, remembering the order of the
cycle. Once a state reappears in the traversal, \textsf{FR} determines if one instance of the state is in the subtree of the other, and if
so whether the top one was raised to a non-trivial power to yield the second
one as a state. If this happens, then \texttt{e} has infinite order. Otherwise, the least common multiple of the powers that
appeared in the traversal is returned. 

 This method is guaranteed to succeed if \texttt{e} is a bounded element. To improve chances of success, \textsf{FR} first computes whether \texttt{e} acts by vertex transformations belonging to an abelian group; and if so, if \texttt{e} is conjugate to an adding machine. In that case too, \texttt{e} has infinite order. }

 
\subsection{\textcolor{Chapter }{Membership in semigroups}}\logpage{[ 11, 3, 3 ]}
\hyperdef{L}{X847B4AFF809D2A56}{}
{
 The following algorithm is used to determine whether a Mealy element belongs
to a self-similar group. The corresponding problem of membership of an FR
element in a state-closed self-similar group can be much simpler, because an
FR element has an associated FR machine, all of whose states belong to the
group. 

 Assume the group is given by generators. \textsf{FR} attempts to express the given Mealy element as a product of generators. At the
same time, it constructs epimorphisms to finite groups. It is hoped that one
of these two processes will stop. 

 This amounts, in fact, to the following. Consider a group $G$ acting on a tree. It has a natural, profinite closure $\overline G$. The algorithm then attempts either to write an element $x$ as a product of generators of \mbox{\texttt{\slshape G}}, or to show that $x$ does not belong to $\overline G$. 

 There are groups $G$ such that $\overline G\setminus G$ contains Mealy machines. For these, the above algorithm will not terminate. 

 An additional refinement is implemented for bounded groups (see \texttt{IsBoundedFRSemigroup} (\ref{IsBoundedFRSemigroup})). The \texttt{Germs} (\ref{Germs}) of an element are computed, and compared to the germs of elements in the
group. 

 Finally, for a group that possesses self-similar data (see Section \ref{preimages}), very fast methods are implemented to recognize and express an FR element as
a product of generators. }

 
\subsection{\textcolor{Chapter }{Order of groups}}\logpage{[ 11, 3, 4 ]}
\hyperdef{L}{X7A0AC96784ACE0BE}{}
{
 

 The order of an FR group is computed as follows: if all generators are
finitary, then enumeration will succeed in computing the order. If the action
of the group is primitive, and it comes from a bireversible automaton, then
the Thompson-Wielandt theorem is tested against. This theorem states that, in
our context (a group acting on a rooted tree, coming from a larger group
acting transitively), if the group is finite then the stabilizer of a sphere
of radius 2 is a $p$-group; see \cite[Proposition 2.1.1]{MR1839488}. Then, \textsf{FR} attempts to find whether the group is level-transitive (in which case it would
be infinite). Finally, it attempts to enumerate the group's elements, testing
at the same time whether these elements have infinite order. 

 Needless to say, none except the first few steps are guaranteed to succeed. }

 
\subsection{\textcolor{Chapter }{Images and preimages of some groups in f.p. and l.p. groups}}\label{preimages}
\logpage{[ 11, 3, 5 ]}
\hyperdef{L}{X8329884F790E1542}{}
{
 Contracting, branched groups admit finite L-presentations (see \cite{MR2009317}), that is, presentations by finitely many generators, relators and
endomorphisms; the (usual) relators are the images of the given relators under
iteration by all endomorphisms. 

 Using the package \textsf{NQL}, it is possible to construct infinite nilpotent quotients of self-similar
groups, and perform fast computations in them. 

 It is possible to construct, algorithmically, such an L-presentation from a
self-similar groups; however, this algorithm has not been implemented yet,
mainly because efficiency issues would make it usable only in very few cases. 

 For groups with an isomorphism to an L-presented group (constructed by \texttt{IsomorphismLpGroup} (\ref{IsomorphismLpGroup})), a fast method expresses group elements as words in the L-presented group's
generators. It proceeds recursively on the decomposition of the element,
mapping elements that are expressible by short words over the nucleus (usually
length 1; length 3 is needed for the \texttt{BrunnerSidkiVieiraGroup} (\ref{BrunnerSidkiVieiraGroup})) to their value in the L-presented group, and using the presentation's
endomorphism to construct words with appropriate decompositions. 

 In particular, the algorithm will stop, returning \texttt{fail}, if during the recursion it reaches an element $x$ such that $x$ is a state of $x$ but $x$ does not belong to the nucleus. }

 
\subsection{\textcolor{Chapter }{Comparison of FR, Mealy, vector, and algebra elements}}\label{sorting}
\logpage{[ 11, 3, 6 ]}
\hyperdef{L}{X7F4247367D1EBEB9}{}
{
 FR and Mealy elements can be compared quite efficiently, as long as they are
distinct. The algorithm runs as follows: let the two elements be $x$ and $y$. Considering both in turn, \textsf{FR} constructs the first entries of minimal Mealy elements expressing $x$ and $y$; as soon as an output entry is distinct for $x$ and for $y$, the status of $x<y$ is determined; and similarly for transition entries. Finally, if either of $x$ or $y$ is finite-state and the entries were identical up to that step, then the
element with smallest stateset is considered smaller. 

 In this way, FR and Mealy elements can efficiently be compared. For Mealy
elements, it suffices to follow their internal data; while for FR elements,
this amounts to constructing Mealy elements approximating them to a sufficient
precision so that they can be compared as such. 

 The algorithm first tries to test its arguments for equality; this test is not
guaranteed to succeed. 

 A similar algorithm applies for linear elements. Here, one constructs vector
element approximations; and compares, for ever-increasing values of $i$, first the output vectors of basis state $i$; then the transitions from state $i$ to state $j$, for all $j\in\{1,\dots,i\}$; then the transitions from state $j$ to state $i$ for all $j\in\{1,\dots,i-1\}$. }

 
\subsection{\textcolor{Chapter }{Inverses of linear elements}}\logpage{[ 11, 3, 7 ]}
\hyperdef{L}{X81F95FEB7C72ABFF}{}
{
 It is probably difficult to compute the inverse of a vector element. The
following approach is used: to compute the inverse of $x$, large (scalar) matrix approximations of $x$ are computed; they are inverted using linear algebra; a vector element
representing this inverse is guessed; and the guess is checked. As long as
that check fails, larger approximations are computed. 

 Needless to say, this method need not succeed; for there are vector elements
that are invertible, but whose inverse is not a vector element. A good test
example appears in \cite{bacher}: consider the infinite matrix with 1's on the diagonal, and $\omega$ below the diagonal. This element admits an inverse if and only if $\omega$ is a root of unity. The complexity of the inverse grows as the degree of $\omega$ grows. Here is an illustation: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> bacher := function(n)
    local f;
    f := CyclotomicField(n);
    return VectorElement(f,One(f)*[[[[1,0],[0,0]],
          [[0,0],[0,1]]],[[[0,1],[0,0]],[[1,0],[0,0]]]],[One(f),E(n)],[One(f),Zero(f)]);
  end;;
  gap> Inverse(bacher(3));
  <Linear element on alphabet CF(3)^2 with 4-dimensional stateset>
  6 gap> Inverse(bacher(5));
  <Linear element on alphabet CF(5)^2 with 6-dimensional stateset>
\end{Verbatim}
 \begin{center}
\begin{tabular}{r|cccccccccc}$n$&
1&
2&
3&
4&
5&
6&
7&
8&
9&
10\\
dimension&
&
2&
4&
4&
6&
3&
5&
5&
8&
5\\
\hline
$n$&
11&
12&
13&
14&
15&
16&
17&
18&
19&
20\\
dimension&
?&
5&
?&
4&
6&
6&
?&
7&
?&
7\\
\hline
$n$&
22&
24&
26&
28&
30&
32&
34&
36&
38&
40\\
dimension&
?&
6&
?&
6&
?&
7&
?&
?&
?&
?\\
\end{tabular}\\[2mm]
\textbf{Table: }Dimension of states of inverse\end{center}

 }

 }

 }

 
\chapter{\textcolor{Chapter }{Miscellanea}}\logpage{[ 12, 0, 0 ]}
\hyperdef{L}{X785C6C0B80936CC8}{}
{
 
\section{\textcolor{Chapter }{Helpers}}\logpage{[ 12, 1, 0 ]}
\hyperdef{L}{X7E665607810488EE}{}
{
 

\subsection{\textcolor{Chapter }{maybe}}
\logpage{[ 12, 1, 1 ]}\nobreak
\hyperdef{L}{X7AF592A57A86A158}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{maybe\index{maybe@\texttt{maybe}}
\label{maybe}
}\hfill{\scriptsize (global variable)}}\\


 Some methods in \textsf{FR} search for an answer, either positive or negative, but fail to find one in
reasonable time. They then return the value \texttt{maybe}, which is a boolean that is neither true nor false. }

 

\subsection{\textcolor{Chapter }{ReturnMaybe}}
\logpage{[ 12, 1, 2 ]}\nobreak
\hyperdef{L}{X7FFD58887FB6D36D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ReturnMaybe({\slshape arg})\index{ReturnMaybe@\texttt{ReturnMaybe}}
\label{ReturnMaybe}
}\hfill{\scriptsize (function)}}\\


 This function, similar to \texttt{ReturnTrue} or \texttt{ReturnFalse}, returns the value \texttt{maybe} (\ref{maybe}). }

 

\subsection{\textcolor{Chapter }{TensorSum}}
\logpage{[ 12, 1, 3 ]}\nobreak
\hyperdef{L}{X844D3035877B5052}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TensorSum({\slshape objects, ...})\index{TensorSum@\texttt{TensorSum}}
\label{TensorSum}
}\hfill{\scriptsize (function)}}\\


 This function is similar in syntax to \texttt{DirectProduct} (\textbf{Reference: DirectProduct}), and delegates to \texttt{TensorSumOp}; its meaning depends on context, see e.g. \texttt{TensorSumOp} (\ref{TensorSumOp:FR Machines}). }

 

\subsection{\textcolor{Chapter }{TensorProductX}}
\logpage{[ 12, 1, 4 ]}\nobreak
\hyperdef{L}{X868A30347924CEDF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TensorProductX({\slshape objects, ...})\index{TensorProductX@\texttt{TensorProductX}}
\label{TensorProductX}
}\hfill{\scriptsize (function)}}\\


 This function is similar in syntax to \texttt{DirectProduct} (\textbf{Reference: DirectProduct}), and delegates to \texttt{TensorProductOp}; its meaning depends on context, see e.g. \texttt{TensorProductOp} (\ref{TensorProductOp:FR Machines}). }

 

\subsection{\textcolor{Chapter }{DirectSum}}
\logpage{[ 12, 1, 5 ]}\nobreak
\hyperdef{L}{X82AD6F187B550060}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DirectSum({\slshape objects, ...})\index{DirectSum@\texttt{DirectSum}}
\label{DirectSum}
}\hfill{\scriptsize (function)}}\\


 This function is similar in syntax to \texttt{DirectProduct} (\textbf{Reference: DirectProduct}), and delegates to \texttt{DirectSumOp}; its meaning depends on context, see e.g. \texttt{DirectSumOp} (\ref{DirectSumOp:FR Machines}). }

 

\subsection{\textcolor{Chapter }{PeriodicList}}
\logpage{[ 12, 1, 6 ]}\nobreak
\hyperdef{L}{X7B401DFE817D3927}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PeriodicList({\slshape preperiod[, period]})\index{PeriodicList@\texttt{PeriodicList}}
\label{PeriodicList}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PeriodicList({\slshape list, i})\index{PeriodicList@\texttt{PeriodicList}!period, looping point}
\label{PeriodicList:period, looping point}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PeriodicList({\slshape list, f})\index{PeriodicList@\texttt{PeriodicList}!list, function}
\label{PeriodicList:list, function}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CompressedPeriodicList({\slshape preperiod[, period]})\index{CompressedPeriodicList@\texttt{CompressedPeriodicList}}
\label{CompressedPeriodicList}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CompressedPeriodicList({\slshape list, i})\index{CompressedPeriodicList@\texttt{CompressedPeriodicList}!period, looping point}
\label{CompressedPeriodicList:period, looping point}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PrePeriod({\slshape list})\index{PrePeriod@\texttt{PrePeriod}}
\label{PrePeriod}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Period({\slshape list})\index{Period@\texttt{Period}}
\label{Period}
}\hfill{\scriptsize (operation)}}\\


 These functions manipulate \emph{periodic lists}, i.e. lists of infinite length such that elements follow a periodic order
after some point. 

 The first command creates a periodic list, specified by its preperiod and
period, which must both be lists. If the period is absent, this is actually a
finite list. 

 The second command creates a periodic list by decreeing that the entries after
the end of the list start again at position \mbox{\texttt{\slshape i}}. 

 The third command creates a list by applying function \mbox{\texttt{\slshape f}} to all elements of \mbox{\texttt{\slshape l}}. 

 The fourth and fifth command compress the newly created periodic list, see \texttt{CompressPeriodicList} (\ref{CompressPeriodicList}). 

 The sixth and seventh commands return respectively the preperiod and period of
a periodic list. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> l := PeriodicList([1],[2,3,4]);
  [ 1, / 2, 3, 4 ]
  gap> l[5];
  2
  gap> Add(l,100,3); l;
  [ 1, 2, 100, / 3, 4, 2 ]
  gap> Remove(l,5);
  4
  gap> l;
  [ 1, 2, 100, 3, / 2, 3, 4 ]
  gap> PrePeriod(l);
  [ 1, 2, 100, 3 ]
  gap> Period(l);
  [ 2, 3, 4 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{CompressPeriodicList}}
\logpage{[ 12, 1, 7 ]}\nobreak
\hyperdef{L}{X7AFE88F37FC58083}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CompressPeriodicList({\slshape l})\index{CompressPeriodicList@\texttt{CompressPeriodicList}}
\label{CompressPeriodicList}
}\hfill{\scriptsize (operation)}}\\


 This function compresses a periodic list, in replacing the period by a minimal
period, and shortening the preperiod. No value is returned, but the list \mbox{\texttt{\slshape l}} is modified. It remains equal (under \texttt{=}) to the original list. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> l := PeriodicList([1],[2,3,4,2,3,4]);
  [ 1, / 2, 3, 4, 2, 3, 4 ]
  gap> Add(l,4,5); l;
  [ 1, 2, 3, 4, 4, / 2, 3, 4, 2, 3, 4 ]
  gap> CompressPeriodicList(l);
  gap> l;
  [ 1, 2, 3, 4, / 4, 2, 3 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IsConfinal}}
\logpage{[ 12, 1, 8 ]}\nobreak
\hyperdef{L}{X7CA5FA3F7AF9BA3D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsConfinal({\slshape l, m})\index{IsConfinal@\texttt{IsConfinal}}
\label{IsConfinal}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if \mbox{\texttt{\slshape l}} and \mbox{\texttt{\slshape m}} are eventually equal.



 This function tests whether two lists are \emph{confinal}, i.e. whether, after removal of the same suitable number of elements from
both lists, they become equal. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> l := PeriodicList([1],[2,3,2,3]);
  [ 1, / 2, 3, 2, 3 ]
  gap> m := PeriodicList([0,1],[3,2]);
  [ 0, 1, / 3, 2 ]
  gap> IsConfinal(l,m);
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ConfinalityClass}}
\logpage{[ 12, 1, 9 ]}\nobreak
\hyperdef{L}{X86AB4AFF7B1613E3}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ConfinalityClass({\slshape l})\index{ConfinalityClass@\texttt{ConfinalityClass}}
\label{ConfinalityClass}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The strictly periodic list with same tail as \mbox{\texttt{\slshape l}}.



 There exists a unique periodic list, with no preperiod, which is confinal (see \texttt{IsConfinal} (\ref{IsConfinal})) to \mbox{\texttt{\slshape l}}. This strictly periodic list is returned by this command. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> l := PeriodicList([1],[2,3,2,3]);
  [ 1, / 2, 3, 2, 3 ]
  gap> ConfinalityClass(l);
  [/ 3, 2 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{LargestCommonPrefix}}
\logpage{[ 12, 1, 10 ]}\nobreak
\hyperdef{L}{X84FB28807BC8A502}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LargestCommonPrefix({\slshape c})\index{LargestCommonPrefix@\texttt{LargestCommonPrefix}}
\label{LargestCommonPrefix}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
The longest list that is a prefix of all elements of \mbox{\texttt{\slshape c}}.



 This command computes the longest (finite or periodic) list which is a prefix
of all elements of \mbox{\texttt{\slshape c}}. The argument \mbox{\texttt{\slshape c}} is a collection of finite and periodic lists. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> LargestCommonPrefix([PeriodicList([1],[2,3,2,3]),[1,2,3,4]]);
  [ 1, 2, 3 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{WordGrowth}}
\logpage{[ 12, 1, 11 ]}\nobreak
\hyperdef{L}{X7BFF1432803C9172}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WordGrowth({\slshape g, rec(...)})\index{WordGrowth@\texttt{WordGrowth}}
\label{WordGrowth}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{OrbitGrowth({\slshape g, point[, limit]})\index{OrbitGrowth@\texttt{OrbitGrowth}}
\label{OrbitGrowth}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Ball({\slshape g, radius})\index{Ball@\texttt{Ball}}
\label{Ball}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Sphere({\slshape g, radius})\index{Sphere@\texttt{Sphere}}
\label{Sphere}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The word growth of the semigroup \mbox{\texttt{\slshape g}}.



 This function computes the first terms of growth series associated with the
semigroup \mbox{\texttt{\slshape g}}. The argument \mbox{\texttt{\slshape g}} can actually be a group/monoid/semigroup, or a list representing that
semigroup's generating set. 

 The behaviour of \texttt{WordGrowth} is controlled via options passed in the second argument, which is a record.
They can be combined when reasonable, and are: 
\begin{description}
\item[{\texttt{limit:=n}}]  to specify a limit radius;
\item[{\texttt{sphere:=radius}}]  to return the sphere of the specified radius, unless a radius was specified in \texttt{limit}, in which case the value is ignored;
\item[{\texttt{spheres:=maxradius}}]  to return the list of spheres of radius between 0 and the specified limit;
\item[{\texttt{spheresizes:=maxradius}}]  to return the list sizes of spheres of radius between 0 and the specified
limit;
\item[{\texttt{ball:=radius}}]  to return the ball of the specified radius;
\item[{\texttt{balls:=maxradius}}]  to return the list of balls of radius between 0 and the specified limit;
\item[{\texttt{ballsizes:=maxradius}}]  to return the list sizes of balls of radius between 0 and the specified limit;
\item[{\texttt{indet:=z}}]  to return the \texttt{spheresizes}, as a polynomial in \texttt{z} (or the first indeterminate if \texttt{z} is not a polynomial;
\item[{\texttt{draw:=filename}}]  to create a rendering of the Cayley graph of \mbox{\texttt{\slshape g}}. Edges are given colours according to the cyclic ordering "red", "blue",
"green", "gray", "yellow", "cyan", "orange", "purple". If \texttt{filename} is a string, the graph is appended, in \texttt{dot} format, to that file. Otherwise, the output is converted to Postscript using
the program \texttt{neato} from the \textsf{graphviz} package, and displayed in a separate X window using the program \textsf{display}. This works on UNIX systems. 

 It is assumed, but not checked, that \textsf{graphviz} and \textsf{display} are properly installed on the system. 
\item[{\texttt{point:=p}}]  to compute the growth of the orbit of \texttt{p} under \mbox{\texttt{\slshape g}}, rather than the growth of \mbox{\texttt{\slshape g}}.
\item[{\texttt{track:=true}}]  to keep track of a word in the generators that gives the element. This affects
the "ball", "balls", "sphere" and "spheres" commands, where the result
returned is a 3-element list: the first entry is the original results; the
second entry is a homomorphism from a free group/monoid/semigroup; and the
third entry contains the words corresponding to the first entry via the
homomorphism.
\end{description}
 If the first argument is an integer \texttt{n} and not a record, the command is interpreted as \texttt{WordGrowth(...,rec(spheresizes:=n))}. 

 \texttt{WordGrowth(...,rec(draw:=true))} may be abbreviated as \texttt{Draw(...)}; \texttt{WordGrowth(...,rec(ball:=n))} may be abbreviated as \texttt{Ball(...,n)}; \texttt{WordGrowth(...,rec(sphere:=n))} may be abbreviated as \texttt{Sphere(...,n)}; 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> WordGrowth(GrigorchukGroup,4);
  [ 1, 4, 6, 12, 17 ]
  gap> WordGrowth(GrigorchukGroup,rec(limit:=4,indet:=true));
  17*x_1^4+12*x_1^3+6*x_1^2+4*x_1+1
  gap> WordGrowth(GrigorchukGroup,rec(limit:=1,spheres:=true));
  [ [ <Mealy element on alphabet [ 1, 2 ] with 1 state, initial state 1> ],
    [ d, b, c, a ] ]
  gap> WordGrowth(GrigorchukGroup,rec(point:=[2,2,2]));
  [ 1, 1, 1, 1, 1, 1, 1, 1 ]
  gap> OrbitGrowth(GrigorchukGroup,[1,1,1]);
  [ 1, 2, 2, 1, 1, 1 ]
  gap> WordGrowth(GrigorchukGroup,rec(spheres:=4,point:=PeriodicList([],[2])));
  [ [ [/ 2 ] ], [ [ 1, / 2 ] ], [ [ 1, 1, / 2 ] ], [ [ 2, 1, / 2 ] ],
    [ [ 2, 1, 1, / 2 ] ] ]
  gap> WordGrowth([(1,2),(2,3)],rec(spheres:=infinity,track:=true));
  [ [ [  ], [ (2,3), (1,2) ], [ (), (1,2,3), (1,3,2) ], [ (1,3) ] ],
    MappingByFunction( <free semigroup on the generators [ s1, s2 ]>, <group>, function( w ) ... end ),
    [ [  ], [ s2, s1 ], [ s2^2, s2*s1, s1*s2 ], [ s2*s1*s2 ] ] ]
\end{Verbatim}
 Note that the orbit growth of \texttt{[/2]} is constant 1, while that of \texttt{[/1]} is constant 2. The following code would find the point with maximal orbit
growth of a semigroup acting on the integers (for example, constructed with \texttt{PermGroup} (\ref{PermGroup})): 
\begin{Verbatim}[fontsize=\small,frame=single,label=]
  MaximalOrbitGrowth := function(g)
      local maxpt, growth, max;
      maxpt := LargestMovedPoint(g);
      growth := List([1..maxpt],n->WordGrowth(g:point:=n));
      max := Maximum(growth);
      return [max,Filtered([1..maxpt],n->growth[n]=max)];
  end;
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ShortGroupRelations}}
\logpage{[ 12, 1, 12 ]}\nobreak
\hyperdef{L}{X868E478F86A10CFF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ShortGroupRelations({\slshape g, n})\index{ShortGroupRelations@\texttt{ShortGroupRelations}}
\label{ShortGroupRelations}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ShortMonoidRelations({\slshape g, n})\index{ShortMonoidRelations@\texttt{ShortMonoidRelations}}
\label{ShortMonoidRelations}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
A list of relations between words over \mbox{\texttt{\slshape g}}, of length at most \mbox{\texttt{\slshape n}}.



 This function assumes that \mbox{\texttt{\slshape g}} is a list of monoid elements. it searches for products of at most \mbox{\texttt{\slshape n}} elements over \mbox{\texttt{\slshape g}} that are equal. 

 In its first form, it returns a list of words in a free group \texttt{f} of rank the length of \mbox{\texttt{\slshape g}}, that are trivial in \mbox{\texttt{\slshape g}}. The first argument may be a group, in which case its symmetric generating
set is considered. 

 In its second form, it returns a list of pairs \texttt{[l,r]}, where \texttt{l} and \texttt{r} are words in a free monoid \texttt{f} of rank the length of \mbox{\texttt{\slshape g}}, that are equal in \mbox{\texttt{\slshape g}}. The first argument may be a monoid, in which case its monoid generating set
is considered. 

 This command does not construct all such pairs; rather, it returns a small
set, in the hope that it may serve as a presentation for the monoid generated
by \mbox{\texttt{\slshape g}}. 

 The first element of the list returned is actually not a relation: it is a
homomorphism from \texttt{f} to [the group/monoid generated by] \mbox{\texttt{\slshape g}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> ShortGroupRelations(GrigorchukGroup,10);
  [ [ x1, x2, x3, x4 ] -> [ a, b, c, d ],
    x1^2, x2^2, x3^2, x4^2, x2*x3*x4, x4*x1*x4*x1*x4*x1*x4*x1,
    x3*x1*x3*x1*x3*x1*x3*x1*x3*x1*x3*x1*x3*x1*x3*x1 ]
  gap> ShortGroupRelations(GuptaSidkiGroup,9);
  [ [ x1, x2 ] -> [ x, gamma ],
    x1^3, x2^3, x2*x1^-1*x2*x1^-1*x2*x1^-1*x2*x1^-1*x2*x1^-1*x2*x1^-1*
       x2*x1^-1*x2*x1^-1*x2*x1^-1,    x1^-1*x2^-1*x1^-1*x2^-1*x1^-1*x2^-1*
  x1^-1*x2^-1*x1^-1*x2^-1*x1^-1*x2^-1*x1^-1*x2^-1*x1^-1*x2^-1*x1^-1*x2^-1 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ShortGroupWordInSet}}
\logpage{[ 12, 1, 13 ]}\nobreak
\hyperdef{L}{X7B9942AA84B0753E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ShortGroupWordInSet({\slshape g, s, n})\index{ShortGroupWordInSet@\texttt{ShortGroupWordInSet}}
\label{ShortGroupWordInSet}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ShortMonoidWordInSet({\slshape g, s, n})\index{ShortMonoidWordInSet@\texttt{ShortMonoidWordInSet}}
\label{ShortMonoidWordInSet}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ShortSemigroupWordInSet({\slshape g, s, n})\index{ShortSemigroupWordInSet@\texttt{ShortSemigroupWordInSet}}
\label{ShortSemigroupWordInSet}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
Words over \mbox{\texttt{\slshape g}} that express elements of \mbox{\texttt{\slshape s}}.



 This command produces words in the free group/monoid/semigroup generated by \mbox{\texttt{\slshape g}}'s generators that express elements of the set \mbox{\texttt{\slshape s}}. Elements of length at most \mbox{\texttt{\slshape AbsoluteValue(n)}} are searched; if \mbox{\texttt{\slshape n}} is non-negative then at most one element is returned. The value \texttt{\mbox{\texttt{\slshape n}}=infinity} is allowed. 

 The second argument may be either a list, a predicate (i.e. a function
returning \texttt{true} or \texttt{false}) or an element. 

 The function returns a list of words in the free group/monoid/semigroup; the
first entry of the list is a homomorphism from the free group/monoid/semigroup
to \mbox{\texttt{\slshape g}}. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> l := ShortMonoidWordInSet(Group((1,2),(2,3),(3,4)),
              [(1,2,3,4),(4,3,2,1)],-3);
  [ MappingByFunction( <free monoid on the generators [ m1, m2, m3 ]>, Group(
      [ (1,2), (2,3), (3,4) ]), function( w ) ... end ), m3*m2*m1, m1*m2*m3 ]
  gap> f := Remove(l,1);;
  gap> List(l,x->x^f);
  [ (1,2,3,4), (1,4,3,2) ]
  gap> ShortMonoidWordInSet(GrigorchukGroup,
         [Comm(GrigorchukGroup.1,GrigorchukGroup.2)],4);
  [ MappingByFunction( <free monoid on the generators [ m1, m2, m3, m4
       ]>, <self-similar monoid over [ 1 .. 2 ] with
      4 generators>, function( w ) ... end ), m1*m2*m1*m2 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{SurfaceBraidFpGroup}}
\logpage{[ 12, 1, 14 ]}\nobreak
\hyperdef{L}{X84472A637B648C47}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SurfaceBraidFpGroup({\slshape n, g, p})\index{SurfaceBraidFpGroup@\texttt{SurfaceBraidFpGroup}}
\label{SurfaceBraidFpGroup}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PureSurfaceBraidFpGroup({\slshape n, g, p})\index{PureSurfaceBraidFpGroup@\texttt{PureSurfaceBraidFpGroup}}
\label{PureSurfaceBraidFpGroup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The [pure] surface braid group on \mbox{\texttt{\slshape n}} strands.



 This function creates a finitely presented group, isomorphic to the [pure]
braid group on \mbox{\texttt{\slshape n}} strands of the surface of genus \mbox{\texttt{\slshape g}}, with \mbox{\texttt{\slshape p}} punctures. In particular, \texttt{SurfaceBraidFpGroup(n,0,1)} is the usual braid group (on the disc). 

 The presentation comes from \cite{MR2043362}. The first $2g$ generators are the standard $a_i,b_i$ surface generators; the next $n-1$ are the standard $s_i$ braid generators; and the last are the extra $z$ generators. 

 The pure surface braid group is the kernel of the natural map from the surface
braid group to the symmetric group on \mbox{\texttt{\slshape n}} points, defined by sending $a_i,b_i,z$ to the identity and $s_i$ to the transposition \texttt{(i,i+1)}. }

 

\subsection{\textcolor{Chapter }{CharneyBraidFpGroup}}
\logpage{[ 12, 1, 15 ]}\nobreak
\hyperdef{L}{X87E12292861FFE79}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CharneyBraidFpGroup({\slshape n})\index{CharneyBraidFpGroup@\texttt{CharneyBraidFpGroup}}
\label{CharneyBraidFpGroup}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The braid group on \mbox{\texttt{\slshape n}} strands.



 This function creates a finitely presented group, isomorphic to the braid
group on \mbox{\texttt{\slshape n}} strands (on the disc). It is isomorphic to \texttt{SurfaceBraidFpGroup(n,0,1)}, but has a different presentation, due to Charney (\cite{MR1314589}), with one generator per non-trivial permutation of \mbox{\texttt{\slshape n}} points. }

 

\subsection{\textcolor{Chapter }{ArtinRepresentation}}
\logpage{[ 12, 1, 16 ]}\nobreak
\hyperdef{L}{X814375977D2E4AD9}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ArtinRepresentation({\slshape n})\index{ArtinRepresentation@\texttt{ArtinRepresentation}}
\label{ArtinRepresentation}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The braid group's representation on \texttt{FreeGroup(n)}.



 This function creates a Artin's representatin, a homomorphism from the braid
group on \mbox{\texttt{\slshape n}} strands (on the disc) into the automorphism group of a free group of rank \mbox{\texttt{\slshape n}}. }

 

\subsection{\textcolor{Chapter }{StringByInt}}
\logpage{[ 12, 1, 17 ]}\nobreak
\hyperdef{L}{X7E4966327C37C790}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{StringByInt({\slshape n[, b]})\index{StringByInt@\texttt{StringByInt}}
\label{StringByInt}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
A string representing \mbox{\texttt{\slshape n}} in base \mbox{\texttt{\slshape b}}.



 This function converts a positive integer to string. It accepts an optional
second argument, which is a base in which to print \mbox{\texttt{\slshape n}}. By default, \mbox{\texttt{\slshape b}} is 2. }

 

\subsection{\textcolor{Chapter }{PositionTower}}
\logpage{[ 12, 1, 18 ]}\nobreak
\hyperdef{L}{X7979A86E781759F0}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PositionTower({\slshape t, x})\index{PositionTower@\texttt{PositionTower}}
\label{PositionTower}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The largest index such that \texttt{t[i]} contains \mbox{\texttt{\slshape x}}.



 This function assumes \mbox{\texttt{\slshape t}} is a descending tower of domains, such as that constructed by \texttt{LowerCentralSeries}. It returns the largest integer \texttt{i} such that \texttt{t[i]} contains \mbox{\texttt{\slshape x}}; in case the tower ends precisely with \mbox{\texttt{\slshape x}}, the value \texttt{infinity} is returned. 

 \mbox{\texttt{\slshape x}} can be an element or a subdomain of \texttt{t[1]}. }

 

\subsection{\textcolor{Chapter }{CoefficientsInAbelianExtension}}
\logpage{[ 12, 1, 19 ]}\nobreak
\hyperdef{L}{X79016B3878B5EFAA}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CoefficientsInAbelianExtension({\slshape x, b, G})\index{CoefficientsInAbelianExtension@\texttt{CoefficientsInAbelianExtension}}
\label{CoefficientsInAbelianExtension}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
The coefficients in \mbox{\texttt{\slshape b}} of the element \mbox{\texttt{\slshape x}}, modulo \mbox{\texttt{\slshape G}}.



 If \mbox{\texttt{\slshape b}} is a list of group elements $b_1,\dots,b_k$, and $H=\langle G,b_1,\dots,b_k\rangle$ contains \mbox{\texttt{\slshape G}} as a normal subgroup, and $H/G$ is abelian and $x\in H$, then this function computes exponents $e_1,\dots,e_k$ such that $\prod b_i^{e_i}G=xG$. }

 

\subsection{\textcolor{Chapter }{MagmaEndomorphismByImagesNC}}
\logpage{[ 12, 1, 20 ]}\nobreak
\hyperdef{L}{X8624AFAD872509D8}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MagmaEndomorphismByImagesNC({\slshape f, im})\index{MagmaEndomorphismByImagesNC@\texttt{MagmaEndomorphismByImagesNC}}
\label{MagmaEndomorphismByImagesNC}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
An endomorphism of \mbox{\texttt{\slshape f}}.



 This function constructs an endomorphism of the group,monoid or semigroup \mbox{\texttt{\slshape f}} specified by sending generator number $i$ to the $i$th entry in \mbox{\texttt{\slshape im}}. It is a shortcut for a call to \texttt{GroupHomomorphismByImagesNC} or \texttt{MagmaHomomorphismByFunctionNC(...,MappedWord(...))}. }

 

\subsection{\textcolor{Chapter }{MagmaHomomorphismByImagesNC}}
\logpage{[ 12, 1, 21 ]}\nobreak
\hyperdef{L}{X7F7E6457877F69EC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MagmaHomomorphismByImagesNC({\slshape f, g, im})\index{MagmaHomomorphismByImagesNC@\texttt{MagmaHomomorphismByImagesNC}}
\label{MagmaHomomorphismByImagesNC}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
An homomorphism from \mbox{\texttt{\slshape f}} to \mbox{\texttt{\slshape g}}.



 This function constructs a homomorphism of the group,monoid or semigroup \mbox{\texttt{\slshape f}} specified by sending generator number $i$ to the $i$th entry in \mbox{\texttt{\slshape im}}. It is a shortcut for a call to \texttt{GroupHomomorphismByImagesNC} or \texttt{MagmaHomomorphismByFunctionNC(...,MappedWord(...))}. }

 

\subsection{\textcolor{Chapter }{NewFIFO}}
\logpage{[ 12, 1, 22 ]}\nobreak
\hyperdef{L}{X7D44289E861E3343}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NewFIFO({\slshape [l]})\index{NewFIFO@\texttt{NewFIFO}}
\label{NewFIFO}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Add({\slshape f, i})\index{Add@\texttt{Add}!FIFO}
\label{Add:FIFO}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Append({\slshape f, l})\index{Append@\texttt{Append}!FIFO}
\label{Append:FIFO}
}\hfill{\scriptsize (operation)}}\\


 These functions create and extend FIFOs, i.e. first-in first-out data
structures. 

 The first command creates a FIFO, with an optional list initializing it. 

 The second and third commands add an element, or append a list, to the FIFO. 

 Elements are removed via \texttt{NextIterator(f)}, and the FIFO is tested for emptyness via \texttt{IsDoneIterator(f)}. Thus, a typical use is the following code, which tests in breadth-first
manner that all numbers in \texttt{[1..1000]} have a successor which is prime: 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> f := NewFIFO([1..10000]);
  <iterator>
  gap> for i in f do if not IsPrime(i) then Add(f,i+1); fi; od;
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ProductIdeal}}
\logpage{[ 12, 1, 23 ]}\nobreak
\hyperdef{L}{X86AC1C028093204D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ProductIdeal({\slshape a, b})\index{ProductIdeal@\texttt{ProductIdeal}}
\label{ProductIdeal}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ProductBOIIdeal({\slshape a, b})\index{ProductBOIIdeal@\texttt{ProductBOIIdeal}}
\label{ProductBOIIdeal}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
the product of the ideals \mbox{\texttt{\slshape a}} and \mbox{\texttt{\slshape b}}.



 The first command computes the product of the left ideal \mbox{\texttt{\slshape a}} and the right ideal \mbox{\texttt{\slshape b}}. If they are not appropriately-sided ideals, the command first attempts to
convert them. 

 The second command assumes that the ring of these ideals has a basis made of
invertible elements. It is then much easier to compute the product. }

 

\subsection{\textcolor{Chapter }{DimensionSeries}}
\logpage{[ 12, 1, 24 ]}\nobreak
\hyperdef{L}{X794940277C9AD85C}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DimensionSeries({\slshape a[, n]})\index{DimensionSeries@\texttt{DimensionSeries}}
\label{DimensionSeries}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
A nested list of ideals in the algebra-with-one \mbox{\texttt{\slshape a}}.



 This command computes the powers of the augmentation ideal of \mbox{\texttt{\slshape a}}, and returns their list. The list stops when the list becomes stationary. 

 The optional second argument gives a limit to the number of terms to put in
the series. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> a := ThinnedAlgebraWithOne(GF(2),GrigorchukGroup);
  <self-similar algebra-with-one on alphabet GF(2)^2 with 4 generators>
  gap> q := MatrixQuotient(a,3);
  <algebra-with-one of dimension 22 over GF(2)>
  gap> l := DimensionSeries(q);
  [ <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (5 generators)>,
    <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (dimension 21)>,
    <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (dimension 18)>,
    <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (dimension 14)>,
    <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (dimension 10)>,
    <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (dimension 6)>,
    <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (dimension 3)>,
    <two-sided ideal in <algebra-with-one of dimension 22 over GF(2)>, (dimension 1)>,
    <algebra of dimension 0 over GF(2)> ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Trans}}
\logpage{[ 12, 1, 25 ]}\nobreak
\hyperdef{L}{X7CA512F481AADD38}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Trans({\slshape list, ...})\index{Trans@\texttt{Trans}}
\label{Trans}
}\hfill{\scriptsize (function)}}\\


 This function creates a new transformation, in the family \texttt{TRANS{\textunderscore}FAMILY}. These objects behave quite as usual transformations (see \texttt{Transformation} (\textbf{Reference: Transformation})); the differences are that these transformations do not have a bounded set on
which they operate; they are all part of one family, and act on \texttt{PosInt}. The other difference is that, when they are invertible, these
transformations are simply permutations. 

 If one argument is passed, it is a list of images, as in \texttt{PermList} (\textbf{Reference: PermList}). If two arguments are passed and both are lists, they are the source and
range, as in \texttt{PermListList} (\textbf{Reference: PermListList}). Finally, if two arguments are passed and the second is a function, the first
argument is treated as the source and the range is computed with this
function. 

 A major bug is that \texttt{IsTrans(Trans(l))} returns \texttt{false} if \texttt{l} defines a bijective transformation. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  gap> Trans();
  ()
  gap> Trans([1,,2]);
  <1,2,2>
  gap> 3^last;
  2
  gap> Trans([1,3,2]);
  (2,3)
  gap> Trans([10,11],[11,12]);
  <1,2,3,4,5,6,7,8,9,11,12>
  gap> Trans([10,11],x->x^2);
  <1,2,3,4,5,6,7,8,9,100,121>
\end{Verbatim}
 }

 }

 
\section{\textcolor{Chapter }{User settings}}\logpage{[ 12, 2, 0 ]}
\hyperdef{L}{X7ADFF37084706CEC}{}
{
 

\subsection{\textcolor{Chapter }{InfoFR}}
\logpage{[ 12, 2, 1 ]}\nobreak
\hyperdef{L}{X7E95AC267805E4C1}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{InfoFR\index{InfoFR@\texttt{InfoFR}}
\label{InfoFR}
}\hfill{\scriptsize (info class)}}\\


 This is an \texttt{Info} class for the package \textsf{FR}. The command \texttt{SetInfoLevel(InfoFR,1);} switches on the printing of some information during the computations of
certain \textsf{FR} functions; in particular all automatic conversions between FR machines and
Mealy machines. 

 The command \texttt{SetInfoLevel(InfoFR,2);} requests a little more information, and in particular prints intermediate
results in potentially long calculations such as \texttt{NucleusOfFRSemigroup} (\ref{NucleusOfFRSemigroup}). 

 The command \texttt{SetInfoLevel(InfoFR,3);} ensures that \textsf{FR} will print information every few seconds or so. This is useful to gain
confidence that the program is not stuck due to a programming bug by the
author of \textsf{FR}. }

 

\subsection{\textcolor{Chapter }{FR{\textunderscore}SEARCH}}
\logpage{[ 12, 2, 2 ]}\nobreak
\hyperdef{L}{X7DBA334C83DE0619}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FR{\textunderscore}SEARCH\index{FRSEARCH@\texttt{FR{\textunderscore}SEARCH}}
\label{FRSEARCH}
}\hfill{\scriptsize (global variable)}}\\


 This variable controls the search mechanism in FR groups. It is a record with
in particular entries \texttt{radius} and \texttt{depth}. 

 \texttt{radius} limits the search in FR groups to balls of that radius in the generating set.
For example, the command \texttt{x in G} will initiate a search in \texttt{G} to attempt to express \texttt{x} as a reasonably short word in the generators of \texttt{G}. 

 \texttt{depth} limits the level of the tree on which quotients of FR groups should be
considered. Again for the command \texttt{x in G}, deeper and deeper quotients will be considered, in the hope of finding a
quotient of \texttt{G} to which \texttt{x} does not belong. 

 A primitive mechanism is implemented to search alternatively for a quotient
disproving \texttt{x in G} and a word proving \texttt{x in G}. 

 When the limits are reached and the search was unsuccessful, an interactive \texttt{Error()} is raised, to let the user increase their values. 

 Specific limits can be passed to any command via the options \texttt{FRdepth} and \texttt{FRradius}, as for example in \texttt{Size(G:FRdepth:=3,FRradius:=5)}. }

 }

 }

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

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

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


\printindex

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