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

\usepackage{fancyvrb}

\usepackage{pslatex}

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

% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
\newcommand{\Q}{\mathbb{Q}}
\newcommand{\R}{\mathbb{R}}
\newcommand{\C}{\mathbb{C}}
\newcommand{\Z}{\mathbb{Z}}
\newcommand{\N}{\mathbb{N}}
\newcommand{\F}{\mathbb{F}}

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

\newsavebox{\backslashbox}
\sbox{\backslashbox}{\texttt{\symbol{92}}}
\newcommand{\bs}{\usebox{\backslashbox}}

\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\begin{center}{\Huge \textbf{\textsf{Gpd}}}\\[1cm]
\hypersetup{pdftitle=\textsf{Gpd}}
\markright{\scriptsize \mbox{}\hfill \textsf{Gpd} \hfill\mbox{}}
{\Large \textbf{Groupoids, graphs of groups, and graphs of groupoids}}\\[1cm]
{Version 1.01}\\[1cm]
{June 2006}\\[1cm]
\mbox{}\\[2cm]
{\large \textbf{ Emma Moore  }}\\
{\large \textbf{ Chris Wensley    }}\\
\hypersetup{pdfauthor= Emma Moore  ;  Chris Wensley    }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{ Emma Moore  } --- Email: \href{mailto://emmajmoore@yahoo.co.uk}{\texttt{emmajmoore@yahoo.co.uk}}}\\
{\mbox{}\\
\small \noindent \textbf{ Chris Wensley    } --- Email: \href{mailto://c.d.wensley@bangor.ac.uk}{\texttt{c.d.wensley@bangor.ac.uk}}\\
 --- Homepage: \href{http://www.informatics.bangor.ac.uk/~cwensley/}{\texttt{http://www.informatics.bangor.ac.uk/\~{}cwensley/}}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 Department of Mathematics, University of Wales Bangor,\\
 Dean Street, Bangor, Gwynedd, LL57 1UT, U.K. \end{minipage}
}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Abstract}
\logpage{[ 0, 0, 1 ]}
 The \textsf{Gpd} share package for \textsf{GAP}4 provides functions for the computation with groupoids (categories with every
arrow invertible) and their morphisms; for graphs of groups, and graphs of
groupoids. 

 It provides normal forms for Free Products with Amalgamation and for
HNN-extensions when the initial groups have rewrite systems and the subgroups
have finite index. 

 The \textsf{Gpd} package was originally implemented in 2000 (as \textsf{GraphGpd}) when the first author was studying for a Ph.D. in Bangor. 

 Bug reports, suggestions and comments are, of course, welcome. Please contact
the second author at \href{mailto://c.d.wensley@bangor.ac.uk}{\texttt{c.d.wensley@bangor.ac.uk}}. }\\[1cm]
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 2 ]}
 {\copyright} 2000-2006 by Emma Moore and Chris Wensley 

 We adopt the copyright regulations of \textsf{GAP} as detailed in the copyright notice in the \textsf{GAP} manual. }\\[1cm]
\newpage

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

\tableofcontents
\newpage

           
\chapter{\textcolor{Chapter }{Introduction}}\label{intro}
\logpage{[ 1, 0, 0 ]}
{
  Groupoids are mathematical categories in which every arrow is invertible. The \textsf{Gpd} share package provides functions for the computation with groupoids and their
morphisms; for graphs of groups and graphs of groupoids. The package is far
from complete, and development continues. 

 It was used by Emma Moore in her thesis \cite{emma-thesis} to calculate normal forms for Free Products with Amalgamation, and for
HNN-extensions, when the initial groups have rewrite systems. 

 \textsf{Gpd} is implemented using {\GAP}~4.4. Some of the utility functions in the \textsf{XMod} share package for crossed modules are used. 

 The information parameter \texttt{InfoGpd} takes default value \texttt{1} which, for the benefit of new users, causes more messages to be printed out
when operations fail. When raised to a higher value, additional information is
printed out. 

 Help is available in the usual way. 

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> LoadPackage( "gpd" );
  ------------------------------------------------------------
  loading XMod 2.007 for GAP 4.4 - Murat Alp and Chris Wensley
  ------------------------------------------------------------
  -----------------------------------------------------------
  loading Gpd 1.01 for GAP 4.4 - Emma Moore and Chris Wensley
  -----------------------------------------------------------
  true
  gap> ?Groupoid
  Help: several entries match this topic - type ?2 to get match [2]
  
  [1] Gpd: Groupoid
  [2] loops (not loaded): groupoid
  [3] Gpd: Groupoids
  [4] Gpd: Groupoids: their elements and attributes
  [5] Gpd: GroupoidByUnion
  [6] Gpd: GroupoidElement
  [7] Gpd: GroupoidMorphismByComponents
  [8] Gpd: GroupoidMorphism
  [9] Gpd: GroupoidsOfGraphOfGroupoids
  
\end{Verbatim}
 You may reference this package by mentioning \cite{BrMoPoWe} and \cite{emma-thesis}. }

           
