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

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

\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\begin{center}{\Huge \textbf{MapClass\mbox{}}}\\[1cm]
\hypersetup{pdftitle=MapClass}
\markright{\scriptsize \mbox{}\hfill MapClass \hfill\mbox{}}
{October 2011\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\large \textbf{ Adam James  \mbox{}}}\\
{\large \textbf{ Kay Magaard  \mbox{}}}\\
{\large \textbf{ Sergey Shpectorov  \mbox{}}}\\
{\large \textbf{ Helmut V{\"o}lklein  \mbox{}}}\\
\hypersetup{pdfauthor= Adam James  ;  Kay Magaard  ;  Sergey Shpectorov  ;  Helmut V{\"o}lklein  }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{ Adam James  } --- Email: \href{mailto://jamesa@maths.bham.ac.uk} {\texttt{jamesa@maths.bham.ac.uk}}}\\
{\mbox{}\\
\small \noindent \textbf{ Kay Magaard  } --- Email: \href{mailto://K.Magaard@maths.bham.ac.uk} {\texttt{K.Magaard@maths.bham.ac.uk}}}\\
{\mbox{}\\
\small \noindent \textbf{ Sergey Shpectorov  } --- Email: \href{mailto://s.shpectorov@bham.ac.uk} {\texttt{s.shpectorov@bham.ac.uk}}}\\
{\mbox{}\\
\small \noindent \textbf{ Helmut V{\"o}lklein  } --- Email: \href{mailto://voelkle@iem.uni-due.de} {\texttt{voelkle@iem.uni-due.de}}}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
 {\copyright} 2004-2011 by Adam James, Kay Magaard Sergey Shpectorov, and
Helmut V{\"o}lklein 

 MapClass is free software you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version. For details, see the file 'GPL' in the 'etc' directory of the GAP
distribution or see the FSF's own site.\mbox{}}\\[1cm]
\newpage

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

\tableofcontents
\newpage

  
\chapter{\textcolor{Chapter }{Introduction and Main Functions}}\label{ch:intro}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X7B9EBA44836A7F7D}{}
{
 This chapter provides an overview of the background material, and provides
documentation for the main functions and data structures of the MapClass
package. 
\section{\textcolor{Chapter }{Background Material}}\label{sec:background}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X7929306C7A98029D}{}
{
 \index{Overview} Let $G$ be a finite group, let $C_1,\ldots, C_r$ be a collection of conjugacy classes in $G$. Let $\mathcal{E} = \mathcal{E}(G,g,(C_1, \dots, C_r))$ denote the set of all tuples $ \sigma = (\sigma_1,...,\sigma_{2g+r})\in G^{2g+r}$ (for natural numbers $g$ and $r$) of elements in $G$ satisfying the relation 
\[ \prod_{i=1}^g [\sigma_i, \sigma_{g+i}] \prod_{i=1}^r \sigma_{2g+i} = 1 \]
 and such that $\sigma_{2g +k} \in C_k$. If the tuple also satisfies $\langle \sigma_1, \ldots, \sigma_{2g+r}\rangle = G$ it is said to be \emph{generating}.

 One may associate the elements of the tuple $\sigma$ with the standard generators of the fundamental group of a compact connected
surface $S$ (genus $g$, $r$ punctures). The mapping class group of $S$ is naturally isomorphic to $Out(\pi_1(S))$ and so gives rise to an action on the fundamental group of $S$ modulo inner automorphisms. This action can be transferred to an action on the
set $\mathcal{E}$ (up to conjugation in $G$). The \emph{mapping class orbits} are the orbits of $\mathcal{E}$ under this action. 

 The package can be used to compute the set $\mathcal{E}(G, g, (C_1,\ldots,C_r))$ and the corresponding partition into mapping class orbits for a given group $G$ and a set of conjugacy classes $(C_1,...,C_r)$ (although the programs expect a tuple of class representatives). For an
example application see Section \ref{sec:application}. We call the tuple $(g;C_1,...,C_r)$ the signature. The package is an extension of the \emph{Braid} package for \textsf{GAP}. 

 }

 
\section{\textcolor{Chapter }{Overview of Main Functions}}\label{mainfunction}
\logpage{[ 1, 2, 0 ]}
\hyperdef{L}{X7D47DF997A20A44A}{}
{
 The following are the principal ways for calculating the mapping class orbits
for a given signature and group. We require our groups to be permutation
groups, and the tuple in question to have length at least two. 

\subsection{\textcolor{Chapter }{AllMCOrbits}}
\logpage{[ 1, 2, 1 ]}\nobreak
\hyperdef{L}{X7820883E8607F7AF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AllMCOrbits({\slshape group, genus, tuple})\index{AllMCOrbits@\texttt{AllMCOrbits}}
\label{AllMCOrbits}
}\hfill{\scriptsize (function)}}\\


 This function calculates the orbits for the given group, genus and tuple. This
function is a wrapper for the function \texttt{AllMCOrbitsCore} (\ref{AllMCOrbitsCore}), and so can make use of GAP's \texttt{OptionsStack}. The options are described in more detail in the documentation for \texttt{AllMCOrbitsCore} (\ref{AllMCOrbitsCore}). We draw attention to two useful options: the \texttt{OutputStyle} and \texttt{SaveOrbit} options. The \texttt{SaveOrbit} option takes values of either \texttt{false} - in which case the orbit is not saved to a file - or it accepts a string that
is the name of a directory in which the routine saves the orbits. See \texttt{AllMCOrbitsCore} (\ref{AllMCOrbitsCore}) for more details on the saving process. The \texttt{ OutputStyle } option controls the verbosity of the output of the function. It accepts three
possible values: 
\begin{itemize}
\item  \texttt{"silent"} -- the routine prints no output except in the case of an Error. 
\item  \texttt{"single-line"} -- the routine prints output to a single line. An intermediate output style
for those who want some output but do not want to see all diagnostic output. 
\item  \texttt{"full"} -- the routine provides full diagnostic output. 
\end{itemize}
 }

 

\subsection{\textcolor{Chapter }{AllMCOrbitsCore}}
\logpage{[ 1, 2, 2 ]}\nobreak
\hyperdef{L}{X791C18967E0DFC70}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{AllMCOrbitsCore({\slshape group, genus, tuple, partition, constant})\index{AllMCOrbitsCore@\texttt{AllMCOrbitsCore}}
\label{AllMCOrbitsCore}
}\hfill{\scriptsize (function)}}\\


 This function calculates the orbits for the given group, genus and tuple, with
the $r$ branch points partitioned as in \mbox{\texttt{\slshape partition}}. It uses the given \mbox{\texttt{\slshape constant}} to determine how many of the tuples it want to account for before exiting.
This function also make use of GAP's \texttt{OptionsStack} if one desires to alter how the algorithm runs. The following options and
their defaults are given below. \begin{center}
\begin{tabular}{|r|c|}\hline
Option Name&
Default Value\\
\hline
\texttt{MaximumWeight}&
40 \\
\texttt{MinimumWeight}&
20 \\
\texttt{InitialWeight}&
20 \\
\texttt{BumpUp}&
7\\
\texttt{KnockDown}&
7\\
\texttt{InitialNumberOfRandomTuples }&
20\\
\texttt{ SaveOrbit }&
 \texttt{false} \\
\texttt{ OutputStyle }&
 \texttt{"full"} \\
\hline
\end{tabular}\\[2mm]
\end{center}

 When trying to search for orbits it can be the case that the routine struggles
to find a small orbit because of the low probability of randomly choosing a
tuple in the orbit. To combat this problem the routine does not choose tuples
entirely randomly but uses a weighted random selection to increase the
probability of selecting tuples appearing in small tuples. To small subgroups
of our group we have an associated weight. When a subgroup is generated by a
tuple in our orbit frequently then we reduce its weight. Subgroups which do
not appear often have their weight increased. The options \texttt{MaximumWeight}, \texttt{MinimumWeight}, \texttt{InitialWeight},\texttt{BumpUp}, and \texttt{KnockDown}, control this subgroup weighting. Each option takes positive integer values.
They play the following roles in the weighting process: 
\begin{itemize}
\item \texttt{MaximumWeight} : The maximum weight that a subgroup can be. 
\item \texttt{MinimumWeight} : The minimum weight that a subgroup can be. 
\item \texttt{InitialWeight} : The weight that a new subgroup receives when added to to the list of small
subgroups. 
\item \texttt{BumpUp} : The amount we increase the weight of a subgroup by when it does not appear
frequently. 
\item \texttt{KnockDown} : The amount we decrease the weight of a subgroup by when it appears too
frequently. 
\end{itemize}
 The default options were chosen experimentally and so it may be beneficial to
tune these values for a specific case.

 The option \texttt{InitialNumberOfRandomTuples} decides how many tuples the routine collects before trying to see if they are
in some pre-existing orbit.

 The option \texttt{SaveOrbit} which is by default \texttt{false} can be set to the name of a directory in which you want to save orbits. This
option then saves the orbits to files in the folder with "\texttt{{\textunderscore}name}". So for example if you wish to save your orbits into the file \texttt{{\textunderscore}example} then you would run \texttt{AllMCOrbits(group, genus, tuple: SaveOrbit:="example");}. The orbits are then saved in orbits which are named numerically. Following
on from the above example then the first orbit will be saved as
"{\textunderscore}example/0". The \texttt{ OutputStyle } option controls the verbosity of the output. It accepts three possible values: 
\begin{itemize}
\item  \texttt{"silent"} - the routine prints no output except in the case of an Error. 
\item  \texttt{"single-line"} - the routine output to a single line. An intermediate output style for those
who want some output but do not want to see all diagnostic output. 
\item  \texttt{"full"} - the routine provides full diagnostic output. 
\end{itemize}
 }

 

\subsection{\textcolor{Chapter }{GeneratingMCOrbits}}
\logpage{[ 1, 2, 3 ]}\nobreak
\hyperdef{L}{X7EFE8AF479347734}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GeneratingMCOrbits({\slshape group, genus, tuple})\index{GeneratingMCOrbits@\texttt{GeneratingMCOrbits}}
\label{GeneratingMCOrbits}
}\hfill{\scriptsize (function)}}\\


 This calculates the orbits for the given arguments. Unlike the \texttt{AllMCOrbits} (\ref{AllMCOrbits}) function, \texttt{GeneratingMCOrbits} calculates only those orbits whose tuples generate the whole of our original
group. }

 

\subsection{\textcolor{Chapter }{GeneratingMCOrbitsCore}}
\logpage{[ 1, 2, 4 ]}\nobreak
\hyperdef{L}{X8383CA687FFFC2EF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GeneratingMCOrbitsCore({\slshape group, genus, tuple, partition, constant})\index{GeneratingMCOrbitsCore@\texttt{GeneratingMCOrbitsCore}}
\label{GeneratingMCOrbitsCore}
}\hfill{\scriptsize (function)}}\\


 This calculates the orbits for the given arguments. Unlike the \texttt{AllMCOrbits} (\ref{AllMCOrbits}) function, \texttt{GeneratingMCOrbitsCore} calculates only those orbits whose tuples generate the whole of our original
group. As with \texttt{AllMCOrbitsCore} (\ref{AllMCOrbitsCore}), the argument \mbox{\texttt{\slshape partition}} must be a partition of the conjugacy classes represented in list form. We also
have access to the full value of the options stack as in \texttt{AllMCOrbitsCore} (\ref{AllMCOrbitsCore}). }

 

\subsection{\textcolor{Chapter }{MappingClassOrbit}}
\logpage{[ 1, 2, 5 ]}\nobreak
\hyperdef{L}{X84D605BD79533A1E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MappingClassOrbit({\slshape group, genus, principaltuple, partition, tuple})\index{MappingClassOrbit@\texttt{MappingClassOrbit}}
\label{MappingClassOrbit}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 an orbit record for an orbit containing tuple or returns \texttt{fail} 



 Calculates the orbit of the \mbox{\texttt{\slshape tuple}} with respect to the given \mbox{\texttt{\slshape group}}, \mbox{\texttt{\slshape principaltuple}} and \mbox{\texttt{\slshape genus}}. }

 

\subsection{\textcolor{Chapter }{PrepareMinTree}}
\logpage{[ 1, 2, 6 ]}\nobreak
\hyperdef{L}{X7E26117582BDD678}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{PrepareMinTree({\slshape principaltuple, group, ourR, genus})\index{PrepareMinTree@\texttt{PrepareMinTree}}
\label{PrepareMinTree}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a record with two keys \texttt{MinimizationTree} and \texttt{MinimumSet}. If \texttt{record} is the returned record then \texttt{record.MinimizationTree} is the list encoding the tree used to help minimize tuples. The list \texttt{ record.MinimumSet} is a list of minimal elements which is also used to speed up tuple
minimization. 

}

 

\subsection{\textcolor{Chapter }{MinimizeTuple}}
\logpage{[ 1, 2, 7 ]}\nobreak
\hyperdef{L}{X7D9564417E8C1A00}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MinimizeTuple({\slshape tuple, minimizationTree, minimumSet, numberOfGenerators})\index{MinimizeTuple@\texttt{MinimizeTuple}}
\label{MinimizeTuple}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the minimal tuple in the same orbit of \mbox{\texttt{\slshape tuple}}.



 Take the minimisation data provided by \texttt{PrepareMinTree} (\ref{PrepareMinTree}) and minimizes the given \mbox{\texttt{\slshape tuple}}. }

 

\subsection{\textcolor{Chapter }{EasyMinimizeTuple}}
\logpage{[ 1, 2, 8 ]}\nobreak
\hyperdef{L}{X7CA1E3A07A4F6270}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{EasyMinimizeTuple({\slshape group, genus, tuple})\index{EasyMinimizeTuple@\texttt{EasyMinimizeTuple}}
\label{EasyMinimizeTuple}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the minimal tuple in the same orbit as \mbox{\texttt{\slshape tuple}}.

}

 

\subsection{\textcolor{Chapter }{IsInOrbit}}
\logpage{[ 1, 2, 9 ]}\nobreak
\hyperdef{L}{X8469F8DC845C902D}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsInOrbit({\slshape orbit, tuple})\index{IsInOrbit@\texttt{IsInOrbit}}
\label{IsInOrbit}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{True} if the \mbox{\texttt{\slshape tuple}} lies in the \mbox{\texttt{\slshape orbit}}.

}

 

\subsection{\textcolor{Chapter }{FindTupleInOrbit}}
\logpage{[ 1, 2, 10 ]}\nobreak
\hyperdef{L}{X7930B90F8572763B}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FindTupleInOrbit({\slshape orbit, tuple})\index{FindTupleInOrbit@\texttt{FindTupleInOrbit}}
\label{FindTupleInOrbit}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the index of \mbox{\texttt{\slshape tuple}} in \texttt{orbit.TupleTable} if in the \mbox{\texttt{\slshape orbit}}. If the tuple is not in \mbox{\texttt{\slshape orbit}} returns \texttt{fail}. 

}

 

\subsection{\textcolor{Chapter }{IsEqualOrbit}}
\logpage{[ 1, 2, 11 ]}\nobreak
\hyperdef{L}{X7975937984C559FC}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsEqualOrbit({\slshape orbit1, orbit2})\index{IsEqualOrbit@\texttt{IsEqualOrbit}}
\label{IsEqualOrbit}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
\texttt{true} if the two orbits are equal else returns \texttt{fail}. 

}

 

