% 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{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}

\definecolor{linkColor}{rgb}{0.0,0.0,0.554}
\definecolor{citeColor}{rgb}{0.0,0.0,0.554}
\definecolor{fileColor}{rgb}{0.0,0.0,0.554}
\definecolor{urlColor}{rgb}{0.0,0.0,0.554}
\definecolor{promptColor}{rgb}{0.0,0.0,0.589}
\definecolor{brkpromptColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapinputColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapoutputColor}{rgb}{0.0,0.0,0.0}

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


\usepackage{fancyvrb}

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


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

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

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

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

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

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





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


\begin{document}

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

\begin{center}{\maintitlesize \textbf{\textsf{Guarana} \mbox{}}}\\
\vfill

\hypersetup{pdftitle=\textsf{Guarana} }
\markright{\scriptsize \mbox{}\hfill \textsf{Guarana}  \hfill\mbox{}}
{\Huge \textbf{A Gap4 Package \mbox{}}}\\
\vfill

{\Huge ( Version 0.94 ) \mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\Large \textbf{Bj{\"o}rn Assmann \mbox{}}}\\
\hypersetup{pdfauthor=Bj{\"o}rn Assmann }
\end{center}\vfill

\mbox{}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
{\copyright} 2007 Bj{\"o}rnAssmann. 

 \mbox{}}\\[1cm]
\newpage

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

\tableofcontents
\newpage

 
\chapter{\textcolor{Chapter }{Introduction}}\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X7DFB63A97E67C0A1}{}
{
  
\section{\textcolor{Chapter }{About Guarana}}\label{sec:about}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X7E0647AA861EA26C}{}
{
  In this package we demonstrate the algorithmic usefulness of the so-called
Mal'cev correspondence for computations with infinite polycyclic groups; it is
a correspondence that associates to every $\Q$-powered nilpotent group $H$ a unique rational nilpotent Lie algebra $L_H$ and vice-versa. The Mal'cev correspondence was discovered by Anatoly Mal'cev
in 1951 \cite{Mal51}. }

 
\section{\textcolor{Chapter }{Setup for computing the correspondence}}\label{sec:setup}
\logpage{[ 1, 2, 0 ]}
\hyperdef{L}{X7E6EB42287311C08}{}
{
  Let $G$ be a finitely generated torsion-free nilpotent group, i.e.\texttt{\symbol{92}}
a $T$-group. Then $G$ can be embedded in a $\mathbb{Q}$-powered hull $\hat{G}$. The group $\hat{G}$ is a $\mathbb{Q}$-powered nilpotent group and is unique up to isomorphism. We denote the Lie
algebra which corresponds to $\hat{G}$ under the Mal'cev correspondence by $L(G)= L_{\hat{G}}$. We provide an algorithm for setting up the Mal'cev correspondence between $\hat{G}$ and the Lie algebra $L(G)$. That is, if $G$ is given by a polycyclic presentation with respect to a Mal'cev basis, then we
can compute a structure constants table of $L(G)$. Furthermore for a given $g\in G$ we can compute the corresponding element in $L(G)$ and vice versa. }

 
\section{\textcolor{Chapter }{Collection}}\label{sec:collect}
\logpage{[ 1, 3, 0 ]}
\hyperdef{L}{X80AD720B85736A05}{}
{
  Every element of a polycyclically presented group has a unique normal form. An
algorithm for computing this normal form is called a collection algorithm.
Such an algorithm lies at the heart of most methods dealing with
polycyclically presented groups. The current state of the art is collection
from the left \cite{Geb02}\cite{LGS90}\cite{VLe90} \texttt{\symbol{125}}. This package contains a new collection algorithm for
polycyclically presented groups, which we call Mal'cev collection \cite{ALi07}. Mal'cev collection is in some cases dramatically faster than collection from
the left, while using less memory. }

 }

 
\chapter{\textcolor{Chapter }{Computing the Mal'cev correspondence}}\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X781C0216819C09A8}{}
{
  
\section{\textcolor{Chapter }{The main functions}}\label{sec:mainfuncs}
\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X7D3DC4ED855DC13C}{}
{
  Let $G$ be a $T$-group and $\hat{G}$ its $\mathbb{Q}$-powered hull. In this chapter we describe functionality for setting up the
Mal'cev correspondence between $\hat{G}$ and the Lie algebra $L(G)$. The data structures needed for computations with $\hat{G}$ and $L(G)$ are stored in a so-called Mal'cev object. Computational representations of
elements of $\hat{G}$, respectively $L(G)$, will be called Mal'cev group elements, respectively Mal'cev Lie elements. 

\subsection{\textcolor{Chapter }{MalcevObjectByTGroup}}
\logpage{[ 2, 1, 1 ]}\nobreak
\hyperdef{L}{X7A3976DA834C0E90}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{MalcevObjectByTGroup({\mdseries\slshape N})\index{MalcevObjectByTGroup@\texttt{MalcevObjectByTGroup}}
\label{MalcevObjectByTGroup}
}\hfill{\scriptsize (function)}}\\


 If \mbox{\texttt{\mdseries\slshape N}} is a a \mbox{\texttt{\mdseries\slshape T}}-group (i.e. a finitely generated torsion-free nilpotent group), given by a
polycyclic presentation with respect to a Mal'cev basis, then this function
computes the Mal'cev correspondence for \mbox{\texttt{\mdseries\slshape N}} and stores the result in a so-called Mal'cev object. Otherwise this function
returns `fail'. In the moment this function is restricted to groups \mbox{\texttt{\mdseries\slshape N}} of nilpotency class at most 9. }

 

\subsection{\textcolor{Chapter }{UnderlyingGroup}}
\logpage{[ 2, 1, 2 ]}\nobreak
\hyperdef{L}{X7A6720DD7B4AF466}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{UnderlyingGroup({\mdseries\slshape mo})\index{UnderlyingGroup@\texttt{UnderlyingGroup}}
\label{UnderlyingGroup}
}\hfill{\scriptsize (function)}}\\


 For a Mal'cev object \mbox{\texttt{\mdseries\slshape mo}} this function returns the \mbox{\texttt{\mdseries\slshape T}}-group, which was used to build \mbox{\texttt{\mdseries\slshape mo}}. }

 

\subsection{\textcolor{Chapter }{UnderlyingLieAlgebra}}
\logpage{[ 2, 1, 3 ]}\nobreak
\hyperdef{L}{X7CA021E28527763E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{UnderlyingLieAlgebra({\mdseries\slshape mo})\index{UnderlyingLieAlgebra@\texttt{UnderlyingLieAlgebra}}
\label{UnderlyingLieAlgebra}
}\hfill{\scriptsize (function)}}\\


 For a Mal'cev object \mbox{\texttt{\mdseries\slshape mo}} this function returns the Lie algebra, which underlies the correspondence
described by \mbox{\texttt{\mdseries\slshape mo}}. }

 

\subsection{\textcolor{Chapter }{Dimension}}
\logpage{[ 2, 1, 4 ]}\nobreak
\hyperdef{L}{X7E6926C6850E7C4E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{Dimension({\mdseries\slshape mo})\index{Dimension@\texttt{Dimension}}
\label{Dimension}
}\hfill{\scriptsize (function)}}\\


 Returns the dimension of the Lie algebra that underlies the Mal'cev object \mbox{\texttt{\mdseries\slshape mo}}. }

 

\subsection{\textcolor{Chapter }{MalcevGrpElementByExponents}}
\logpage{[ 2, 1, 5 ]}\nobreak
\hyperdef{L}{X860138DA82C4F56D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{MalcevGrpElementByExponents({\mdseries\slshape mo, exps})\index{MalcevGrpElementByExponents@\texttt{MalcevGrpElementByExponents}}
\label{MalcevGrpElementByExponents}
}\hfill{\scriptsize (function)}}\\


 For a Mal'cev object \mbox{\texttt{\mdseries\slshape mo}} and an exponent vector \mbox{\texttt{\mdseries\slshape exps}} with rational entries, this functions returns the Mal'cev group element, which
has exponents \mbox{\texttt{\mdseries\slshape exps}} with respect to the Mal'cev basis of the underlying group of \mbox{\texttt{\mdseries\slshape mo}}. }

 

\subsection{\textcolor{Chapter }{MalcevLieElementByCoefficients}}
\logpage{[ 2, 1, 6 ]}\nobreak
\hyperdef{L}{X849FCF377F5E29C2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{MalcevLieElementByCoefficients({\mdseries\slshape mo, coeffs})\index{MalcevLieElementByCoefficients@\texttt{MalcevLieElementByCoefficients}}
\label{MalcevLieElementByCoefficients}
}\hfill{\scriptsize (function)}}\\


 For a Mal'cev object \mbox{\texttt{\mdseries\slshape mo}} and a coefficient vector \mbox{\texttt{\mdseries\slshape coeffs}} with rational entries, this functions returns the Mal'cev Lie element, which
has coefficients \mbox{\texttt{\mdseries\slshape coeffs}} with respect to the basis of the underlying Lie algebra of \mbox{\texttt{\mdseries\slshape mo}}. }

 

\subsection{\textcolor{Chapter }{RandomGrpElm}}
\logpage{[ 2, 1, 7 ]}\nobreak
\hyperdef{L}{X86CC8994841B1193}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{RandomGrpElm({\mdseries\slshape mo, range})\index{RandomGrpElm@\texttt{RandomGrpElm}}
\label{RandomGrpElm}
}\hfill{\scriptsize (function)}}\\


 For a Mal'cev object \mbox{\texttt{\mdseries\slshape mo}} this function returns the output of MalcevGrpElementByExponents( \mbox{\texttt{\mdseries\slshape mo}}, \mbox{\texttt{\mdseries\slshape exps}} ), where \mbox{\texttt{\mdseries\slshape exps}} is an exponent vector whose entries are randomly chosen integers between -\mbox{\texttt{\mdseries\slshape range}} and \mbox{\texttt{\mdseries\slshape range}}. }

 

\subsection{\textcolor{Chapter }{RandomLieElm}}
\logpage{[ 2, 1, 8 ]}\nobreak
\hyperdef{L}{X876F868B78430678}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{RandomLieElm({\mdseries\slshape mo, range})\index{RandomLieElm@\texttt{RandomLieElm}}
\label{RandomLieElm}
}\hfill{\scriptsize (function)}}\\


 For a Mal'cev object \mbox{\texttt{\mdseries\slshape mo}} this function returns the output of MalcevLieElementByExponents( \mbox{\texttt{\mdseries\slshape mo}}, \mbox{\texttt{\mdseries\slshape coeffs}} ), where \mbox{\texttt{\mdseries\slshape coeffs}} is a coefficient vector whose entries are randomly chosen integers between -\mbox{\texttt{\mdseries\slshape range}} and \mbox{\texttt{\mdseries\slshape range}}. }

 

\subsection{\textcolor{Chapter }{Log}}
\logpage{[ 2, 1, 9 ]}\nobreak
\hyperdef{L}{X7E7C986487C4EB02}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{Log({\mdseries\slshape g})\index{Log@\texttt{Log}}
\label{Log}
}\hfill{\scriptsize (function)}}\\


 For Mal'cev group element \mbox{\texttt{\mdseries\slshape g}} this function returns the corresponding Mal'cev Lie element. }

 

\subsection{\textcolor{Chapter }{Exp}}
\logpage{[ 2, 1, 10 ]}\nobreak
\hyperdef{L}{X86E48BC98197839E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{Exp({\mdseries\slshape x})\index{Exp@\texttt{Exp}}
\label{Exp}
}\hfill{\scriptsize (function)}}\\


 For Mal'cev Lie element \mbox{\texttt{\mdseries\slshape x}} this function returns the corresponding Mal'cev group element. }

 

\subsection{\textcolor{Chapter }{*}}
\logpage{[ 2, 1, 11 ]}\nobreak
\hyperdef{L}{X7857704878577048}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{*({\mdseries\slshape g, h})\index{*@\texttt{*}}
\label{*}
}\hfill{\scriptsize (function)}}\\


 Returns the product of Mal'cev group elements. }

 

\subsection{\textcolor{Chapter }{Comm}}
\logpage{[ 2, 1, 12 ]}\nobreak
\hyperdef{L}{X80761843831B468E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{Comm({\mdseries\slshape x, y})\index{Comm@\texttt{Comm}}
\label{Comm}
}\hfill{\scriptsize (function)}}\\


 If \mbox{\texttt{\mdseries\slshape x}},\mbox{\texttt{\mdseries\slshape y}} are Mal'cev group elements, then this function returns the group theoretic
commutator of \mbox{\texttt{\mdseries\slshape x}} and \mbox{\texttt{\mdseries\slshape y}}. If \mbox{\texttt{\mdseries\slshape x}},\mbox{\texttt{\mdseries\slshape y}} are Mal'cev Lie elements, then this function returns the Lie commutator of \mbox{\texttt{\mdseries\slshape x}} and \mbox{\texttt{\mdseries\slshape y}}. }

 

\subsection{\textcolor{Chapter }{MalcevSymbolicGrpElementByExponents}}
\logpage{[ 2, 1, 13 ]}\nobreak
\hyperdef{L}{X86C4910279A45173}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{MalcevSymbolicGrpElementByExponents({\mdseries\slshape mo, exps})\index{MalcevSymbolicGrpElementByExponents@\texttt{MalcevSymbolicGrpElementByExponents}}
\label{MalcevSymbolicGrpElementByExponents}
}\hfill{\scriptsize (function)}}\\


 For a Mal'cev object \mbox{\texttt{\mdseries\slshape mo}} and an exponent vector \mbox{\texttt{\mdseries\slshape exps}} with rational indeterminates as entries, this functions returns the Mal'cev
group element, which has exponents \mbox{\texttt{\mdseries\slshape exps}} with respect to the Mal'cev basis of the underlying group of \mbox{\texttt{\mdseries\slshape mo}}. }

 

\subsection{\textcolor{Chapter }{MalcevLieElementByCoefficients}}
\logpage{[ 2, 1, 14 ]}\nobreak
\hyperdef{L}{X849FCF377F5E29C2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{MalcevLieElementByCoefficients({\mdseries\slshape mo, coeffs})\index{MalcevLieElementByCoefficients@\texttt{MalcevLieElementByCoefficients}}
\label{MalcevLieElementByCoefficients}
}\hfill{\scriptsize (function)}}\\


 For a Mal'cev object \mbox{\texttt{\mdseries\slshape mo}} and a coefficient vector \mbox{\texttt{\mdseries\slshape coeffs}} with rational indeterminates as entries, this functions returns the Mal'cev
Lie element, which has coefficients \mbox{\texttt{\mdseries\slshape coeffs}} with respect to the basis of the underlying Lie algebra of \mbox{\texttt{\mdseries\slshape mo}}. }

 }

 
\section{\textcolor{Chapter }{An example application}}\logpage{[ 2, 2, 0 ]}
\hyperdef{L}{X81CAD2F27B2066C4}{}
{
  
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  	gap> n := 2;
  	2
  	gap> F := FreeGroup( n );
  	<free group on the generators [ f1, f2 ]>
  	gap> c := 3;
  	3
  	gap> N := NilpotentQuotient( F, c );
  	Pcp-group with orders [ 0, 0, 0, 0, 0 ]
  	
  	gap> mo := MalcevObjectByTGroup( N );
  	<<Malcev object of dimension 5>>
  	gap> dim := Dimension( mo );
  	5
  	gap> UnderlyingGroup( mo );
  	Pcp-group with orders [ 0, 0, 0, 0, 0 ]
  	gap> UnderlyingLieAlgebra( mo );
  	<Lie algebra of dimension 5 over Rationals>
  	 
  	gap> g := MalcevGrpElementByExponents( mo, [1,1,0,2,-1/2] );
  	[ 1, 1, 0, 2, -1/2 ]
  	gap> x := MalcevLieElementByCoefficients( mo, [1/2, 2, -1, 3, 5 ] );
  	[ 1/2, 2, -1, 3, 5 ]
  	
  	gap> h := RandomGrpElm( mo );
  	[ 5, -3, 0, -2, 8 ]
  	gap> y := RandomLieElm( mo );
  	[ 3, 9, 5, 5, 2 ]
  	
  	gap> z := Log( g );
  	[ 1, 1, -1/2, 7/3, -1/3 ]
  	gap> Exp( z ) = g;
  	true
  	gap> k := Exp( y );
  	[ 3, 9, 37/2, 77/4, 395/4 ]
  	gap> Log( k ) = y;
  	true
  	
  	gap> g*h;
  	[ 6, -2, 5, 10, -15/2 ]
  	gap> Comm(g,h);
  	[ 0, 0, 8, 10, -18 ]
  	gap> Comm(x,y);
  	[ 0, 0, 3/2, -25/4, -79/4 ]
  	
  	gap> indets := List( List( [1..dim], i->Concatenation( "a_", String(i) ) ),
  	>                   x->Indeterminate( Rationals, x : new ) );
  	[ a_1, a_2, a_3, a_4, a_5 ]
  	gap> g_sym := MalcevSymbolicGrpElementByExponents( mo, indets );
  	[ a_1, a_2, a_3, a_4, a_5 ]
  	gap> x_sym := Log( g_sym );
  	[ a_1, a_2, -1/2*a_1*a_2+a_3, 1/12*a_1^2*a_2+1/4*a_1*a_2-1/2*a_1*a_3+a_4,
  	-1/12*a_1*a_2^2+1/4*a_1*a_2-1/2*a_2*a_3+a_5 ]
  	gap> g_sym * g;
  	[ a_1+1, a_2+1, a_2+a_3, a_3+a_4+2, 1/2*a_2^2+1/2*a_2+a_3+a_5-1/2 ]
  	
\end{Verbatim}
 }

 }

 
\chapter{\textcolor{Chapter }{Mal'cev collection }}\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X7989E7D27B142919}{}
{
  Let $G$ be an infinite polycyclic group. It is well-known that there exist a normal $T$-group $N$ and a $T$-group $C$ such that $H=CN$ is normal of finite index in $G$ and $H/N$ is free abelian of finite rank \cite{Seg83}. In this chapter we present an effective collection method for an infinite
polycyclic group which is given by a polycyclic presentation with respect to a
polycyclic sequence $P$ going through the normal series $1 \le N \le H \le G$. This polycyclic sequence $P$ must be chosen as follows. Let $(n_1,\dots,n_l)$ be a Mal'cev basis of $N$ and let $(c_1N,\dots,c_k N)$ be a basis for the free abelian group $CN/N$. Then $(c_1,\dots,c_k,n_1,\dots,n_l)$ is a polycyclic sequence for $H=CN$. Further there exists $f_1,\dots, f_j \in G$ such that $(f_1 H, \dots, f_j H)$ is a polycyclic sequence for $G/H$. Now we set 
\[P = (f_1,\dots,f_j, c_1, \dots , c_k, n_1, \dots, n_l )\]
 
\section{\textcolor{Chapter }{The main functions }}\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X7D3DC4ED855DC13C}{}
{
  

\subsection{\textcolor{Chapter }{MalcevCollectorConstruction}}
\logpage{[ 3, 1, 1 ]}\nobreak
\hyperdef{L}{X7C7C33FB789E7F50}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{MalcevCollectorConstruction({\mdseries\slshape G, inds, C, CC, N, NN})\index{MalcevCollectorConstruction@\texttt{MalcevCollectorConstruction}}
\label{MalcevCollectorConstruction}
}\hfill{\scriptsize (function)}}\\


 Returns a Mal'cev collector for the infinite polycyclically presented group $G$. The group $G$ must be given with respect to a polycyclic sequence $(g_1,\dots,g_r, c_{r+1}, \dots, c_{r+s}, n_{r+s+1}, \dots, n_{r+s+t})$ with the following properties: 
\begin{itemize}
\item  (a) $(n_{r+s+1}, \dots, n_{r+s+t})$ is a Mal'cev basis for the $T$-group $N \leq G$, 
\item  (b) $(c_{r+1}N, \dots, c_{r+s}N)$ is a basis for the free-abelian group $CN/N$ where $C \leq G$ is a $T$-group generated by $c_{r+1}, \dots, c_{r+s}$, 
\item  (c) $(g_1 CN, \dots, g_r CN)$ is a polycyclic sequence for the finite group $G/CN$. 
\end{itemize}
 The list \mbox{\texttt{\mdseries\slshape inds}} is equal to $[ [1,\dots,r],[r+1,\dots,r+s],[r+s+1,\dots,r+s+t]]$. The group $CC$ is isomorphic to $C$ via \mbox{\texttt{\mdseries\slshape CC}}!.bijection and given by a polycyclic presentation with respect to a Mal'cev
basis starting with $c_{r+1}, \dots, c_{r+s}$. The group $NN$ is isomorphic to $N$ via \mbox{\texttt{\mdseries\slshape NN}}!.bijection. and given by a polycyclic presentation with respect to the
Mal'cev basis $( n_{r+s+1}, \dots, n_{r+s+t})$. }

 

\subsection{\textcolor{Chapter }{GUARANA.Tr{\textunderscore}n{\textunderscore}O1}}
\logpage{[ 3, 1, 2 ]}\nobreak
\hyperdef{L}{X78FA4EF079BEA275}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{GUARANA.Tr{\textunderscore}n{\textunderscore}O1({\mdseries\slshape n})\index{GUARANA.TrnO1@\texttt{GUA}\-\texttt{R}\-\texttt{A}\-\texttt{N}\-\texttt{A.}\-\texttt{Tr{\textunderscore}n{\textunderscore}O1}}
\label{GUARANA.TrnO1}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{GUARANA.Tr{\textunderscore}n{\textunderscore}O2({\mdseries\slshape n})\index{GUARANA.TrnO2@\texttt{GUA}\-\texttt{R}\-\texttt{A}\-\texttt{N}\-\texttt{A.}\-\texttt{Tr{\textunderscore}n{\textunderscore}O2}}
\label{GUARANA.TrnO2}
}\hfill{\scriptsize (function)}}\\


 for a positive integer \mbox{\texttt{\mdseries\slshape n}} these functions construct polycyclically presented groups that can be used to
test the Mal'cev collector. They return a list which can be used as input for
the function MalcevCollectorConstruction. The constructed groups are
isomorphic to triangular matrix groups of dimension \mbox{\texttt{\mdseries\slshape n}} over the ring $O_1$, respectively $O_2$. The ring $O_1$, respectively $O_2$, is the maximal order of $\mathbb{Q}(\theta_i)$ where $\theta_1$, respectively $\theta_2$, is a zero of the polynomial $p_1(x) = x^2-3$, respectively $p_2(x)=x^3 -x^2 +4$. }

 

\subsection{\textcolor{Chapter }{GUARANA.F{\textunderscore}2c{\textunderscore}Aut1}}
\logpage{[ 3, 1, 3 ]}\nobreak
\hyperdef{L}{X86FA27828711BB51}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{GUARANA.F{\textunderscore}2c{\textunderscore}Aut1({\mdseries\slshape c})\index{GUARANA.F2cAut1@\texttt{GUA}\-\texttt{R}\-\texttt{A}\-\texttt{N}\-\texttt{A.}\-\texttt{F{\textunderscore}2c{\textunderscore}}\-\texttt{Aut1}}
\label{GUARANA.F2cAut1}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{GUARANA.F{\textunderscore}3c{\textunderscore}Aut1({\mdseries\slshape c})\index{GUARANA.F3cAut1@\texttt{GUA}\-\texttt{R}\-\texttt{A}\-\texttt{N}\-\texttt{A.}\-\texttt{F{\textunderscore}3c{\textunderscore}}\-\texttt{Aut1}}
\label{GUARANA.F3cAut1}
}\hfill{\scriptsize (function)}}\\


 for a positive integer \mbox{\texttt{\mdseries\slshape c}} these functions construct polycyclically presented groups that can be used to
test the Mal'cev collector. They return a list which can be used as input for
the function MalcevCollectorConstruction. These groups are constructed as
follows: Let $F_{n,c}$ be the free nilpotent of class $c$ group on $n$ generators. An automorphism $\varphi$ of the free group $F_n$ naturally induces an automorphism $\bar{\varphi}$ of $F_{n,c}$. We use the automorphism $\varphi_1$ of $F_2$ which maps $f_1$ to $f_2^{-1}$ and $f_2$ to $f_1 f_2^3$ and the automorphism $\varphi_2$ of $F_3$ mapping $f_1$ to $f_2^{-1}$, $f_2$ to $f_3^{-1}$ and $f_3$ to $f_2^{-3}f_1^{-1}$ for our construction. The returned group
F{\textunderscore}2c{\textunderscore}Aut1, respectively
F{\textunderscore}3c{\textunderscore}Aut2, is isomorphic to the semidirect
product $\langle \varphi_1 \rangle \ltimes F_{2,c}$, respectively $\langle \varphi_2 \rangle \ltimes F_{3,c}$. }

 

\subsection{\textcolor{Chapter }{MalcevGElementByExponents}}
\logpage{[ 3, 1, 4 ]}\nobreak
\hyperdef{L}{X79D925AD7AFF1202}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{MalcevGElementByExponents({\mdseries\slshape malCol, exps})\index{MalcevGElementByExponents@\texttt{MalcevGElementByExponents}}
\label{MalcevGElementByExponents}
}\hfill{\scriptsize (function)}}\\


 For a Mal'cev collector \mbox{\texttt{\mdseries\slshape malCol}} of a group $G$ and an exponent vector \mbox{\texttt{\mdseries\slshape exps}} with integer entries, this functions returns the group element of $G$, which has exponents \mbox{\texttt{\mdseries\slshape exps}} with respect to the polycyclic sequence underlying \mbox{\texttt{\mdseries\slshape malCol}}. }

 

\subsection{\textcolor{Chapter }{Random}}
\logpage{[ 3, 1, 5 ]}\nobreak
\hyperdef{L}{X79730D657AB219DB}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{Random({\mdseries\slshape malCol, range})\index{Random@\texttt{Random}}
\label{Random}
}\hfill{\scriptsize (function)}}\\


 For a Mal'cev collector \mbox{\texttt{\mdseries\slshape malCol}} this function returns the output of MalcevGElementByExponents( \mbox{\texttt{\mdseries\slshape malCol}}, \mbox{\texttt{\mdseries\slshape exps}} ), where \mbox{\texttt{\mdseries\slshape exps}} is an exponent vector whose entries are randomly chosen integers between -\mbox{\texttt{\mdseries\slshape range}} and \mbox{\texttt{\mdseries\slshape range}}. }

 

\subsection{\textcolor{Chapter }{*}}
\logpage{[ 3, 1, 6 ]}\nobreak
\hyperdef{L}{X7857704878577048}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{*({\mdseries\slshape g, h})\index{*@\texttt{*}}
\label{*}
}\hfill{\scriptsize (function)}}\\


 Returns the product of group elements which are defined with respect to a
Mal'cev collector by the the function MalcevGElementByExponents. }

 

\subsection{\textcolor{Chapter }{GUARANA.AverageRuntimeCollec}}
\logpage{[ 3, 1, 7 ]}\nobreak
\hyperdef{L}{X7DD44FEE7DE4E810}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{GUARANA.AverageRuntimeCollec({\mdseries\slshape malCol, ranges, no})\index{GUARANA.AverageRuntimeCollec@\texttt{GUARANA.AverageRuntimeCollec}}
\label{GUARANA.AverageRuntimeCollec}
}\hfill{\scriptsize (function)}}\\


 For a Mal'cev collector \mbox{\texttt{\mdseries\slshape malCol}}, a list of positive integers \mbox{\texttt{\mdseries\slshape ranges}} and a positive integer \mbox{\texttt{\mdseries\slshape no}} this function computes for each number \mbox{\texttt{\mdseries\slshape r}} in \mbox{\texttt{\mdseries\slshape ranges}} the average runtime of \mbox{\texttt{\mdseries\slshape no}} multiplications of two random elements of \mbox{\texttt{\mdseries\slshape malCol}} of range \mbox{\texttt{\mdseries\slshape r}}, as generated by Random( \mbox{\texttt{\mdseries\slshape malCol}}, \mbox{\texttt{\mdseries\slshape r}} ). }

 }

 
\section{\textcolor{Chapter }{An example application }}\logpage{[ 3, 2, 0 ]}
\hyperdef{L}{X81CAD2F27B2066C4}{}
{
  
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  		gap> ll := GUARANA.Tr_n_O1( 3 );
  		[ Pcp-group with orders [ 2, 2, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0 ],
  		  [ [ 1 .. 3 ], [ 4 .. 6 ], [ 7 .. 12 ] ],
  		  Pcp-group with orders [ 0, 0, 0, 0, 0, 0 ],
  		  Pcp-group with orders [ 0, 0, 0, 0, 0, 0 ],
  		  Pcp-group with orders [ 0, 0, 0 ], Pcp-group with orders [ 0, 0, 0 ] ]
  		gap> malCol := MalcevCollectorConstruction( ll );
  		<<Malcev collector>>
  		  F : [ 2, 2, 2 ]
  		  C : <<Malcev object of dimension 3>>
  		  N : <<Malcev object of dimension 6>>
  		
  		gap> exps_g := [ 1, 1, 1, -3, -2, 1, -2, -1, 0, 3, -1,3 ];
  		[ 1, 1, 1, -3, -2, 1, -2, -1, 0, 3, -1, 3 ]
  		gap> exps_h := [ 1, 0, 1, -1, 0, 2, 0, 4, -1, 5, 9,-5 ];
  		[ 1, 0, 1, -1, 0, 2, 0, 4, -1, 5, 9, -5 ]
  		gap> g := MalcevGElementByExponents( malCol, exps_g );
  		[ 1, 1, 1, -3, -2, 1, -2, -1, 0, 3, -1, 3 ]
  		gap> h := MalcevGElementByExponents( malCol, exps_h );
  		[ 1, 0, 1, -1, 0, 2, 0, 4, -1, 5, 9, -5 ]
  		
  		gap> k := g*h;
  		[ 0, 1, 0, -4, -2, 3, -7, 0, -37, -16, -352, -212 ]
  				
  		gap> Random( malCol, 10 );
  		[ 0, 0, 1, 9, 5, 5, 2, -2, 7, -10, 7, -6 ]
  		
  		
\end{Verbatim}
 }

 }

 
\chapter{\textcolor{Chapter }{Installation }}\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X8360C04082558A12}{}
{
  
\section{\textcolor{Chapter }{Installing this package }}\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X81746D7285808409}{}
{
  The Guarana package is part of the standard distribution of \textsf{GAP} and so normally there should be no need to install it separately. If by any
chance it is not part of your \textsf{GAP} distribution, then the standard method is to unpack the package into the `pkg'
directory of your \textsf{GAP} distribution. This will create a `guarana' subdirectory. For other
non-standard options please see Chapter  (\textbf{Reference: Installing a GAP Package}) of the \textsf{GAP} Reference Manual. Note that the GAP-Packages Polycyclic and Polenta are needed
for this package. Normally they should be contained in your distribution. If
not, they can be obtained at \href{http://www.gap-system.org/Packages/packages.html} {\texttt{http://www.gap-system.org/Packages/packages.html}}  }

 
\section{\textcolor{Chapter }{Loading the Guarana package }}\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X7F5D393E81A24451}{}
{
  If the \textsf{Guarana} Package is not already loaded then you have to request it explicitly. This can
be done by `LoadPackage("guarana")'. The `LoadPackage' command is described in
Section  (\textbf{Reference: LoadPackage}) in the \textsf{GAP} Reference Manual. }

 
\section{\textcolor{Chapter }{Running the test suite }}\logpage{[ 4, 3, 0 ]}
\hyperdef{L}{X796DF52483B61C74}{}
{
  Once the package is installed, it is possible to check the correct
installation by running the test suite of the package. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  	gap> Read(Filename(DirectoriesPackageLibrary("guarana","tst")[1],"testall.g"));
  	
\end{Verbatim}
 Note that this now disables running of the tests in tst/guarana2.tst, since
these require alnuth which in turn requires kash/kant. If your system has
these prerequisites in place you can manually run those test examples as
follows. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  	gap> ReadTest(Filename(DirectoriesPackageLibrary("guarana","tst")[1],"guarana2.tst"));
  	
\end{Verbatim}
 For more details on Test Files see Section  (\textbf{Reference: Test Files}) of the \textsf{GAP} Reference Manual. If the test suite runs into an error, then please send a
message to `jjm@mcs.st-andrews.ac.uk' including the error message. }

 }

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

\bibliographystyle{alpha}
\bibliography{manual}

\addcontentsline{toc}{chapter}{References}

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

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


\printindex

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