\chapter{\textcolor{Chapter }{Groupoids}}\label{chap-gpd}
\logpage{[ 2, 0, 0 ]}
{
  A \emph{groupoid} is a (mathematical) category in which every element is invertible. It consists
of a set of components, each of which is a connected groupoid. 

 A \emph{connected groupoid} is determined by a set of \emph{objects} \texttt{obs} and an \emph{object group} \texttt{grp}. Connected groupoids are represented as \texttt{IsConnectedGroupoidRep}, a record with components \texttt{objects} and \texttt{group}. The objects of a connected groupoid are generally chosen to be consecutive
negative integers, but any suitable ordered set is acceptable, and
`consecutive' is not a requirement. The object groups will usually be taken to
be permutation groups, but pc-groups and fp-groups are also supported. 

 A \emph{group} is a connected groupoid with one object. 

 A \emph{groupoid} is a set of one or more connected groupoids, its connected \emph{components}, and is represented as \texttt{IsGroupoidRep}, with attribute \texttt{ComponentsOfGroupoid}. 

 For the definitions of the standard properties of groupoids we refer to R.
Brown's book ``Topology'' \cite{BrTop}, recently revised and reissued as ``Topology and Groupoids'' \cite{BrTopGpd}. 
\section{\textcolor{Chapter }{Groupoids: their elements and attributes}}\logpage{[ 2, 1, 0 ]}
{
 

\subsection{\textcolor{Chapter }{ConnectedGroupoid}}
\logpage{[ 2, 1, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ConnectedGroupoid( obs, grp )\index{ConnectedGroupoid@\texttt{ConnectedGroupoid}}
\label{ConnectedGroupoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GroupAsGroupoid( obj, grp )\index{GroupAsGroupoid@\texttt{GroupAsGroupoid}}
\label{GroupAsGroupoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GroupoidByUnion( comps )\index{GroupoidByUnion@\texttt{GroupoidByUnion}}
\label{GroupoidByUnion}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Groupoid( args )\index{Groupoid@\texttt{Groupoid}}
\label{Groupoid}
}\hfill{\scriptsize (function)}}\\


 There are a variety of constructors for groupoids, with one or two parameters.
The global function \texttt{Groupoid} will normally find the appropriate one to call, the options being: 
\begin{itemize}
\item  a list of objects, the object group; 
\item  a single object, a group being converted to a groupoid; 
\item  a list of groupoids which have already been constructed. 
\end{itemize}
 

 Methods for \texttt{ViewObj}, \texttt{PrintObj} and \texttt{Display} are provided for groupoids and the other types of object in this package.
Users are advised to supply names for all the groups and groupoids they
construct. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> d8 := Group( (1,2,3,4), (1,3) );;
  gap> SetName( d8, "d8" );
  gap> Gd8 := ConnectedGroupoid( [-9,-8,-7], d8 );
  Perm Connected Groupoid:
  < [ -9, -8, -7 ], d8 >
  gap> c6 := Group( (5,6,7)(8,9) );;
  gap> SetName( c6, "c6" );
  gap> Gc6 := GroupAsGroupoid( -6, c6 );
  Perm Connected Groupoid:
  < [ -6 ], c6 >
  gap> Gd8c6 := GroupoidByUnion( [ Gd8, Gc6 ] );;
  gap> Display( Gd8c6 );
  Perm Groupoid with 2 components:
  < objects: [ -9, -8, -7 ]
      group: d8 = <[ (1,2,3,4), (1,3) ]> >
  < objects: [ -6 ]
      group: c6 = <[ (5,6,7)(8,9) ]> >
  gap> SetName( Gd8, "Gd8" );  SetName( Gc6, "Gc6" );  SetName( Gd8c6, "Gd8+Gc6" );
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{ComponentsOfGroupoid}}
\logpage{[ 2, 1, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ComponentsOfGroupoid( gpd )\index{ComponentsOfGroupoid@\texttt{ComponentsOfGroupoid}}
\label{ComponentsOfGroupoid}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ObjectsOfGroupoid( gpd )\index{ObjectsOfGroupoid@\texttt{ObjectsOfGroupoid}}
\label{ObjectsOfGroupoid}
}\hfill{\scriptsize (attribute)}}\\


 When a groupoid consists of two or more components, we require their object
lists to be disjoint. The components are sorted by the first object in their
object lists, which must be disjoint. The list \texttt{ObjectsOfGroupoid} of a groupoid is the sorted concatenation of the objects in the components. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> ComponentsOfGroupoid( Gd8c6 );
  [ Gd8, Gc6 ]
  gap> ObjectsOfGroupoid( Gd8c6 );
  [ -9, -8, -7, -6 ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsPermGroupoid}}
\logpage{[ 2, 1, 3 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsPermGroupoid( gpd )\index{IsPermGroupoid@\texttt{IsPermGroupoid}}
\label{IsPermGroupoid}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsPcGroupoid( gpd )\index{IsPcGroupoid@\texttt{IsPcGroupoid}}
\label{IsPcGroupoid}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFpGroupoid( gpd )\index{IsFpGroupoid@\texttt{IsFpGroupoid}}
\label{IsFpGroupoid}
}\hfill{\scriptsize (property)}}\\


 A groupoid is a permutation groupoid if all its components have permutation
groups. Most of the examples in this chapter are permutation groupoids, but in
principle any type of group known to \textsf{GAP} may be used. 

 In the following example \texttt{Gf2} is an fp-groupoid, while \texttt{Gq8} is a pc-groupoid. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> f2 := FreeGroup( 2 );;
  gap> SetName( f2, "f2" );
  gap> Gf2 := Groupoid( -22, f2 );;
  gap> q8 := SmallGroup( 8, 4 );;
  gap> Gq8 := Groupoid( [ -28, -27 ], q8 );;
  gap> SetName( q8, "q8" );  SetName( Gq8, "Gq8" );
  gap> Gf2q8 := Groupoid( [ Gf2, Gq8 ] );;
  gap> [ IsFpGroupoid( Gf2 ), IsPcGroupoid( Gq8 ), IsPcGroupoid( Gf2q8 ) ];
  [ true, true, false ]
  gap> G4 := Groupoid( [ Gd8c6, Gf2, Gq8 ] );;
  gap> Display( G4 );
  Groupoid with 4 components:
  < objects: [ -28, -27 ]
      group: q8 = <[ f1, f2, f3 ]> >
  < objects: [ -22 ]
      group: f2 = <[ f1, f2 ]> >
  < objects: [ -9, -8, -7 ]
      group: d8 = <[ (1,2,3,4), (1,3) ]> >
  < objects: [ -6 ]
      group: c6 = <[ (5,6,7)(8,9) ]> >
  gap> G4 = Groupoid( [ Gq8, Gf2, Gd8c6 ] );
  true
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{GroupoidElement}}
\logpage{[ 2, 1, 4 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GroupoidElement( gpd, elt, tail, head )\index{GroupoidElement@\texttt{GroupoidElement}}
\label{GroupoidElement}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsElementOfGroupoid( elt )\index{IsElementOfGroupoid@\texttt{IsElementOfGroupoid}}
\label{IsElementOfGroupoid}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GroupElement( elt )\index{GroupElement@\texttt{GroupElement}}
\label{GroupElement}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Tail( elt )\index{Tail@\texttt{Tail}}
\label{Tail}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Head( elt )\index{Head@\texttt{Head}}
\label{Head}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Size( gpd )\index{Size@\texttt{Size}}
\label{Size}
}\hfill{\scriptsize (attribute)}}\\


 A \emph{groupoid element} \texttt{e} is a triple consisting of a group element, \texttt{GroupElement(e)} or \texttt{e![1]}; the tail (source) object, \texttt{Tail(e)} or \texttt{e![2]}; and the head (target) object, \texttt{Head(e)} or \texttt{e![3]}. 

 The \texttt{Size} of a groupoid is the number of its elements which, for a connected groupoid,
is the product of the size of the group with the square of the number of
objects. 

 Groupoid elements have a \emph{partial composition}: two elements may be multiplied when the head of the first coincides with the
tail of the second. Conjugate $a^b$ is defined when $a$ is a loop at the tail of $b$. 

 }

 \index{*,\^{} for groupoid elements} 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> e1 := GroupoidElement( Gd8, (1,2)(3,4), -9, -8 );
  [(1,2)(3,4) : -9 -> -8]
  gap> e2 := GroupoidElement( Gd8, (1,3), -8, -7 );;
  gap> Print( [ GroupElement( e2 ), Tail( e2 ), Head( e2 ) ], "\n" );
  [ (1,3), -8, -7 ]
  gap> prod := e1*e2;
  [(1,2,3,4) : -9 -> -7]
  gap> e3 := GroupoidElement( Gd8, (1,3)(2,4), -7, -9 );;
  gap> cycle := prod*e3;
  [(1,4,3,2) : -9 -> -9]
  gap> cycle^2;
  [(1,3)(2,4) : -9 -> -9]
  gap> Order( cycle );
  4
  gap> cycle^e1;
  [(1,2,3,4) : -8 -> -8]
  gap> [ Size( Gd8 ), Size( Gc6 ), Size( Gd8c6 ), Size( Gf2q8 ) ];
  [ 72, 6, 78, infinity ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsConnectedGroupoid}}
\logpage{[ 2, 1, 5 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsConnectedGroupoid( gpd )\index{IsConnectedGroupoid@\texttt{IsConnectedGroupoid}}
\label{IsConnectedGroupoid}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsDiscreteGroupoid( gpd )\index{IsDiscreteGroupoid@\texttt{IsDiscreteGroupoid}}
\label{IsDiscreteGroupoid}
}\hfill{\scriptsize (property)}}\\


 The forgetful functor, which forgets the composition of elements, maps the
category of groupoids and their morphisms to the category of digraphs and
their morphisms. Applying this functor to a particular groupoid gives the \emph{underlying digraph} of the groupoid. A groupoid is \emph{connected} if its underlying digraph is connected (and so complete). A groupoid is \emph{discrete} if it is a union of groups, so that all the arcs in its underlying digraph are
loops. It is sometimes convenient to call a groupoid element a \emph{loop} when its tail and head are the same object. 

 }

 }

 
\section{\textcolor{Chapter }{Subgroupoids}}\logpage{[ 2, 2, 0 ]}
{
 

\subsection{\textcolor{Chapter }{SubgroupoidByComponents}}
\logpage{[ 2, 2, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SubgroupoidByComponents( gpd, obhoms )\index{SubgroupoidByComponents@\texttt{SubgroupoidByComponents}}
\label{SubgroupoidByComponents}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Subgroupoid( args )\index{Subgroupoid@\texttt{Subgroupoid}}
\label{Subgroupoid}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FullSubgroupoid( gpd, obs )\index{FullSubgroupoid@\texttt{FullSubgroupoid}}
\label{FullSubgroupoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MaximalDiscreteSubgroupoid( gpd )\index{MaximalDiscreteSubgroupoid@\texttt{MaximalDiscreteSubgroupoid}}
\label{MaximalDiscreteSubgroupoid}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DiscreteSubgroupoid( gpd, obs, sgps )\index{DiscreteSubgroupoid@\texttt{DiscreteSubgroupoid}}
\label{DiscreteSubgroupoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FullIdentitySubgroupoid( gpd )\index{FullIdentitySubgroupoid@\texttt{FullIdentitySubgroupoid}}
\label{FullIdentitySubgroupoid}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DiscreteIdentitySubgroupoid( gpd )\index{DiscreteIdentitySubgroupoid@\texttt{DiscreteIdentitySubgroupoid}}
\label{DiscreteIdentitySubgroupoid}
}\hfill{\scriptsize (attribute)}}\\


 A \emph{subgroupoid} \texttt{sgpd} of \texttt{gpd} has as objects a subset of the objects of \texttt{gpd}. It is \emph{wide} if all the objects are included. It is \emph{full} if, for any two objects in \texttt{sgpd}, the \texttt{Homset} is the same as in \texttt{gpd}. The elements of \texttt{sgpd} are a subset of those of \texttt{gpd}, closed under multiplication and with tail and head in the chosen object set. 

 There are a variety of constructors for a subgroupoid of a groupoid. The
operation \texttt{SubgroupoidByComponents} is the most general. Its two parameters are a groupoid and a list of connected
components, where each component is specified as a list \texttt{[obs,sgp]}, \texttt{obs} is a subset of the objects in one of the components of \texttt{gpd}, and \texttt{sgp} is a subgroup of the group in that component. 

 The \texttt{FullSubgroupoid} of a groupoid \texttt{gpd} on a subset \texttt{obs} of its objects contains all the elements of \texttt{gpd} with tail and head in \texttt{obs}. 

 A subgroupoid is \emph{discrete} if it is a union of groups. The \texttt{MaximalDiscreteSubgroupoid} of \texttt{gpd} is the union of all the single-object full subgroupoids of \texttt{gpd}. 

 An \emph{identity subgroupoid} has trivial object groups, but need not be discrete. A connected identity
groupoid is sometimes called a \emph{tree groupoid}. 

 The global function \texttt{Subgroupoid} should call the appropriate operation. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> c4d := Subgroup( d8, [ (1,2,3,4) ] );;
  gap> k4d := Subgroup( d8, [ (1,2)(3,4), (1,3)(2,4) ] );;
  gap> SetName( c4d, "c4d" );  SetName( k4d, "k4d" );
  gap> Ud8 := Subgroupoid( Gd8, [ [[-9, k4d]], [[-8,-7], c4d] ] );;
  gap> SetName( Ud8, "Ud8" );
  gap> Display( Ud8 );
  Perm Groupoid with 2 components:
  < objects: [ -9 ]
      group: k4d = <[ (1,2)(3,4), (1,3)(2,4) ]> >
  < objects: [ -8, -7 ]
      group: c4d = <[ (1,2,3,4) ]> >
  gap> FullSubgroupoid( Gd8c6, [-7,-6] );
  Perm Groupoid with components:
  < [ -7 ], d8 >
  < [ -6 ], c6 >
  gap> DiscreteSubgroupoid( Gd8c6, [-9,-8], [ c4d, k4d ] );
  Perm Groupoid with components:
  < [ -9 ], c4d >
  < [ -8 ], k4d >
  gap> FullIdentitySubgroupoid( Ud8 );
  Perm Groupoid with components:
  < [ -9 ], id(k4d) >
  < [ -8, -7 ], id(c4d) >
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Stars, Costars and Homsets}}\logpage{[ 2, 3, 0 ]}
{
 

\subsection{\textcolor{Chapter }{ObjectStar}}
\logpage{[ 2, 3, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ObjectStar( gpd, obj )\index{ObjectStar@\texttt{ObjectStar}}
\label{ObjectStar}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ObjectCostar( gpd, obj )\index{ObjectCostar@\texttt{ObjectCostar}}
\label{ObjectCostar}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Homset( gpd, tail, head )\index{Homset@\texttt{Homset}}
\label{Homset}
}\hfill{\scriptsize (operation)}}\\


 The \emph{star} at \texttt{obj} is the set of groupoid elements which have \texttt{obj} as tail, while the \emph{costar} is the set of elements which have \texttt{obj} as head. The \emph{homset} from \texttt{obj1} to \texttt{obj2} is the set of elements with the specified tail and head, and so is bijective
with the elements of the group. Thus every star and every costar is a union of
homsets. 

 In order not to create unneccessary long lists, these operations return
objects of type \texttt{IsHomsetCosetsRep} for which an \texttt{Iterator} is provided. (An \texttt{Enumerator} is not yet implemented.) 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> star9 := ObjectStar( Gd8, -9 );
  <star at [ -9 ] with group d8>
  gap> for e in star9 do
  >      if ( Order( e![1] ) = 2 ) then Print( e, "\n" ); fi;
  >    od;
  [(1,4,3,2) : -9 -> -9]
  [(1,4,3,2) : -9 -> -8]
  [(1,4,3,2) : -9 -> -7]
  [(1,2,3,4) : -9 -> -9]
  [(1,2,3,4) : -9 -> -8]
  [(1,2,3,4) : -9 -> -7]
  gap> costar6 := ObjectCostar( Gc6, -6 );
  <costar at [ -6 ] with group c6>
  gap> hset78 := Homset( Ud8, -7, -8 );
  <homset -7 -> -8 with group c4d>
  gap> for e in hset78 do  Print( e, "\n" );  od;
  [() : -7 -> -8]
  [(1,3)(2,4) : -7 -> -8]
  [(1,4,3,2) : -7 -> -8]
  [(1,2,3,4) : -7 -> -8]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IdentityElement}}
\logpage{[ 2, 3, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IdentityElement( gpd, obj )\index{IdentityElement@\texttt{IdentityElement}}
\label{IdentityElement}
}\hfill{\scriptsize (operation)}}\\


 The identity groupoid element \texttt{1\_{o}} of \texttt{gpd} at object \texttt{o} is \texttt{[e,o,o]} where \texttt{e} is the identity group element in the object group. It is a left identity for
the star and a right identity for the costar at that object. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> i7 := IdentityElement( Gd8, -7 );;
  gap> i8 := IdentityElement( Gd8, -8 );;
  gap> L := [ i7, i8 ];;
  gap> for e in hset78 do  Add( L, i7*e*i8 = e );  od;
  gap> L;
  [ [() : -7 -> -7], [() : -8 -> -8], true, true, true, true ]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Left, right and double cosets}}\logpage{[ 2, 4, 0 ]}
{
 

\subsection{\textcolor{Chapter }{RightCoset}}
\logpage{[ 2, 4, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RightCoset( G, U, elt )\index{RightCoset@\texttt{RightCoset}}
\label{RightCoset}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RightCosetRepresentatives( G, U )\index{RightCosetRepresentatives@\texttt{RightCosetRepresentatives}}
\label{RightCosetRepresentatives}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RightCosetsNC( G, U )\index{RightCosetsNC@\texttt{RightCosetsNC}}
\label{RightCosetsNC}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LeftCoset( G, U, elt )\index{LeftCoset@\texttt{LeftCoset}}
\label{LeftCoset}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LeftCosetRepresentatives( G, U )\index{LeftCosetRepresentatives@\texttt{LeftCosetRepresentatives}}
\label{LeftCosetRepresentatives}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LeftCosetRepresentativesFromObject( G, U, obj )\index{LeftCosetRepresentativesFromObject@\texttt{LeftCosetRepresentativesFromObject}}
\label{LeftCosetRepresentativesFromObject}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LeftCosetsNC( G, U )\index{LeftCosetsNC@\texttt{LeftCosetsNC}}
\label{LeftCosetsNC}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DoubleCoset( G, U, elt, V )\index{DoubleCoset@\texttt{DoubleCoset}}
\label{DoubleCoset}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DoubleCosetRepresentatives( G, U, V )\index{DoubleCosetRepresentatives@\texttt{DoubleCosetRepresentatives}}
\label{DoubleCosetRepresentatives}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DoubleCosetsNC( G, U, V )\index{DoubleCosetsNC@\texttt{DoubleCosetsNC}}
\label{DoubleCosetsNC}
}\hfill{\scriptsize (operation)}}\\


 If \texttt{U} is a wide subgroupoid of $G$, the \emph{right cosets} of $U$ in $G$ are the equivalence classes of the relation on the elements of $G$ where $g1$ is related to $g2$ if and only if $g2 = u*g1$ for some element $u$ of $U$. The right coset containing $g$ is written $Ug$. These right cosets refine the costars of $G$ and, in particular, $U1\_{o}$ is the costar of $U$ at $o$, so that (unlike groups) $U$ is itself a coset only when $G$ has a single object. 

 The \emph{right coset representatives} for $U$ in $G$ form a list containing one groupoid element for each coset where, in a
particular component of $U$, the group element chosen is the right coset representative of the group of $U$ in the group of $G$. 

 Similarly, the \emph{left cosets} $gU$ refine the stars of $G$, while \emph{double cosets} are unions of left cosets and of right cosets. The operation \texttt{LeftCosetRepresentativesFromObject( G, U, obj )} is used in Chapter 4, and returns only those representatives which have tail
at \texttt{obj}. 

 As with stars and homsets, these cosets are implemented with representation \texttt{IsHomsetCosetsRep} and provided with an iterator. Note that, when $U$ has more than one component, cosets may have differing lengths. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> re2 := RightCoset( Gd8, Ud8, e2 );
  RightCoset(c4d,[(1,3) : -8 -> -7])
  gap> for x in re2 do Print( x, "\n" ); od;
  [(1,3) : -8 -> -8]
  [(1,3) : -7 -> -8]
  [(2,4) : -8 -> -8]
  [(2,4) : -7 -> -8]
  [(1,4)(2,3) : -8 -> -8]
  [(1,4)(2,3) : -7 -> -8]
  [(1,2)(3,4) : -8 -> -8]
  [(1,2)(3,4) : -7 -> -8]
  gap> rcrd8 := RightCosetRepresentatives( Gd8, Ud8 );
  [ [() : -9 -> -9], [() : -9 -> -8], [() : -9 -> -7], [(2,4) : -9 -> -9],
    [(2,4) : -9 -> -8], [(2,4) : -9 -> -7], [() : -8 -> -9], [() : -8 -> -8],
    [() : -8 -> -7], [(2,4) : -8 -> -9], [(2,4) : -8 -> -8], [(2,4) : -8 -> -7]
   ]
  gap> lcr7 := LeftCosetRepresentativesFromObject( Gd8, Ud8, -7 );
  [ [() : -7 -> -9], [(2,4) : -7 -> -9], [() : -7 -> -8], [(2,4) : -7 -> -8] ]
  
\end{Verbatim}
 }

 More examples of these operations may be found in the example file \texttt{gpd/examples/gpd.g}. }

           
\chapter{\textcolor{Chapter }{Morphisms of Groupoids}}\label{chap-gpdmor}
\logpage{[ 3, 0, 0 ]}
{
  A \emph{morphism} $m$ from a groupoid $G$ to a groupoid $H$ consists of a map from the objects of $G$ to those of $H$ together with a map from the elements of $G$ to those of $H$ which is compatible with tail and head and which preserves multiplication: 
\[ m(g1 : o1 \to o2)*m(g2 : o2 \to o3) ~=~ m(g1*g2 : o1 \to o3). \]
 

 Note that when a morphism is not injective on objects, the image of the source
need not be a subgroupoid of the range. The simplest example of this is given
by mapping the two-object groupoid with trivial group to the free group $\langle a \rangle$ on one generator, when the image is $[1,a,a^{-1}]$. 
\section{\textcolor{Chapter }{Morphisms to a connected groupoid}}\logpage{[ 3, 1, 0 ]}
{
 

\subsection{\textcolor{Chapter }{MorphismOfConnectedGroupoids}}
\logpage{[ 3, 1, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MorphismOfConnectedGroupoids( G, H, imobs, hom )\index{MorphismOfConnectedGroupoids@\texttt{MorphismOfConnectedGroupoids}}
\label{MorphismOfConnectedGroupoids}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Source( mor )\index{Source@\texttt{Source}}
\label{Source}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Range( mor )\index{Range@\texttt{Range}}
\label{Range}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ComponentImages( mor )\index{ComponentImages@\texttt{ComponentImages}}
\label{ComponentImages}
}\hfill{\scriptsize (attribute)}}\\


 As usual, there are a variety of morphism constructors. The basic construction
is a morphism $G \to H$ with $H$ connected, which is implemented as \texttt{IsMorphismToConnectedGroupoidRep} with attributes \texttt{Source}, \texttt{Range} and \texttt{ComponentImages}. If $G$ is also connected, we may apply \texttt{MorphismOfConnectedGroupoids}, requiring: 
\begin{itemize}
\item  a list \texttt{imobs} of the images of the objects of $G$; 
\item  a homomorphism \texttt{hom} from the group of $G$ to the group of $H$. 
\end{itemize}
 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> d12 := Group( (15,16,17,18,19,20, (15,20)(16,19)(17,18) );;
  gap> Gd12 := ConnectedGroupoid( [-37,-36,-35,-34], d12 );;
  gap> SetName( d12, "d12" );  SetName( Gd12, "Gd12" );
  gap> s3d := Subgroup( d12, [ (15,17,19)(16,18,20), (15,20)(16,19)(17,18) ] );
  gap> Gs3d := SubgroupoidByComponents( Gd12, [ [[-36,-35,-34], s3d] ] );;
  gap> SetName( s3d, "s3d" );  SetName( Gs3d, "Gs3d" );
  gap> gend8 := GeneratorsOfGroup( d8 );;
  gap> imhd8 := [ ( ), (15,20)(16,19)(17,18) ];;
  gap> hd8 := GroupHomomorphismByImages( d8, s3d, gend8, imhd8 );
  gap> md8 := MorphismOfConnectedGroupoids( Gd8, Gs3d, [-34,-35,-36], hd8 );
  Groupoid morphism : Gd8 -> Gs3d 
  gap> IsBijectiveOnObjects( md8 );
  true
  gap> Display( md8 );
  Morphism to connected groupoid:
  [ Gd8 ] -> [ Gs3d ]
    object map = [ [ -9, -8, -7 ], [ -34, -35, -36 ] ]
  homomorphism = [ [ (1,2,3,4), (1,3) ], [ (), (15,20)(16,19)(17,18) ] ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{MorphismToConnectedGroupoid}}
\logpage{[ 3, 1, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{MorphismToConnectedGroupoid( G, H, obhoms )\index{MorphismToConnectedGroupoid@\texttt{MorphismToConnectedGroupoid}}
\label{MorphismToConnectedGroupoid}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GroupoidMorphismWithCommonRange( G, H, mors )\index{GroupoidMorphismWithCommonRange@\texttt{GroupoidMorphismWithCommonRange}}
\label{GroupoidMorphismWithCommonRange}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GroupoidMorphism( args )\index{GroupoidMorphism@\texttt{GroupoidMorphism}}
\label{GroupoidMorphism}
}\hfill{\scriptsize (function)}}\\


 When $G$ is not connected the appropriate operation is \texttt{MorphismToConnectedGroupoid( G, H, obhoms )}, where the third parameter is a list \texttt{ComponentImages( mor )} of \texttt{[imobs,hom]} pairs. 

 The operation \texttt{GroupoidMorphismWithCommonRange} combines into a single morphism two or more morphisms, in the list \texttt{mors}, with range $H$ and source a subgroupoid of $G$. 

 The global function \texttt{GroupoidMorphism} will normally find the appropriate operation to call. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> hc6 := GroupHomomorphismByImages( c6, s3d, [(5,6,7)(8,9)], [(15,19)(16,18)] );;
  gap> mc6 := GroupoidMorphism( Gc6, Gs3d, [ -36 ], hc6 );;
  gap> md8c6 := MorphismToConnectedGroupoid( Gd8c6, Gs3d, 
                [ [[-34,-35,-36], hd8], [[-36], hc6] ] );
  Groupoid morphism : Gd8+Gc6 -> Gs3d
  gap> Display( md8c6 );
  Morphism to connected groupoid with components:
  [ Gd8 ] -> [ Gs3d ]
    object map = [ [ -9, -8, -7 ], [ -34, -35, -36 ] ]
  homomorphism = [ [ (1,2,3,4), (1,3) ], [ (), (15,20)(16,19)(17,18) ] ]
  [ Gc6 ] -> [ Gs3d ]
    object map = [ [ -6 ], [ -36 ] ]
  homomorphism = [ [ (5,6,7)(8,9) ], [ (15,19)(16,18) ] ]
  gap> 
  gap> gens3d := GeneratorsOfGroup( s3d );;
  gap> imas3d := [ (15,17,19)(16,18,20), (15,16)(17,20)(18,19) ];;
  gap> as3d := GroupHomomorphismByImages( s3d, s3d, gens3d, imas3d );;
  gap> aGs3d := MorphismOfConnectedGroupoids( Gs3d, Gs3d, [-35,-34,-36], as3d );;
  gap> IsGroupoidAutomorphism( aGs3d );
  true
  gap> Order( aGs3d );
  3
  gap> Gs3dd8 := GroupoidByUnion( [ Gd8, Gs3d ] );;
  gap> SetName( Gs3dd8, "Gs3d+Gd8" );;
  gap> common := GroupoidMorphismWithCommonRange( Gs3dd8, Gs3d, [ aGs3d, md8 ] );;
  gap> Display( common );
  Morphism to connected groupoid with components:
  [ Gs3d ] -> [ Gs3d ]
    object map = [ [ -36, -35, -34 ], [ -35, -34, -36 ] ]
  homomorphism = [ [ (15,17,19)(16,18,20), (15,20)(16,19)(17,18) ],
    [ (15,17,19)(16,18,20), (15,16)(17,20)(18,19) ] ]
  [ Gd8 ] -> [ Gs3d ]
    object map = [ [ -9, -8, -7 ], [ -34, -35, -36 ] ]
  homomorphism = [ [ (1,2,3,4), (1,3) ], [ (), (15,20)(16,19)(17,18) ] ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsomorphismNewObjects}}
\logpage{[ 3, 1, 3 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismNewObjects( gpd, obs )\index{IsomorphismNewObjects@\texttt{IsomorphismNewObjects}}
\label{IsomorphismNewObjects}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IdentityMapping( gpd )\index{IdentityMapping@\texttt{IdentityMapping}}
\label{IdentityMapping}
}\hfill{\scriptsize (attribute)}}\\


 The function \texttt{IsomorphismNewObjects} provides an isomorphism to an isomorphic groupoid with a new set of objects.
The function \texttt{IdentityMapping}, already provided for groups, is also implemented for groupoids. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> idGd8 := IdentityMapping( Gd8 );
  Groupoid morphism: [ Gd8 ] -> [ Gd8 ]
  gap> copys3d := IsomorphismNewObjects( Gs3d, [-24,-25,-26] );;
  gap> Hs3d := Range( copys3d );;
  gap> SetName( Hs3, "Hs3" );
  gap> Display( copys3d );
  Morphism to connected groupoid:
  [ Gs3d ] -> [ Hs3d ]
    object map = [ [ -36, -35, -34 ], [ -32, -31, -30 ] ]
  homomorphism = [ [ (15,17,19)(16,18,20), (15,20)(16,19)(17,18) ],
    [ (15,17,19)(16,18,20), (15,20)(16,19)(17,18) ] ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{InclusionMappingGroupoids}}
\logpage{[ 3, 1, 4 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{InclusionMappingGroupoids( G, U )\index{InclusionMappingGroupoids@\texttt{InclusionMappingGroupoids}}
\label{InclusionMappingGroupoids}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RestrictionMappingGroupoids( hom, src, rng )\index{RestrictionMappingGroupoids@\texttt{RestrictionMappingGroupoids}}
\label{RestrictionMappingGroupoids}
}\hfill{\scriptsize (operation)}}\\


 We have added functions \texttt{InclusionMappingGroupoids} and \texttt{RestrictionMappingGroupoids}, corresponding to \texttt{InclusionMappingGroups} and \texttt{RestrictionMappingGroups} for groups. At present \texttt{RestrictionMappingGroups} is only implemented for the case where the source and range of the morphism
are connected. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> SetName( ComponentsOfGroupoid(Ud8)[1], "Ud8a" );
  gap> SetName( ComponentsOfGroupoid(Ud8)[2], "Ud8b" );
  gap> inc := InclusionMappingGroupoids( Gd8, Ud8 );;
  gap> Display( inc );
  Morphism to connected groupoid with components:
  [ Ud8a ] -> [ Gd8 ]
    object map = [ [ -9 ], [ -9 ] ]
  homomorphism = [ [ (1,2)(3,4), (1,3)(2,4) ], [ (1,2)(3,4), (1,3)(2,4) ] ]
  [ Ud8b ] -> [ Gd8 ]
    object map = [ [ -8, -7 ], [ -8, -7 ] ]
  homomorphism = [ [ (1,2,3,4) ], [ (1,2,3,4) ] ]
  gap> res := RestrictionMappingGroupoids( md8, Ud8, Gs3d );
  gap> Display( res );
  Morphism to connected groupoid with components:
  [ Ud8a ] -> [ Gs3d ]
    object map = [ [ -9 ], [ -34 ] ]
  homomorphism = [ [ (1,2)(3,4), (1,3)(2,4) ], [ (15,20)(16,19)(17,18), () ] ]
  [ Ud8b ] -> [ Gs3d ]
    object map = [ [ -8, -7 ], [ -35, -36 ] ]
  homomorphism = [ [ (1,2,3,4) ], [ () ] ]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{General Morphisms and composites}}\logpage{[ 3, 2, 0 ]}
{
 

\subsection{\textcolor{Chapter }{GroupoidMorphismByComponents}}
\logpage{[ 3, 2, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GroupoidMorphismByComponents( G, H, mors )\index{GroupoidMorphismByComponents@\texttt{GroupoidMorphismByComponents}}
\label{GroupoidMorphismByComponents}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GroupoidMorphismByUnion( mors )\index{GroupoidMorphismByUnion@\texttt{GroupoidMorphismByUnion}}
\label{GroupoidMorphismByUnion}
}\hfill{\scriptsize (function)}}\\


 When $H$ is not connected, a groupoid morphism from $G$ to $H$ is a union of a list \texttt{mors} of morphisms of connected groupoids. 

 There are two ways of combining \texttt{m1 : G1->H1} and \texttt{m2 : G2->H2} into a single morphism. The operation \texttt{GroupoidMorphismByUnion( [m1,m2] );} constucts the groupoid unions \texttt{G12,H12} of \texttt{G1} with \texttt{G2} and \texttt{H1} with \texttt{H2}, and then a morphism \texttt{m12 : G12->H12}. If \texttt{G12,H12} have already been constructed, the operation \texttt{GroupoidMorphismByComponents( G12, H12, [m1,m2] );} may be more appropriate. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> imad8 := [ (1,2,3,4), (2,4) ];;
  gap> ad8 := GroupHomomorphismByImages( d8, d8, [(1,2,3,4),(1,3)], imad8 );;
  gap> aGd8 := MorphismOfConnectedGroupoids( Gd8, Gd8, [-8,-7,-9], ad8 );;
  gap> mor1 := GroupoidMorphismByUnion( [ aGd8, mc6 ] );;
  gap> mor2 := GroupoidMorphismByComponents( Gd8c6, Gs3dd8, [ aGd8, mc6 ] );;
  gap> Display( mor2 );
  Groupoid Morphism: Gd8+Gc6 -> Gs3d+Gd8 with components :
  [ Gc6 ] -> [ Gs3d ]
    object map = [ [ -6 ], [ -36 ] ]
  homomorphism = [ [ (5,6,7)(8,9) ], [ (15,19)(16,18) ] ]
  [ Gd8 ] -> [ Gd8 ]
    object map = [ [ -9, -8, -7 ], [ -8, -7, -9 ] ]
  homomorphism = [ [ (1,2,3,4), (1,3) ], [ (1,2,3,4), (2,4) ] ]
  gap> mor1 = mor2;
  true
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsGroupoidMorphism}}
\logpage{[ 3, 2, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsGroupoidMorphism( mor )\index{IsGroupoidMorphism@\texttt{IsGroupoidMorphism}}
\label{IsGroupoidMorphism}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsInjectiveOnObjects( mor )\index{IsInjectiveOnObjects@\texttt{IsInjectiveOnObjects}}
\label{IsInjectiveOnObjects}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsSurjectiveOnObjects( mor )\index{IsSurjectiveOnObjects@\texttt{IsSurjectiveOnObjects}}
\label{IsSurjectiveOnObjects}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsBijectiveOnObjects( mor )\index{IsBijectiveOnObjects@\texttt{IsBijectiveOnObjects}}
\label{IsBijectiveOnObjects}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsGroupoidAutomorphism( mor )\index{IsGroupoidAutomorphism@\texttt{IsGroupoidAutomorphism}}
\label{IsGroupoidAutomorphism}
}\hfill{\scriptsize (property)}}\\


 Here are some of the basic properties of groupoid morphisms. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> IsGroupoidMorphism( res );
  true
  gap> IsInjectiveOnObjects( res );
  true
  gap> IsInjective( res );
  false
  gap> IsSurjectiveOnObjects( inc );
  true
  gap> IsSurjective( inc );
  false
  gap> IsGroupoidAutomorphism( aGd8 );
  true
  gap> eGd8 := MorphismOfConnectedGroupoids( Gd8, Gd8, [-7,-7,-9], ad8 );;
  gap> IsGroupoidEndomorphism( eGd8 );
  true
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{ImagesOfObjects}}
\logpage{[ 3, 2, 3 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ImagesOfObjects( mor )\index{ImagesOfObjects@\texttt{ImagesOfObjects}}
\label{ImagesOfObjects}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ImagesSource( mor )\index{ImagesSource@\texttt{ImagesSource}}
\label{ImagesSource}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ImageElm( mor, elt )\index{ImageElm@\texttt{ImageElm}}
\label{ImageElm}
}\hfill{\scriptsize (operation)}}\\


 Here are some of examples of operations that return images. These are not yet
fully implemented: for example, \texttt{ImageElm} and \texttt{ImagesSource} require the range of \texttt{mor} to be connected. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> ImagesOfObjects( md8 );
  [ [ -34, -35, -36, -36 ] ]
  gap> ImagesSource(md8);
  Perm Connected Groupoid:
  < [ -36, -35, -34 ], Group( [ (), (15,20)(16,19)(17,18) ] ) >
  gap> e1;
  [(1,2)(3,4) : -9 -> -8]
  gap> ImageElm( md8c6, e1 );
  [(15,20)(16,19)(17,18) : -34 -> -35]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{Product}}
\logpage{[ 3, 2, 4 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Product( mors )\index{Product@\texttt{Product}}
\label{Product}
}\hfill{\scriptsize (operation)}}\\


 \index{*,\^{} for groupoid morphisms} Morphisms $m_1, m_2$ can be composed if the image of $m_1$ is contained in the domain of $m_2$. Currently composition is only defined for morphisms of connected groupoids. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Hk4d := SubgroupoidByComponents( Gd8, [ [[-9,-8,-7], k4d] ] );;
  gap> genq8 := GeneratorsOfGroup(q8);;
  gap> hq8 := GroupHomomorphismByImages( q8,k4d,genq8,[(1,2)(3,4),(1,3)(2,4),()]);;
  gap> mq8 := GroupoidMorphism( Gq8, Hk4d, [-7,-9], hq8 );;
  gap> iHk4d := InclusionMappingGroupoids( Gd8, Hk4d );;
  gap> mor3 := mq8*iHk4d;;
  gap> Display( mor3 );
  Morphism to connected groupoid:
  [ Gq8 ] -> [ Gd8 ]
    object map = [ [ -28, -27 ], [ -7, -9 ] ]
  homomorphism = [ Pcgs([ f1, f2, f3 ]), [ (1,2)(3,4), (1,3)(2,4), () ] ]
  gap> mor4 := mor1*aGd8;;
  gap> Display( mor4 );
  Morphism to connected groupoid:
  [ Gq8 ] -> [ Gd8 ]
    object map = [ [ -28, -27 ], [ -9, -8 ] ]
  homomorphism = [ Pcgs([ f1, f2, f3 ]), [ (1,4)(2,3), (1,3)(2,4), () ] ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{InverseMorphism}}
\logpage{[ 3, 2, 5 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{InverseMorphism( mor )\index{InverseMorphism@\texttt{InverseMorphism}}
\label{InverseMorphism}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{Order( mor )\index{Order@\texttt{Order}}
\label{Order}
}\hfill{\scriptsize (attribute)}}\\


 The \emph{inverse} of a morphism $m$ is defined when $m$ is bijective on objects and on elements. The operation \texttt{InverseMorphism} is a synonym for \texttt{InverseGeneralMapping}. The \emph{order} of an automorphism is the smallest power which returns the identity morphism
of $G$. 

 }

 

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> genq8 := GeneratorsOfGroup( q8 );;
  gap> imq8 := [ q8.2, q8.1*q8.2, q8.3 ];
  [ f2, f1*f2, f3 ]
  gap> autq8 := GroupHomomorphismByImages( q8, q8, genq8, imq8 );;
  gap> autGq8 := GroupoidMorphism( Gq8, Gq8, [-27,-28], autq8 );;
  gap> Display( InverseMorphism( autGq8 ) );
  Morphism to connected groupoid:
  [ Gq8 ] -> [ Gq8 ]
    object map = [ [ -28, -27 ], [ -27, -28 ] ]
  homomorphism = [ [ f2, f1*f2, f3 ], [ f1, f2, f3 ] ]
  gap> Order( autGq8 );
  6
  
\end{Verbatim}
 }

   }

           
\chapter{\textcolor{Chapter }{Graphs of Groups and Groupoids}}\label{chap-ggraph}
\logpage{[ 4, 0, 0 ]}
{
  This package was originally designed to implement \emph{graphs of groups}, a notion introduced by Serre in \cite{Serre}. It was only when this was extended to \emph{graphs of groupoids} that the functions for groupoids, described in the previous chapters, were
required. The methods described here are based on Philip Higgins' paper \cite{HiJLMS}. For further details see Chapter 2 of \cite{emma-thesis}. Since a graph of groups involves a directed graph, with a group associated
to each vertex and arc, we first define digraphs with edges weighted by the
generators of a free group. 
\section{\textcolor{Chapter }{Digraphs}}\logpage{[ 4, 1, 0 ]}
{
 

\subsection{\textcolor{Chapter }{FpWeightedDigraph}}
\logpage{[ 4, 1, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FpWeightedDigraph( verts, arcs )\index{FpWeightedDigraph@\texttt{FpWeightedDigraph}}
\label{FpWeightedDigraph}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFpWeightedDigraph( dig )\index{IsFpWeightedDigraph@\texttt{IsFpWeightedDigraph}}
\label{IsFpWeightedDigraph}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{InvolutoryArcs( dig )\index{InvolutoryArcs@\texttt{InvolutoryArcs}}
\label{InvolutoryArcs}
}\hfill{\scriptsize (attribute)}}\\


 A \emph{weighted digraph} is a record with two components: \emph{vertices}, which are usually taken to be positive integers (to distinguish them from
the objects in a groupoid); and \emph{arcs}, which take the form of 3-element lists \texttt{[weight,tail,head]}. The \emph{tail} and \emph{head} are the two vertices of the arc. The \emph{weight} is taken to be an element of a finitely presented group, so as to produce
digraphs of type \texttt{IsFpWeightedDigraph}. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> V1 := [ 5, 6 ];;
  gap> f1 := FreeGroup( "y" );;
  gap> y := f1.1;;
  gap> A1 := [ [ y, 5, 6 ], [ y^-1, 6, 5 ] ];
  gap> D1 := FpWeightedDigraph( V1, A1 );
  weighted digraph with vertices: [ 5, 6 ]
  and arcs: [ [ y, 5, 6 ], [ y^-1, 6, 5 ] ]
  gap> inv1 := InvolutoryArcs( D1 );
  [ 2, 1 ]
  
\end{Verbatim}
 The example illustrates the fact that we require arcs to be defined in
involutory pairs, as though they were inverse elements in a groupoid. We may
in future decide just to give \texttt{[y,5,6]} as the data and get the function to construct the reverse edge. The attribute \texttt{InvolutoryArcs} returns a list of the positions of each inverse arc in the list of arcs. In
the second example the graph is a complete digraph on three vertices. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> f3 := FreeGroup( 3, "z" );;
  gap> z1 := f3.1;;  z2 := f3.2;;  z3 := f3.3;;
  gap> V3 := [ 7, 8, 9 ];;
  gap> A3 := [[z1,7,8],[z2,8,9],[z3,9,7],[z1^-1,8,7],[z2^-1,9,8],[z3^-1,7,9]];;
  gap> D3 := FpWeightedDigraph( V3, A3 );
  weighted digraph with vertices: [ 7, 8, 9 ]
  and arcs: [ [ z1, 7, 8 ], [ z2, 8, 9 ], [ z3, 9, 7 ], [ z1^-1, 8, 7 ],
    [ z2^-1, 9, 8 ], [ z3^-1, 7, 9 ] ]
  [gap> inv3 := InvolutoryArcs( D3 );
  [ 4, 5, 6, 1, 2, 3 ]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Graphs of Groups}}\logpage{[ 4, 2, 0 ]}
{
 

\subsection{\textcolor{Chapter }{GraphOfGroups}}
\logpage{[ 4, 2, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GraphOfGroups( dig, gps, sgps, isos )\index{GraphOfGroups@\texttt{GraphOfGroups}}
\label{GraphOfGroups}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DigraphOfGraphOfGroups( gg )\index{DigraphOfGraphOfGroups@\texttt{DigraphOfGraphOfGroups}}
\label{DigraphOfGraphOfGroups}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GroupsOfGraphOfGroups( gg )\index{GroupsOfGraphOfGroups@\texttt{GroupsOfGraphOfGroups}}
\label{GroupsOfGraphOfGroups}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SubgroupsOfGraphOfGroups( gg )\index{SubgroupsOfGraphOfGroups@\texttt{SubgroupsOfGraphOfGroups}}
\label{SubgroupsOfGraphOfGroups}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismsOfGraphOfGroups( gg )\index{IsomorphismsOfGraphOfGroups@\texttt{IsomorphismsOfGraphOfGroups}}
\label{IsomorphismsOfGraphOfGroups}
}\hfill{\scriptsize (attribute)}}\\


 A graph of groups is traditionally defined as consisting of: 
\begin{itemize}
\item  a digraph with involutory pairs of arcs; 
\item  a \emph{vertex group} associated to each vertex; 
\item  a group associated to each pair of arcs; 
\item  an injective homomorphism from each arc group to the group at the head of the
arc. 
\end{itemize}
 We have found it more convenient to associate to each arc: 
\begin{itemize}
\item  a subgroup of the vertex group at the tail; 
\item  a subgroup of the vertex group at the head; 
\item  an isomorphism between these subgroups, such that each involutory pair of arcs
determines inverse isomorphisms. 
\end{itemize}
 These two viewpoints are clearly equivalent. 

 In this implementation we require that all subgroups are of finite index in
the vertex groups. 

 The four attributes provide a means of calling the four items of data in the
construction of a graph of groups. 

 We shall be representing free products with amalgamation of groups and HNN
extensions of groups, so we take as our first example the trefoil group with
generators $a,b$ and relation $a^3=b^2$. For this we take digraph \texttt{D1} above with an infinite cyclic group at each vertex, generated by $a$ and $b$ respectively. The two subgroups will be generated by $a^3$ and $b^2$ with the obvious isomorphisms. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> ## free vertex group at 5
  gap> fa := FreeGroup( "a" );;
  gap> a := fa.1;;
  gap> SetName( fa, "fa" );
  gap> hy := Subgroup( fa, [a^3] );;
  gap> SetName( hy, "hy" );
  gap> ## free vertex group at 6
  gap> fb := FreeGroup( "b" );;
  gap> b := fb.1;;
  gap> SetName( fb, "fb" );
  gap> hybar := Subgroup( fb, [b^2] );;
  gap> SetName( hybar, "hybar" );
  gap> ## isomorphisms between subgroups
  gap> homy := GroupHomomorphismByImagesNC( hy, hybar, [a^3], [b^2] );;
  gap> homybar := GroupHomomorphismByImagesNC( hybar, hy, [b^2], [a^3] );;
  gap> ## defining graph of groups G1
  gap> G1 := GraphOfGroups( D1, [fa,fb], [hy,hybar], [homy,homybar] );
  Graph of Groups: 2 vertices; 2 arcs; groups [ fa, fb ]
  gap> Display( G1 );
  Graph of Groups with :-
      vertices: [ 5, 6 ]
          arcs: [ [ y, 5, 6 ], [ y^-1, 6, 5 ] ]
        groups: [ fa, fb ]
     subgroups: [ hy, hybar ]
  isomorphisms: [ [ [ a^3 ], [ b^2 ] ], [ [ b^2 ], [ a^3 ] ] ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsGraphOfFpGroups}}
\logpage{[ 4, 2, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsGraphOfFpGroups( gg )\index{IsGraphOfFpGroups@\texttt{IsGraphOfFpGroups}}
\label{IsGraphOfFpGroups}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsGraphOfPcGroups( gg )\index{IsGraphOfPcGroups@\texttt{IsGraphOfPcGroups}}
\label{IsGraphOfPcGroups}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsGraphOfPermGroups( gg )\index{IsGraphOfPermGroups@\texttt{IsGraphOfPermGroups}}
\label{IsGraphOfPermGroups}
}\hfill{\scriptsize (property)}}\\


 This is a list of properties to be expected of a graph of groups. In principle
any type of group known to \textsf{GAP} may be used as vertex groups, though these types are not normally mixed in a
single structure. }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> IsGraphOfFpGroups( G1 );
  true
  gap> IsomorphismsOfGraphOfGroups( G1 );
  [ [ a^3 ] -> [ b^2 ], [ b^2 ] -> [ a^3 ] ]
  
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{RightTransversalsOfGraphOfGroups}}
\logpage{[ 4, 2, 3 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RightTransversalsOfGraphOfGroups( gg )\index{RightTransversalsOfGraphOfGroups@\texttt{RightTransversalsOfGraphOfGroups}}
\label{RightTransversalsOfGraphOfGroups}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LeftTransversalsOfGraphOfGroups( gg )\index{LeftTransversalsOfGraphOfGroups@\texttt{LeftTransversalsOfGraphOfGroups}}
\label{LeftTransversalsOfGraphOfGroups}
}\hfill{\scriptsize (attribute)}}\\


 Computation with graph of groups words will require, for each arc subgroup \texttt{ha}, a set of representatives for the left cosets of \texttt{ha} in the tail vertex group. As already pointed out, we require subgroups of
finite index. Since \textsf{GAP} prefers to provide right cosets, we obtain the right representatives first,
and then invert them. 

 When the vertex groups are of type \texttt{FpGroup} we shall require normal forms for these groups, so we assume that such vertex
groups are provided with Knuth Bendix rewriting systems using functions from
the main \textsf{GAP} library, (e.g. \texttt{IsomorphismFpSemigroup}). 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> RTG1 := RightTransversalsOfGraphOfGroups( G1 );
  [ [ <identity ...>, a, a^2 ], [ <identity ...>, b ] ]
  gap> LTG1 := LeftTransversalsOfGraphOfGroups( G1 );
  [ [ <identity ...>, a^-1, a^-2 ], [ <identity ...>, b^-1 ] ] 
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Words in a Graph of Groups and their normal forms}}\logpage{[ 4, 3, 0 ]}
{
 

\subsection{\textcolor{Chapter }{GraphOfGroupsWord}}
\logpage{[ 4, 3, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GraphOfGroupsWord( gg, tv, list )\index{GraphOfGroupsWord@\texttt{GraphOfGroupsWord}}
\label{GraphOfGroupsWord}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsGraphOfGroupsWord( w )\index{IsGraphOfGroupsWord@\texttt{IsGraphOfGroupsWord}}
\label{IsGraphOfGroupsWord}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GraphOfGroupsOfWord( w )\index{GraphOfGroupsOfWord@\texttt{GraphOfGroupsOfWord}}
\label{GraphOfGroupsOfWord}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WordOfGraphOfGroupsWord( w )\index{WordOfGraphOfGroupsWord@\texttt{WordOfGraphOfGroupsWord}}
\label{WordOfGraphOfGroupsWord}
}\hfill{\scriptsize (attribute)}}\\


 If \texttt{G} is a graph of groups with underlying digraph \texttt{D}, the following groupoids may be considered. First there is the free groupoid
or path groupoid on \texttt{D}. Since we want each involutory pair of arcs to represent inverse elements in
the groupoid, we quotient out by the relations \texttt{y\^{}-1 = ybar} to obtain \texttt{PG(D)}. Secondly, there is the discrete groupoid \texttt{VG(D)}, namely the union of all the vertex groups. Since these two groupoids have
the same object set (the vertices of \texttt{D}) we can form \texttt{A(G)}, the free product of \texttt{PG(D)} and \texttt{VG(D)} amalgamated over the vertices. For further details of this universal groupoid
construction see \cite{emma-thesis}. (Note that these groupoids are not implemented in this package.) 

 An element of \texttt{A(G)} is a graph of groups word which may be represented by a list of the form $w = [g_1,y_1,g_2,y_2,...,g_n,y_n,g_{n+1}]$. Here each $y_i$ is an arc of \texttt{D}; the head of $y_{i-1}$ is a vertex $v_i$ which is also the tail of $y_i$; and $g_i$ is an element of the vertex group at $v_i$. So a graph of groups word requires as data the graph of groups; the tail
vertex for the word; and a list of arcs and group elements. We may specify
each arc by its position in the list of arcs. 

 In the following example, where \texttt{gw1} is a word in the trefoil graph of groups, the $y_i$ are specified by their positions in \texttt{A1}. Both arcs are traversed twice, so the resulting word is a loop at vertex $5$. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> L1 := [ a^7, 1, b^-6, 2, a^-11, 1, b^9, 2, a^7 ];;
  gap> gw1 := GraphOfGroupsWord( G1, 5, L1 );
  (5)a^7.y.b^-6.y^-1.a^-11.y.b^9.y^-1.a^7(5)
  gap> IsGraphOfGroupsWord( gw1 );
  true
  gap> [ Tail(gw1), Head(gw1) ];
  [ 5, 5 ]
  gap> GraphOfGroupsOfWord(gw1);
  Graph of Groups: 2 vertices; 2 arcs; groups [ fa, fb ]
  gap> WordOfGraphOfGroupsWord( gw1 );
  [ a^7, 1, b^-6, 2, a^-11, 1, b^9, 2, a^7 ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{ReducedGraphOfGroupsWord}}
\logpage{[ 4, 3, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ReducedGraphOfGroupsWord( w )\index{ReducedGraphOfGroupsWord@\texttt{ReducedGraphOfGroupsWord}}
\label{ReducedGraphOfGroupsWord}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsReducedGraphOfGroupsWord( w )\index{IsReducedGraphOfGroupsWord@\texttt{IsReducedGraphOfGroupsWord}}
\label{IsReducedGraphOfGroupsWord}
}\hfill{\scriptsize (property)}}\\


 A graph of groups word may be reduced in two ways, to give a normal form.
Firstly, if part of the word has the form \texttt{[yi, identity, yibar]} then this subword may be omitted. This is known as a length reduction.
Secondly there are coset reductions. Working from the left-hand end of the
word, subwords of the form $[g_i,y_i,g_{i+1}]$ are replaced by $[t_i,y_i,m_i(h_i)*g_{i+1}]$ where $g_i = t_i*h_i$ is the unique factorisation of $g_i$ as a left coset representative times an element of the arc subgroup, and $m_i$ is the isomorphism associated to $y_i$. Thus we may consider a coset reduction as passing a subgroup element along
an arc. The resulting normal form (if no length reductions have taken place)
is then $[t_1,y_1,t_2,y_2,...,t_n,y_n,k]$ for some $k$ in the head group of $y_n$. For further details see Section 2.2 of \cite{emma-thesis}. 

 The reduction of the word \texttt{gw1} in our example includes one length reduction. The four stages of the reduction
are as follows: 
\[ a^7b^{-6}a^{-11}b^9a^7 ~\mapsto~ a^{-2}b^0a^{-11}b^9a^7 ~\mapsto~
a^{-13}b^9a^7 ~\mapsto~ a^{-1}b^{-8}b^9a^7 ~\mapsto~ a^{-1}b^{-1}a^{10}. \]
 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> nw1 := ReducedGraphOfGroupsWord( gw1 );
  (5)a^-1.y.b^-1.y^-1.a^10(5)
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Free products with amalgamation and HNN extensions}}\logpage{[ 4, 4, 0 ]}
{
 

\subsection{\textcolor{Chapter }{FreeProductWithAmalgamation}}
\logpage{[ 4, 4, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{FreeProductWithAmalgamation( gp1, gp2, iso )\index{FreeProductWithAmalgamation@\texttt{FreeProductWithAmalgamation}}
\label{FreeProductWithAmalgamation}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsFpaGroup( fpa )\index{IsFpaGroup@\texttt{IsFpaGroup}}
\label{IsFpaGroup}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GraphOfGroupsRewritingSystem( fpa )\index{GraphOfGroupsRewritingSystem@\texttt{GraphOfGroupsRewritingSystem}}
\label{GraphOfGroupsRewritingSystem}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{NormalFormGGRWS( fpa, word )\index{NormalFormGGRWS@\texttt{NormalFormGGRWS}}
\label{NormalFormGGRWS}
}\hfill{\scriptsize (attribute)}}\\


 As we have seen with the trefoil group example, graphs of groups can be used
to obtain a normal form for free products with amalgamation $G_1 *_H G_2$ when $G_1, G_2$ both have rewrite systems, and $H$ is of finite index in both $G_1$ and $G_2$. 

 When \texttt{gp1} and \texttt{gp2} are fp-groups, the operation \texttt{FreeProductWithAmalgamation} constructs the required fp-group. When the two groups are permutation groups,
the \texttt{IsomorphismFpGroup} operation is called on both \texttt{gp1} and \texttt{gp2}, and the resulting isomorphism is transported to one between the two new
subgroups. 

 The attribute \texttt{GraphOfGroupsRewritingSystem} of \texttt{fpa} is the graph of groups which has underlying digraph \texttt{D1}, with two vertices and two arcs; the two groups as vertex groups; and the
specified isomorphisms on the arcs. Despite the name, graphs of groups
constructed in this way \emph{do not} belong to the category \texttt{IsRewritingSystem}. This anomaly may be dealt with when time permits. 

 The example below shows a computation in the the free product of the symmetric \texttt{s3} and the alternating \texttt{a4}, amalgamated over a cyclic subgroup \texttt{c3}. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> ## set up the first group s3 and a subgroup c3=<a1>
  gap> f1 := FreeGroup( 2, "a" );;
  gap> rel1 := [ f1.1^3, f1.2^2, (f1.1*f1.2)^2 ];;
  gap> s3 := f1/rel1;;
  gap> gs3 := GeneratorsOfGroup(s3);;
  gap> SetName( s3, "s3" );
  gap> a1 := gs3[1];;  a2 := gs3[2];;
  gap> H1 := Subgroup(s3,[a1]);;
  gap> ## then the second group a4 and subgroup c3=<b1>
  gap> f2 := FreeGroup( 2, "b" );;
  gap> rel2 := [ f2.1^3, f2.2^3, (f2.1*f2.2)^2 ];;
  gap> a4 := f2/rel2;;
  gap> ga4 := GeneratorsOfGroup(a4);;
  gap> SetName( a4, "a4" );
  gap> b1 := ga4[1];  b2 := ga4[2];;
  gap> H2 := Subgroup(a4,[b1]);;
  gap> ## form the isomorphism and the fpa group
  gap> iso := GroupHomomorphismByImages(H1,H2,[a1],[b1]);;
  gap> fpa := FreeProductWithAmalgamation( s3, a4, iso );
  <fp group on the generators [ fa1, fa2, fa3, fa4 ]>
  gap> RelatorsOfFpGroup( fpa );
  [ fa1^3, fa2^2, fa1*fa2*fa1*fa2, fa3^3, fa4^3, fa3*fa4*fa3*fa4, fa1*fa3^-1 ]
  gap> gg1 := GraphOfGroupsRewritingSystem( fpa );;
  gap> Display( gg1 );
  Graph of Groups with :-
      vertices: [ 5, 6 ]
          arcs: [ [ y, 5, 6 ], [ y^-1, 6, 5 ] ]
        groups: [ s3, a4 ]
     subgroups: [ Group( [ a1 ] ), Group( [ b1 ] ) ]
  isomorphisms: [ [ [ a1 ], [ b1 ] ], [ [ b1 ], [ a1 ] ] ]
  gap> LeftTransversalsOfGraphOfGroups( gg1 );
  [ [ <identity ..>, a2^-1 ], [ <identity ..>, b2^-1, b1^-1*b2^-1, b1*b2^-1 ] ]
  gap> ## choose a word in fpa and find its normal form 
  gap> gfpa := GeneratorsOfGraphOfGroups( fpa );;
  gap> w2 := (gfpa[1]*gfpa[2]*gfpa[3]^gfpa[4])^3;
  fa1*fa2*fa4^-1*fa3*fa4*fa1*fa2*fa4^-1*fa3*fa4*fa1*fa2*fa4^-1*fa3*fa4
  gap> n2 := NormalFormGGRWS( fpa, w2 );
  fa2*fa3*fa4^-1*fa2*fa4^-1*fa2*fa3^-1*fa4*fa3^-1
  
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{HnnExtension}}
\logpage{[ 4, 4, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{HnnExtension( gp, iso )\index{HnnExtension@\texttt{HnnExtension}}
\label{HnnExtension}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsHnnGroup( hnn )\index{IsHnnGroup@\texttt{IsHnnGroup}}
\label{IsHnnGroup}
}\hfill{\scriptsize (property)}}\\


 For \emph{HNN extensions}, the appropriate graph of groups has underlying digraph with just one vertex
and one pair of loops, weighted with \texttt{FpGroup} generators $z,z^{-1}$. There is one vertex group \texttt{G}, two isomorphic subgroups \texttt{H1,H2} of \texttt{G}, with the isomorphism and its inverse on the loops. The presentation of the
extension has one more generator than that of \texttt{G} and corresponds to the generator $z$. 

 The functions \texttt{GraphOfGroupsRewritingSystem} and \texttt{NormalFormGGRWS} may be applied to hnn-groups as well as to fpa-groups. 

 In the example we take \texttt{G=a4} and the two subgroups are cyclic groups of order 3. }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> H3 := Subgroup(a4,[b2]);;
  gap> i23 := GroupHomomorphismByImages( H2, H3, [b1], [b2] );;
  gap> hnn := HnnExtension( a4, i23 );
  <fp group on the generators [ fe1, fe2, fe3 ]> 
  gap> phnn := PresentationFpGroup( hnn );;
  gap> TzPrint( phnn );
  #I  generators: [ fe1, fe2, fe3 ]
  #I  relators:
  #I  1.  3  [ 1, 1, 1 ]
  #I  2.  3  [ 2, 2, 2 ]
  #I  3.  4  [ 1, 2, 1, 2 ]
  #I  4.  4  [ -3, 1, 3, -2 ] 
  gap> gg2 := GraphOfGroupsRewritingSystem( hnn );
  Graph of Groups: 1 vertices; 2 arcs; groups [ a4 ]
  gap> LeftTransversalsOfGraphOfGroups( gg2 );
  [ [ <identity ...>, b2^-1, b1^-1*b2^-1, b1*b2^-1 ],
    [ <identity ...>, b1^-1, b1, b2^-1*b1 ] ]
  gap> gh := GeneratorsOfGroup( hnn );;
  gap> w3 := (gh[1]^gh[2])*gh[3]^-1*(gh[1]*gh[3]*gh[2]^2)^2*gh[3]*gh[2];
  fe2^-1*fe1*fe2*fe3^-1*fe1*fe3*fe2^2*fe1*fe3*fe2^2*fe3*fe2 
  gap> n3 := NormalFormGGRWS( hnn, w3 );
  fe2*fe1*fe3*fe2*fe1*fe3   
  
\end{Verbatim}
 Both fpa-groups and hnn-groups are provided with a record attribute, \texttt{FpaInfo(fpa)} and \texttt{HnnInfo(hnn)} respectively, storing the groups and isomorphisms involved in their
construction. 

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> fpainfo := FpaInfo( fpa );
  rec( groups := [ s3, a4 ], positions := [ [ 1, 2 ], [ 3, 4 ] ],
    isomorphism := [ a1 ] -> [ b1 ] )
  gap> hnninfo := HnnInfo( hnn );
  rec( group := a4, isomorphism := [ b1 ] -> [ b2 ] )
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{GraphsOfGroupoids and their Words}}\logpage{[ 4, 5, 0 ]}
{
 

\subsection{\textcolor{Chapter }{GraphOfGroupoids}}
\logpage{[ 4, 5, 1 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GraphOfGroupoids( dig, gpds, subgpds, isos )\index{GraphOfGroupoids@\texttt{GraphOfGroupoids}}
\label{GraphOfGroupoids}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsGraphOfPermGroupoids( gg )\index{IsGraphOfPermGroupoids@\texttt{IsGraphOfPermGroupoids}}
\label{IsGraphOfPermGroupoids}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsGraphOfFpGroupoids( gg )\index{IsGraphOfFpGroupoids@\texttt{IsGraphOfFpGroupoids}}
\label{IsGraphOfFpGroupoids}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GroupoidsOfGraphOfGroupoids( gg )\index{GroupoidsOfGraphOfGroupoids@\texttt{GroupoidsOfGraphOfGroupoids}}
\label{GroupoidsOfGraphOfGroupoids}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{DigraphOfGraphOfGroupoids( gg )\index{DigraphOfGraphOfGroupoids@\texttt{DigraphOfGraphOfGroupoids}}
\label{DigraphOfGraphOfGroupoids}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{SubgroupoidsOfGraphOfGroupoids( gg )\index{SubgroupoidsOfGraphOfGroupoids@\texttt{SubgroupoidsOfGraphOfGroupoids}}
\label{SubgroupoidsOfGraphOfGroupoids}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsomorphismsOfGraphOfGroupoids( gg )\index{IsomorphismsOfGraphOfGroupoids@\texttt{IsomorphismsOfGraphOfGroupoids}}
\label{IsomorphismsOfGraphOfGroupoids}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{RightTransversalsOfGraphOfGroupoids( gg )\index{RightTransversalsOfGraphOfGroupoids@\texttt{RightTransversalsOfGraphOfGroupoids}}
\label{RightTransversalsOfGraphOfGroupoids}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{LefvtTransversalsOfGraphOfGroupoids( gg )\index{LefvtTransversalsOfGraphOfGroupoids@\texttt{LefvtTransversalsOfGraphOfGroupoids}}
\label{LefvtTransversalsOfGraphOfGroupoids}
}\hfill{\scriptsize (attribute)}}\\


 Graphs of groups generalise naturally to graphs of groupoids, forming the
class \texttt{IsGraphOfGroupoids}. There is now a groupoid at each vertex and the isomorphism on an arc
identifies wide subgroupoids at the tail and at the head. Since all
subgroupoids are wide, every groupoid in a connected component of the graph
has the same number of objects, but there is no requirement that the object
sets are all the same. 

 The example below generalises the trefoil group example in subsection 4.4.1,
taking at each vertex of \texttt{D1} a two-object groupoid with a free group on one generator, and full
subgroupoids with groups $\langle a^3 \rangle$ and $\langle b^2 \rangle$. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> Gfa := ConnectedGroupoid( [-2,-1], fa );;
  gap> Uhy := Subgroupoid( Gfa, [ [[-2,-1], hy ] ] );;
  gap> SetName( Gfa, "Gfa" );  SetName( Uhy, "Uhy" );
  gap> Gfb := ConnectedGroupoid( [-4,-3], fb );;
  gap> Uhybar := Subgroupoid( Gfb, [ [[-4,-3], hybar ] ] );;
  gap> SetName( Gfb, "Gfb" );  SetName( Uhybar, "Uhybar" );
  gap> mory := MorphismOfConnectedGroupoids( Uhy, Uhybar, [-4,-3], homy );;
  gap> morybar := MorphismOfConnectedGroupoids( Uhybar, Uhy, [-2,-1], homybar );;
  gap> gg3 := GraphOfGroupoids( D1, [Gfa,Gfb], [Uhy,Uhybar], [mory,morybar] );;
  gap> Display(gg3);
  Graph of Groupoids with :-
      vertices: [ 5, 6 ]
          arcs: [ [ y, 5, 6 ], [ y^-1, 6, 5 ] ]
     groupoids:
  Fp Connected Groupoid: Gfa
    objects: [ -2, -1 ]
      group: fa = <[ a ]>
  Fp Connected Groupoid: Gfb
    objects: [ -4, -3 ]
      group: fb = <[ b ]>
  subgroupoids: Connected Groupoid: Uhy
    objects: [ -2, -1 ]
      group: hy = <[ a^3 ]>
  Connected Groupoid: Uhybar
    objects: [ -4, -3 ]
      group: hybar = <[ b^2 ]>
  isomorphisms: [ Groupoid morphism : Uhy -> Uhybar
      , Groupoid morphism : Uhybar -> Uhy
       ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{GraphOfGroupoidsWord}}
\logpage{[ 4, 5, 2 ]}\nobreak
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GraphOfGroupoidsWord( gg, tv, list )\index{GraphOfGroupoidsWord@\texttt{GraphOfGroupoidsWord}}
\label{GraphOfGroupoidsWord}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsGraphOfGroupoidsWord( w )\index{IsGraphOfGroupoidsWord@\texttt{IsGraphOfGroupoidsWord}}
\label{IsGraphOfGroupoidsWord}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{GraphOfGroupoidsOfWord( w )\index{GraphOfGroupoidsOfWord@\texttt{GraphOfGroupoidsOfWord}}
\label{GraphOfGroupoidsOfWord}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{WordOfGraphOfGroupoidsWord( w )\index{WordOfGraphOfGroupoidsWord@\texttt{WordOfGraphOfGroupoidsWord}}
\label{WordOfGraphOfGroupoidsWord}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{ReducedGraphOfGroupoidsWord( w )\index{ReducedGraphOfGroupoidsWord@\texttt{ReducedGraphOfGroupoidsWord}}
\label{ReducedGraphOfGroupoidsWord}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsReducedGraphOfGroupoidsWord( w )\index{IsReducedGraphOfGroupoidsWord@\texttt{IsReducedGraphOfGroupoidsWord}}
\label{IsReducedGraphOfGroupoidsWord}
}\hfill{\scriptsize (property)}}\\


 Having produced the graph of groupoids \texttt{gg3}, we may construct left coset representatives; choose a graph of groupoids
word; and reduce this to normal form. Compare the \texttt{nw3} below with the normal form \texttt{nw1} in subsection 4.3.2. 

 }

 
\begin{Verbatim}[fontsize=\small,frame=single,label=Example]
  
  gap> f1 := GroupoidElement( Gfa, a^7, -1, -2);;
  gap> f2 := GroupoidElement( Gfb, b^-6, -4, -4 );;
  gap> f3 := GroupoidElement( Gfa, a^-11, -2, -1 );;
  gap> f4 := GroupoidElement( Gfb, b^9, -3, -4 );;
  gap> f5 := GroupoidElement( Gfa, a^7, -2, -1 );;
  gap> L3 := [ f1, 1, f2, 2, f3, 1, f4, 2, f5 ];
  [ [a^7 : -1 -> -2], 1, [b^-6 : -4 -> -4], 2, [a^-11 : -2 -> -1], 1,
    [b^9 : -3 -> -4], 2, [a^7 : -2 -> -1] ]
  gap> gw3 := GraphOfGroupoidsWord( gg3, 5, L3);
  (5)[a^7 : -1 -> -2].y.[b^-6 : -4 -> -4].y^-1.[a^-11 : -2 -> -1].y.[b^9 :
  -3 -> -4].y^-1.[a^7 : -2 -> -1](5)
  gap> nw3 := ReducedGraphOfGroupoidsWord( gw3 );
  (5)[a^-1 : -1 -> -2].y.[b^-1 : -4 -> -4].y^-1.[a^10 : -2 -> -1](5)
  
\end{Verbatim}
 }

 More examples of these operations may be found in the example file \texttt{gpd/examples/ggraph.g}. }

           
\chapter{\textcolor{Chapter }{Development History}}\label{history}
\logpage{[ 5, 0, 0 ]}
{
  
\section{\textcolor{Chapter }{Versions of the Package}}\logpage{[ 5, 1, 0 ]}
{
 The first version, \textsf{GraphGpd} 1.001, formed part of Emma Moore's thesis \cite{emma-thesis} in December 2000, but was not made generally available. 

 Version 1.002 of \textsf{GraphGpd} was prepared to run under \textsf{GAP} 4.4 in January 2004; was submitted to the \textsf{GAP} council to be considered as an accepted package; but suggestions from the
referee were not followed up. 

 In April 2006 the manual was converted to \textsf{GAPDoc} format. Variables \texttt{Star}, \texttt{Costar} and \texttt{CoveringGroup} were found to conflict with usage in other packages, and were renamed \texttt{VertexStar}, \texttt{VertexCostar} and \texttt{CoveringGroupOfGroupoid} respectively. Similarly, the \texttt{Vertices} and \texttt{Arcs} of an \texttt{FpWeightedDigraph} were changed from attributes to record components. 

 In the spring of 2006 the package was extensively rewritten and renamed \textsf{Gpd}. Version 1.01 was submitted as a deposited package in June 2006. }

 
\section{\textcolor{Chapter }{What needs to be done next?}}\logpage{[ 5, 2, 0 ]}
{
 Computationally, there are three types of connected groupoid: 
\begin{itemize}
\item  those with identical object groups, 
\item  those with object groups conjugate in some supergroup, 
\item  those with object groups which are simply isomorphic. 
\end{itemize}
 \textsf{GraphGpd} attempted to implement the second case. \textsf{Gpd} 1.01 restricts itself to the first case. \textsf{Gpd} 1.02 will extend 1.01 to the second case. 

 Here are some other immediate requirements: 
\begin{itemize}
\item  normal subgroupoids and quotient groupoids; 
\item  more methods for morphisms of groupoids, particularly when the range is not
connected; 
\item  \texttt{ImageElm} and \texttt{ImagesSource} for the cases of groupoid morphisms not yet covered; 
\item  \texttt{Enumerator} for \texttt{IsHomsetCosetsRep}; 
\item  free groupoid on a graph; 
\item  methods for \texttt{FreeProductWithAmalgamation} and \texttt{HnnEntension} for pc-groups; 
\item  convert \texttt{GraphOfGroupsRewritingSystem} to the category \texttt{IsRewritingSystem}; 
\item  in \textsf{XMod}, implement crossed modules over groupoids. 
\end{itemize}
 }

 }

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

\bibliographystyle{alpha}
\bibliography{manual}

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


\printindex

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