\subsection{\textcolor{Chapter }{SelectTuple}}
\logpage{[ 1, 2, 12 ]}\nobreak
\hyperdef{L}{X815C513B789565CF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SelectTuple({\slshape orbit, index})\index{SelectTuple@\texttt{SelectTuple}}
\label{SelectTuple}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the tuple \texttt{orbit.TupleTable[index].tuple}. 

}

 

\subsection{\textcolor{Chapter }{NumberGeneratingTuples}}
\logpage{[ 1, 2, 13 ]}\nobreak
\hyperdef{L}{X7B772B3C8275F5DD}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NumberGeneratingTuples({\slshape group, partition, tuple, genus})\index{NumberGeneratingTuples@\texttt{NumberGeneratingTuples}}
\label{NumberGeneratingTuples}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the total number of possible generating tuples for the group and tuple. 

}

 

\subsection{\textcolor{Chapter }{TotalNumberTuples}}
\logpage{[ 1, 2, 14 ]}\nobreak
\hyperdef{L}{X7D054A867DC96522}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{TotalNumberTuples({\slshape group, tuple, genus})\index{TotalNumberTuples@\texttt{TotalNumberTuples}}
\label{TotalNumberTuples}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the total number of tuples we have to account for. 

}

 

\subsection{\textcolor{Chapter }{CalculateTuplePartition}}
\logpage{[ 1, 2, 15 ]}\nobreak
\hyperdef{L}{X855F49457DC386AF}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{CalculateTuplePartition({\slshape group, tuple})\index{CalculateTuplePartition@\texttt{CalculateTuplePartition}}
\label{CalculateTuplePartition}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 A partition of ${1,\ldots, r}$ where $r$ is the length of the tuple. 



 The function returns a partition of ${1,\ldots, r}$ such that $i$ and $j$ lie in the same block if and only if the elements \texttt{tuple[i]} and \texttt{tuple[j]} are member of the same conjugacy class. The program currently requires that
the elements of the tuple be ordered such that if \texttt{tuple[i]} and \texttt{tuple[j]} are in the same conjugacy class with $i \le j$ then so is\texttt{tuple[k]} for all $i \le k \le j$. }

 

\subsection{\textcolor{Chapter }{RestoreOrbitFromFile}}
\logpage{[ 1, 2, 16 ]}\nobreak
\hyperdef{L}{X86EA79C9873E3141}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RestoreOrbitFromFile({\slshape n, name[, path]})\index{RestoreOrbitFromFile@\texttt{RestoreOrbitFromFile}}
\label{RestoreOrbitFromFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the n-th orbit record from the project with project \texttt{"name"} 



 By default the function searches the current working directory for the saved
project folder and searches inside this for the n-th orbit. If no such orbit
exists it returns \texttt{fail}. If an optional argument \mbox{\texttt{\slshape path}} is provided then it searches this path for a folder with the name specified
(note that path expects a \texttt{Directory} object). If an orbit exists then it is returned as a record as outlined in the
data structure section. }

 

\subsection{\textcolor{Chapter }{SaveOrbitToFile}}
\logpage{[ 1, 2, 17 ]}\nobreak
\hyperdef{L}{X82F6093885ECD889}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SaveOrbitToFile({\slshape orbit, n, name})\index{SaveOrbitToFile@\texttt{SaveOrbitToFile}}
\label{SaveOrbitToFile}
}\hfill{\scriptsize (function)}}\\


 Saves the orbit to filename "\mbox{\texttt{\slshape n}}" in the directory \texttt{'{\textunderscore}name'}. The directory must already exist. }

 }

 
\section{\textcolor{Chapter }{Key Data Structures}}\label{datastructures}
\logpage{[ 1, 3, 0 ]}
\hyperdef{L}{X83EB578D85D98DF5}{}
{
 Many of the above functions require or return key data structures which we aim
to document. 
\subsection{\textcolor{Chapter }{The Orbit Record}}\label{orbitrecord}
\logpage{[ 1, 3, 1 ]}
\hyperdef{L}{X84FDC7BD82227DA8}{}
{
 Many of the functions return or expect an orbit "object". This object is in
fact record with the following values: 
\begin{itemize}
\item  \texttt{PrincipalFiniteGroup }- the finite group 
\item  \texttt{OurG }- genus 
\item  \texttt{OurR }- length of our primary tuple 
\item  \texttt{OurN }- number of points on which our group acts 
\item  \texttt{NumberOfGenerators }- 2 \texttt{OurG}+ \texttt{OurR } 
\item  \texttt{OurFreeGroup }- a free group on \texttt{NumberOfGenerators }letters 
\item  \texttt{AbsGens }- generators for \texttt{OurFreeGroup} 
\item  \texttt{OurAlpha } - generators of \texttt{OurFreeGroup}corresponding to the $\alpha_i$ type loops in the fundamental group ( the first $g$ elements of \texttt{AbsGens}) 
\item  \texttt{OurBeta }- elements of \texttt{OurFreeGroup }corresponding to $\beta$ type loops 
\item  \texttt{OurGamma }- generators of \texttt{OurFreeGroup }corresponding to the loops around branch points 
\item  \texttt{TupleTable }- a table containing all the tuples in the orbit 
\item \texttt{HashLength}
\item \texttt{Hash}
\item \texttt{PrimeCode}
\item \texttt{OurAction}
\item \texttt{ActionOnOrbit}
\item \texttt{MinimizationTree}- minimization structure
\item \texttt{MinimumSet}- minimizaton structure
\end{itemize}
 }

 
\subsection{\textcolor{Chapter }{The Tuple Table}}\label{tupletable}
\logpage{[ 1, 3, 2 ]}
\hyperdef{L}{X7CEE3F9180497635}{}
{
  The tuple table is a list. Each element of the list is a record with the
names, tuple and next. If \texttt{orbit} is an orbit object then \texttt{orbit.TupleTable[n].tuple} returns the tuple at index $n$ of the tuple table. }

 }

 
\section{\textcolor{Chapter }{A Sample Session}}\logpage{[ 1, 4, 0 ]}
\hyperdef{L}{X81D1E049865AE89E}{}
{
 We demonstate how one might use the package. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
              gap> group:=AlternatingGroup(5);
              Alt( [ 1 .. 5 ] )
              gap> tuple:=[ (1,2)(3,4), (1,2)(3,4), (1,2)(3,4) ]
              [ (1,2)(3,4), (1,2)(3,4), (1,2)(3,4) ]
              gap> orbits:=AllMCOrbits(group,1,tuple);;
  
              Total Number of Tuples: 189120
  
  
              Collecting 20 random tuples... done
  
              Cleaning done; 20 random tuples remaining
  
  
              Orbit 1:
                                                                                    
              Length=3072
              Generating Tuple  =[ (1,2,4,5,3), (1,4,5,2,3), (1,2)(4,5),
              (1,4)(2,3), (2,5)(3,4) ]
              Generated subgroup size=60
              Centralizer size=1
              4800 tuples remaining
              Cleaning current orbit...
              Cleaning a list of 20 tuples
              Random Tuples Remaining: 0
              Cleaning done; 0 random tuples remaining
  
  
              Collecting 20 random tuples... done
  
              Cleaning orbit 1
              Cleaning a list of 20 tuples
              Random Tuples Remaining: 0
  
              Cleaning done; 0 random tuples remaining
  
  
              Collecting 40 random tuples... done
  
              Cleaning orbit 1
              Cleaning a list of 40 tuples
              Random Tuples Remaining: 3
  
              Cleaning done; 3 random tuples remaining
  
  
              Orbit 2:
                                                                                    
              Length=32
              Generating Tuple  =[ (1,4)(2,3), (1,2)(3,4), (1,4)(2,3), (1,2)(3,4),
              (1,3)(2,4) ]
              Generated subgroup size=4
              Centralizer size=4
              4320 tuples remaining
              Cleaning current orbit...
              Cleaning a list of 3 tuples
              Random Tuples Remaining: 2
              Cleaning done; 2 random tuples remaining
  
  
              Orbit 3:
                                                                                    
              Length=72
              Generating Tuple  =[ (1,5,2), (1,3,2), (1,2)(3,5), (1,3)(2,5),
              (1,3)(2,5) ]
              Generated subgroup size=12
              Centralizer size=1
              0 tuples remaining
              Cleaning current orbit...
              Cleaning a list of 2 tuples
              Random Tuples Remaining: 0
              Cleaning done; 0 random tuples remaining
  
              gap> # Check we have as many orbits as it says...
              gap> Length(orbits);
              3
              gap> # Inspect the first orbit..
              gap> orb1:=orbits[1];;
              gap> # How long is orb1?
              gap> Length(orb1.TupleTable);
              3072
              gap> # Select element 42 ...
              gap> SelectTuple(orb1, 42);
              [ (1,3,4), (1,5,3,2,4), (1,5)(2,4), (1,2)(3,5), (2,3)(4,5) ]
              gap> # Save the orbit to a file...
              gap> SaveOrbitToFile(orb1, 1, "test");
              gap> #If the folder doesn't exist we get an error..
              gap> SaveOrbitToFile(orb1, 1, "foo");
              AppendTo: cannot open '_foo/1' for output at
              CallFuncList( APPEND_TO, arg );
              gap> #
              gap> # Now we try find generating orbits 
              gap> group:=SymmetricGroup(5);
              Sym( [ 1 .. 5 ] )
              gap> # And we will save them using the `SaveOrbit` option
              gap> GeneratingMCOrbits(group,1,tuple : SaveOrbit:="example");;
  
              Total Number of Tuples: 607680
  
  
  
              Collecting 20 generating tuples .. done
  
              Cleaning done; 20 random tuples remaining
  
  
              Orbit 1:                    
              Length=5064
              Generating Tuple  =[ (1,3,2,5), (2,4,3), (1,4)(3,5), (1,3)(2,5),
              (1,4)(3,5) ]
              Generated subgroup size=120
              Saving orbit to file _example/0
              Centralizer size=1
              0 tuples remaining
              Cleaning current orbit...
              Cleaning a list of 20 tuples
              Random Tuples Remaining: 0
              Cleaning done; 0 random tuples remaining
  
              gap> generatingorbits:=last;;
              gap> # How many generating orbits are there?
              gap> Length(generatingorbits);
              1
              gap> # Is this orbit equal to the other one we found earlier
              gap> IsEqualOrbit(orb1, generatingorbits[1]);
              fail
              gap> # We can reload the orbits...
              gap> orb2:=RestoreOrbitFromFile(0, "example");;
              gap> Length(orb2.TupleTable);
              5064
          
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{An Application}}\label{sec:application}
\logpage{[ 1, 5, 0 ]}
\hyperdef{L}{X7A3C63AC854BCF4C}{}
{
 This section describes an application of the package. 

 Let $X$ be a compact Riemann surface of genus $g$ and $f: X \rightarrow \mathbb{P}^1\mathbb{C}$ be a meromorphic function of degree $n$. Let $B$ be the set of branch points for $f$ and fix a basepoint $b_0 \in \mathbb{P}^1\mathbb{C}- B$. The fundamental group $\pi_1(\mathbb{P}^1 \mathbb{C} - B, b_0) $ acts transitively on the fibre $f^{-1}(b_0)$ and this corresponds to a representation 
\[ f^* :\pi_1(\mathbb{P}^1 \mathbb{C} - B, b_0) \rightarrow S_n \]
 The image of $f^*$ is called the \emph{monodromy group} of $(X, f)$. The fundamental group of the punctured Riemann sphere is generated by the
loops that wind around the points in $B$. Label the branch points $b_1,...,b_r$ and let $\tau_i $ be the image under $f^*$ of the loop, $\gamma_i \in \pi_1(\mathbb{P}^1\mathbb{C} - B)$, that winds once around the point $b_i\in B$. Therefore, 
\[ \langle \tau_1, ..., \tau_r \rangle = G \]
 and 
\[ \tau_1 \cdots \tau_r = 1 \]
 Moreover by the Riemann-Hurwitz formula 
\[ 2(n+g-1) = \sum_1^r {ind}( \tau_i) \]
 where the ${ind}(\tau_i)$ is the minimal number of factors to express $\tau_i$ as a product of transpositions. A set $t_1, \ldots, t_r$ of elements of $S_n$ satisfying the Riemann-Hurwitz formula, the product-one condition, and
generating some transitive subgroup $G$ of $S_n$ is called a \emph{genus } $ g $ \emph{generating system } for $G$. Therefore to the meromorphic function $(X, f)$ there is an associated genus $g$ system. In fact the conjugacy classes of the elements $\tau_i$ are also determined by $f$ -- the collection of conjugacy classes is sometimes called the \emph{ ramification type} of $f$. On the other hand for every genus $ g$ generating system, $t = (\tau_1, \ldots, \tau_n)$ for $G$ there is Riemann surface of genus $g$ and a meromorphic function with associated generating system $t$ -- this result is known as \emph{ Riemann's Existence Theorem}.

 The question we hope to use our package to answer is: For a given finite group $G$ how many meromorphic maps with monodromy group $G$ are there? It can be shown -- see \cite{Volklein96} for example -- that determining whether two genus $g$ coverings are equivalent corresponds to determining whether their associated
genus $g$ systems are in the same mapping class orbit ( most literature would refer to
mapping class orbits as braid orbits in this case - this is because of the
equivalence between the mapping class group of a punctured disc and the braid
groups \cite{Birman75}). 

 Thus for a finite group $G$ we can answer the above principal question using the following process: 
\begin{itemize}
\item  For a given finite group $G$ the work of Breuer \cite{Breuer00} can be used to calculate all possible ramification types. 
\item  Pick a tuple, $C = (c_1,...,c_r)$, of representative elements of the conjugacy classes which correspond to a
chosen ramification type as calculated in the previous step. 
\item  Use the function \texttt{GeneratingMCOrbits(G, 0, [c1,...,cr])} to calculate the number of mapping class orbits. Note that the genus argument
is $0$ because this is the genus of $\mathbb{P}^1\mathbb{C}$. 
\end{itemize}
 For more information on this process and the underlying theory see \cite{MSV} and \cite{Volklein96}. }

 }

 

\appendix


\chapter{\textcolor{Chapter }{Installation}}\logpage{[ "A", 0, 0 ]}
\hyperdef{L}{X8360C04082558A12}{}
{
 To Install the package place the "MapClass" folder into your GAP system's
'pkg' directory. If you do not have permission to modify the gap package then
the package can be included by appending a local directory to GAP's root
directory using the '-l' flag. For more information on GAP's root directory
process try '?GAP root' in a GAP session. Or see the online help at
http://www.gap-system.org/Manuals/doc/htm/ref/CHAP009.htm\#SECT002 To Load the
package simply type 'LoadPackage("mapclass");'. If the load has been
successful the package banner will be shown. }

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

\bibliographystyle{alpha}
\bibliography{bib}

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


\printindex

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