Impressum groupoids.tex

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

            \usepackage[all]{xy} 
            \newcommand{\Aut} {\mathrm{Aut}}
            \newcommand{\AUT} {\mathrm{AUT}}
            \newcommand{\Inn} {\mathrm{Inn}}
        
\usepackage[top=37mm,bottom=37mm,left=27mm,right=27mm]{geometry}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[utf8]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}

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

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


\usepackage{fancyvrb}

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


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

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

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

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

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

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





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


\begin{document}

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

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

\hypersetup{pdftitle= groupoids }
\markright{\scriptsize \mbox{}\hfill  groupoids  \hfill\mbox{}}
{\Huge \textbf{ Calculations with finite groupoids and their homomorphisms \mbox{}}}\\
\vfill

{\Huge  1.79 \mbox{}}\\[1cm]
{ 11 September 2025 \mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\Large \textbf{ Emma J. Moore\\
 \mbox{}}}\\
{\Large \textbf{ Chris Wensley\\
   \mbox{}}}\\
\hypersetup{pdfauthor= Emma J. Moore\\
 ;  Chris Wensley\\
   }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{ Chris Wensley\\
   }  Email: \href{mailto://cdwensley.maths@btinternet.com} {\texttt{cdwensley.maths@btinternet.com}}\\
  Homepage: \href{https://github.com/cdwensley} {\texttt{https://github.com/cdwensley}}}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Abstract}
\logpage{[ 0, 0, 1 ]}
 The \textsf{groupoids} package provides functions for computation with groupoids (categories with
every arrow invertible) and their morphisms; for graphs of groups, and graphs
of groupoids. The most basic structure introduced is that of \emph{magma with objects}; followed by \emph{semigroup with objects}; then \emph{monoid with objects}; and finally \emph{groupoid}, which is a \emph{group with objects}. 

It provides normal forms for Free Products with Amalgamation and for
HNN\texttt{\symbol{45}}extensions when the initial groups have rewrite systems
and the subgroups have finite index. 

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

The package was then renamed \textsf{Gpd} and version 1.07 was released in July 2011, ready for \textsf{GAP} 4.5. 

\textsf{Gpd} became an accepted \textsf{GAP} package in May 2015. 

In April 2017 the package was renamed again, as \textsf{groupoids}. 

Later versions implement many of the constructions described in the paper \cite{AlWe} for automorphisms of groupoids. 

Bug reports, comments, suggestions for additional features, and offers to
implement some of these, will all be very welcome. 

Please submit any issues at \href{https://github.com/gap-packages/groupoids/issues/} {\texttt{https://github.com/gap\texttt{\symbol{45}}packages/groupoids/issues/}} or send an email to the second author at \href{mailto://cdwensley.maths@btinternet.com} {\texttt{cdwensley.maths@btinternet.com}}. 

 \mbox{}}\\[1cm]
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 2 ]}
 {\copyright} 2000\texttt{\symbol{45}}2025, Emma Moore and Chris Wensley.

 The \textsf{groupoids} package 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. \mbox{}}\\[1cm]
{\small 
\section*{Acknowledgements}
\logpage{[ 0, 0, 3 ]}
 This documentation was prepared using the \textsf{GAPDoc} \cite{GAPDoc} and \textsf{AutoDoc} \cite{AutoDoc} packages.

 The procedure used to produce new releases uses the package \textsf{GitHubPagesForGAP} \cite{GitHubPagesForGAP} and the package \textsf{ReleaseTools}.

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

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

\tableofcontents
\newpage

  
\chapter{\textcolor{Chapter }{Introduction}}\label{chap-intro}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X7DFB63A97E67C0A1}{}
{
  Groupoids are mathematical categories in which every arrow is invertible. The \textsf{groupoids} 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 \emph{free products with amalgamation}, and for \emph{HNN\texttt{\symbol{45}}extensions} when the initial groups have rewriting systems. 

 The package may be obtained as a compressed tar file \texttt{groupoids\texttt{\symbol{45}}version.number.tar.gz} by ftp from one of the following sites: 
\begin{itemize}
\item  the \textsf{groupoids} GitHub site: \href{https://github.com/gap-packages.github.io/groupoids/} {\texttt{https://github.com/gap\texttt{\symbol{45}}packages.github.io/groupoids/}}. 
\item  any \textsf{GAP} archive, e.g. \href{https://www.gap-system.org/Packages/packages.html} {\texttt{https://www.gap\texttt{\symbol{45}}system.org/Packages/packages.html}}; 
\end{itemize}
 The package also has a GitHub repository at: \href{https://github.com/gap-packages/groupoids/} {\texttt{https://github.com/gap\texttt{\symbol{45}}packages/groupoids/}}. 

 The information parameter \texttt{InfoGroupoids} 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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@LoadPackage( "groupoids" );|
  
\end{Verbatim}
 For version 1.05 the package was completely restructured, starting with \emph{magmas with objects} and their mappings, and building up to groupoids via semigroups with objects
and monoids with objects. From version 1.07 the package includes some
functions to implement constructions for automorphisms and homotopies, as
described in \cite{AlWe}. More functions will be released when time permits. 

 Once the package is loaded, it is possible to check the installation has
proceeded correctly by running the test suite of the package with the command \texttt{ ReadPackage("groupoids","tst/testing.g"); }. Additional tests may be run using \texttt{ ReadPackage("groupoids","tst/testextra.g");.} (The file \texttt{"tst/testall.g"} is used for automated testing.) 

 You may reference this package by mentioning \cite{BrMoPoWe}, \cite{emma-thesis} and \cite{AlWe}. 

 Additional information on \emph{Computational Higher Dimensional Algebra} can be found in the notes on crossed modules at: \href{https://github.com/cdwensley/xmod-notes} {\texttt{https://github.com/cdwensley/xmod\texttt{\symbol{45}}notes}}. }

  
\chapter{\textcolor{Chapter }{Many\texttt{\symbol{45}}object structures}}\label{chap-mwp}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X8361CEA4856430C6}{}
{
  The aim of this package is to provide operations for finite groupoids. A \emph{groupoid} is constructed from a group and a set of objects. In order to provide a
sequence of categories, with increasing structure, mimicing those for groups,
we introduce in this chapter the notions of \emph{magma with objects}; \emph{semigroup with objects} and \emph{monoid with objects}. The next chapter introduces morphisms of these structures. At a first
reading of this manual, the user is advised to skip quickly through these
first two chapters, and then move on to groupoids in Chapter \ref{chap-gpd}. 

 The definitions of the standard properties of groupoids can be found in Philip
Higgins' book ``Categories and Groupoids'' \cite{HiGpd} (originally published in 1971, reprinted by TAC in 2005), and in Ronnie
Brown's book ``Topology'' \cite{BrTop}, revised and reissued as ``Topology and Groupoids'' \cite{BrTopGpd}. 
\section{\textcolor{Chapter }{Magmas with objects; arrows}}\label{sec-mwo}
\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X7920BF45828AE5DE}{}
{
  A \emph{magma with objects} $M$ consists of a set of \emph{objects} Ob$(M)$, and a set of \emph{arrows} Arr$(M)$ together with \emph{tail} and \emph{head} maps $t,h :$ Arr$(M) \to$ Ob$(M)$, and a \emph{partial multiplication} $* :$ Arr$(M) \to $ Arr$(M)$, with $a*b$ defined precisely when the head of $a$ coincides with the tail of $b$. We write an arrow $a$ with tail $u$ and head $v$ as $(a : u \to v)$. 

 When this multiplication is associative we obtain a \emph{semigroup with objects}. 

 A \emph{loop} is an arrow whose tail and head are the same object. An \emph{identity arrow} at object $u$ is a loop $(1_u : u \to u)$ such that $a*1_u=a$ and $1_u*b=b$ whenever $u$ is the head of $a$ and the tail of $b$. When $M$ is a semigroup with objects and every object has an identity arrow, we obtain
a \emph{monoid with objects}, which is just the usual notion of mathematical category. 

 An arrow $(a : u \to v)$ in a monoid with objects has \emph{inverse} $(a^{-1} : v \to u)$ provided $a*a^{-1} = 1_u$ and $a^{-1}*a = 1_v$. A monoid with objects in which every arrow has an inverse is a \emph{group with objects}, usually called a \emph{groupoid}. 

\subsection{\textcolor{Chapter }{MagmaWithObjects}}
\logpage{[ 2, 1, 1 ]}\nobreak
\hyperdef{L}{X7C51D7847BD23284}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{MagmaWithObjects({\mdseries\slshape args})\index{MagmaWithObjects@\texttt{MagmaWithObjects}}
\label{MagmaWithObjects}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SinglePieceMagmaWithObjects({\mdseries\slshape magma, obs})\index{SinglePieceMagmaWithObjects@\texttt{SinglePieceMagmaWithObjects}}
\label{SinglePieceMagmaWithObjects}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ObjectList({\mdseries\slshape mwo})\index{ObjectList@\texttt{ObjectList}!for magmas with objects}
\label{ObjectList:for magmas with objects}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RootObject({\mdseries\slshape mwo})\index{RootObject@\texttt{RootObject}!for magmas with objects}
\label{RootObject:for magmas with objects}
}\hfill{\scriptsize (attribute)}}\\


 The simplest construction for a magma with objects $M$ is to take a magma $m$ and an ordered set $s$, and form arrows $(u,a,v)$ for every $a$ in $m$ and $u,v$ in $s$. Multiplication is defined by $(u,a,v)*(v,b,w) = (u,a*b,w)$. In this package we prefer to write $(u,a,v)$ as $(a : u \to v)$, so that the multiplication rule becomes $(a : u \to v)*(b : v \to w) = (a*b : u \to w)$. 

 Any finite, ordered set is in principle acceptable as the object list of $M$, but most of the time we find it convenient to restrict ourselves to sets of
non\texttt{\symbol{45}}positive integers. 

 This is the only construction implemented here for magmas, semigroups, and
monoids with objects, and these all have the property \texttt{IsDirectProductWithCompleteDigraph}. There are other constructions implemented for groupoids. 

 The \emph{root object} of $M$ is the first element in $s$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@tm := [[1,2,4,3],[1,2,4,3],[3,4,2,1],[3,4,2,1]];; |
  !gapprompt@gap>| !gapinput@Display( tm );|
  [ [  1,  2,  4,  3 ],
    [  1,  2,  4,  3 ],
    [  3,  4,  2,  1 ],
    [  3,  4,  2,  1 ] ]
  !gapprompt@gap>| !gapinput@m := MagmaByMultiplicationTable( tm );;  SetName( m, "m" );|
  !gapprompt@gap>| !gapinput@m1 := MagmaElement(m,1);;  m2 := MagmaElement(m,2);; |
  !gapprompt@gap>| !gapinput@m3 := MagmaElement(m,3);;  m4 := MagmaElement(m,4);; |
  !gapprompt@gap>| !gapinput@M78 := MagmaWithObjects( m, [-8,-7] ); |
  magma with objects :-
      magma = m
    objects = [ -8, -7 ]
  !gapprompt@gap>| !gapinput@SetName( M78, "M78" ); |
  !gapprompt@gap>| !gapinput@[ IsAssociative(M78), IsCommutative(M78) ]; |
  [ false, false ]
  !gapprompt@gap>| !gapinput@[ RootObject( M78 ), ObjectList( M78 ) ]; |
  [ -8, [ -8, -7 ] ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsDomainWithObjects}}
\logpage{[ 2, 1, 2 ]}\nobreak
\hyperdef{L}{X87D1C0BC86749E6D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsDomainWithObjects({\mdseries\slshape obj})\index{IsDomainWithObjects@\texttt{IsDomainWithObjects}}
\label{IsDomainWithObjects}
}\hfill{\scriptsize (Category)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsMagmaWithObjects({\mdseries\slshape obj})\index{IsMagmaWithObjects@\texttt{IsMagmaWithObjects}}
\label{IsMagmaWithObjects}
}\hfill{\scriptsize (Category)}}\\


 The output from function \texttt{MagmaWithObjects} lies in the categories \texttt{IsDomainWithObjects}, \texttt{IsMagmaWithObjects} and \texttt{CategoryCollections(IsMultiplicativeElementWithObjects)}. As composition is only partial, the output does \emph{not} lie in the category \texttt{IsMagma}. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@[ IsDomainWithObjects(M78), IsMagmaWithObjects(M78), IsMagma(M78) ]; |
  [ true, true, false ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{Arrow}}
\logpage{[ 2, 1, 3 ]}\nobreak
\label{man-arrow}
\hyperdef{L}{X86247DFC8242CEBE}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Arrow({\mdseries\slshape mwo, elt, tail, head})\index{Arrow@\texttt{Arrow}}
\label{Arrow}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ElementOfArrow({\mdseries\slshape arr})\index{ElementOfArrow@\texttt{ElementOfArrow}!for magmas with objects}
\label{ElementOfArrow:for magmas with objects}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{TailOfArrow({\mdseries\slshape arr})\index{TailOfArrow@\texttt{TailOfArrow}!for magmas with objects}
\label{TailOfArrow:for magmas with objects}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HeadOfArrow({\mdseries\slshape arr})\index{HeadOfArrow@\texttt{HeadOfArrow}!for magmas with objects}
\label{HeadOfArrow:for magmas with objects}
}\hfill{\scriptsize (operation)}}\\


 Arrows in a magma with objects lie in the category \index{IsMultiplicativeElementWithObjects@\texttt{IsMultiplicativeElementWithObjects}} \texttt{IsMultiplicativeElementWithObjects}. An attempt to multiply two arrows which do not compose resuts in \texttt{fail} being returned. Each arrow $arr = (a : u \to v)$ has three components. The magma \emph{element} $a \in m$ may be accessed by \texttt{ElementOfArrow(arr)}. Similarly, the \emph{tail} object $u$ and the \emph{head} object $v$ may be obtained using \texttt{TailOfArrow(arr)} and \texttt{HeadOfArrow(arr)} respectively. The operation \texttt{MultiplicativeElementWithObjects} is a synonym for \texttt{Arrow} since this was used in older versions of the package. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@a78 := Arrow( M78, m2, -7, -8 ); |
  [m2 : -7 -> -8]
  !gapprompt@gap>| !gapinput@a78 in M78; |
  true
  !gapprompt@gap>| !gapinput@b87 := Arrow( M78, m4, -8, -7 );;|
  !gapprompt@gap>| !gapinput@[ ElementOfArrow( b87 ), TailOfArrow( b87 ), HeadOfArrow( b87 ) ]; |
  [ m4, -8, -7 ]
  !gapprompt@gap>| !gapinput@ba := b87*a78;;  ab := a78*b87;;  [ ba, ab ];|
  [ [m4 : -8 -> -8], [m3 : -7 -> -7] ]
  !gapprompt@gap>| !gapinput@[ a78^2, ba^2, ba^3 ]; |
  [ fail, [m1 : -8 -> -8], [m3 : -8 -> -8] ]
  !gapprompt@gap>| !gapinput@## this demonstrates non-associativity with a78*b87*a78:|
  !gapprompt@gap>| !gapinput@[ a78*ba, ab*a78, a78*ba=ab*a78 ]; |
  [ [m3 : -7 -> -8], [m4 : -7 -> -8], false ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsSinglePieceDomain}}
\logpage{[ 2, 1, 4 ]}\nobreak
\hyperdef{L}{X7B3352148103FD05}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsSinglePieceDomain({\mdseries\slshape mwo})\index{IsSinglePieceDomain@\texttt{IsSinglePieceDomain}}
\label{IsSinglePieceDomain}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsSinglePiece({\mdseries\slshape mwo})\index{IsSinglePiece@\texttt{IsSinglePiece}}
\label{IsSinglePiece}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsDirectProductWithCompleteDigraph({\mdseries\slshape mwo})\index{IsDirectProductWithCompleteDigraph@\texttt{IsDirectProductWithCompleteDigraph}}
\label{IsDirectProductWithCompleteDigraph}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsDiscreteMagmaWithObjects({\mdseries\slshape mwo})\index{IsDiscreteMagmaWithObjects@\texttt{IsDiscreteMagmaWithObjects}}
\label{IsDiscreteMagmaWithObjects}
}\hfill{\scriptsize (property)}}\\


 If the partial composition is forgotten, then what remains is a digraph
(usually with multiple edges and loops). Thus the notion of \emph{connected component} may be inherited by magmas with objects from digraphs. Unfortunately the terms \texttt{Component} and \texttt{Constituent} are already in considerable use elsewhere in \textsf{GAP}, so (and this may change if a more suitable word is suggested) we use the
term \texttt{IsSinglePieceDomain} to describe an object with an underlying connected digraph. The property \texttt{IsSinglePiece} is a synonym for \texttt{IsSinglePieceDomain and IsMagmaWithObjects}. When each connected component has a single object, and there is more than
one component, the magma with objects is \emph{discrete}. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@IsSinglePiece( M78 ); |
  true
  !gapprompt@gap>| !gapinput@IsDirectProductWithCompleteDigraph( M78 );|
  true
  !gapprompt@gap>| !gapinput@IsDiscreteMagmaWithObjects( M78 ); |
  false
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Semigroups with objects}}\label{sec-swo}
\logpage{[ 2, 2, 0 ]}
\hyperdef{L}{X7FDF94E8791B9BC1}{}
{
  

\subsection{\textcolor{Chapter }{SemigroupWithObjects}}
\logpage{[ 2, 2, 1 ]}\nobreak
\hyperdef{L}{X8519787D833653A7}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SemigroupWithObjects({\mdseries\slshape args})\index{SemigroupWithObjects@\texttt{SemigroupWithObjects}}
\label{SemigroupWithObjects}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SinglePieceSemigroupWithObjects({\mdseries\slshape sgp, obs})\index{SinglePieceSemigroupWithObjects@\texttt{SinglePieceSemigroupWithObjects}}
\label{SinglePieceSemigroupWithObjects}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{MagmaWithSingleObject({\mdseries\slshape dom, obj})\index{MagmaWithSingleObject@\texttt{MagmaWithSingleObject}!for semigroups}
\label{MagmaWithSingleObject:for semigroups}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsSemigroupWithObjects({\mdseries\slshape obj})\index{IsSemigroupWithObjects@\texttt{IsSemigroupWithObjects}}
\label{IsSemigroupWithObjects}
}\hfill{\scriptsize (filter)}}\\


 The constructions in section \ref{sec-mwo} give a \texttt{SinglePieceSemigroupWithObjects} when the magma is a semigroup. In the following example we use a
transformation semigroup and $3$ objects. 

 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@t := Transformation( [1,1,2,3] );; |
  !gapprompt@gap>| !gapinput@s := Transformation( [2,2,3,3] );;|
  !gapprompt@gap>| !gapinput@r := Transformation( [2,3,4,4] );; |
  !gapprompt@gap>| !gapinput@sgp := Semigroup( t, s, r );; |
  !gapprompt@gap>| !gapinput@SetName( sgp, "sgp<t,s,r>" ); |
  !gapprompt@gap>| !gapinput@S123 := SemigroupWithObjects( sgp, [-3,-2,-1] ); |
  semigroup with objects :-
      magma = sgp<t,s,r>
    objects = [ -3, -2, -1 ]
  !gapprompt@gap>| !gapinput@[ IsAssociative(S123), IsCommutative(S123) ];|
  [ true, false ]
  !gapprompt@gap>| !gapinput@t12 := Arrow( S123, t, -1, -2 );|
  [Transformation( [ 1, 1, 2, 3 ] ) : -1 -> -2]
  !gapprompt@gap>| !gapinput@s23 := Arrow( S123, s, -2, -3 );|
  [Transformation( [ 2, 2, 3, 3 ] ) : -2 -> -3]
  !gapprompt@gap>| !gapinput@r31 := Arrow( S123, r, -3, -1 );|
  [Transformation( [ 2, 3, 4, 4 ] ) : -3 -> -1]
  !gapprompt@gap>| !gapinput@ts13 := t12 * s23;|
  [Transformation( [ 2, 2, 2, 3 ] ) : -1 -> -3]
  !gapprompt@gap>| !gapinput@sr21 := s23 * r31;|
  [Transformation( [ 3, 3, 4, 4 ] ) : -2 -> -1]
  !gapprompt@gap>| !gapinput@rt32 := r31 * t12;|
  [Transformation( [ 1, 2, 3, 3 ] ) : -3 -> -2]
  !gapprompt@gap>| !gapinput@tsr1 := ts13 * r31;|
  [Transformation( [ 3, 3, 3 ] ) : -1 -> -1]
  
\end{Verbatim}
 A magma, semigroup, monoid, or group $M$ can be made into a magma with objects by the addition of a single object. The
two are algebraically isomorphic, and there is one arrow (a loop) for each
element in $M$. In the example we take the transformation semigroup above, which has size $17$ at the object $0$. 

 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@S0 := MagmaWithSingleObject( sgp, 0 );|
  semigroup with objects :-
      magma = sgp<t,s,r>
    objects = [ 0 ]
  !gapprompt@gap>| !gapinput@t0 := Arrow( S0, t, 0, 0 );            |
  [Transformation( [ 1, 1, 2, 3 ] ) : 0 -> 0]
  !gapprompt@gap>| !gapinput@Size( S0 );|
  17
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Monoids with objects}}\label{monwo}
\logpage{[ 2, 3, 0 ]}
\hyperdef{L}{X86C32E6981557ED0}{}
{
  

\subsection{\textcolor{Chapter }{MonoidWithObjects}}
\logpage{[ 2, 3, 1 ]}\nobreak
\hyperdef{L}{X7A271B1A7F2FF245}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{MonoidWithObjects({\mdseries\slshape args})\index{MonoidWithObjects@\texttt{MonoidWithObjects}}
\label{MonoidWithObjects}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SinglePieceMonoidWithObjects({\mdseries\slshape mon, obs})\index{SinglePieceMonoidWithObjects@\texttt{SinglePieceMonoidWithObjects}}
\label{SinglePieceMonoidWithObjects}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsMonoidWithObjects({\mdseries\slshape obj})\index{IsMonoidWithObjects@\texttt{IsMonoidWithObjects}}
\label{IsMonoidWithObjects}
}\hfill{\scriptsize (filter)}}\\


 The constructions in section \ref{sec-mwo} give a \texttt{SinglePieceMonoidWithObjects} when the magma is a monoid. The example uses a finitely presented monoid with $2$ generators and $2$ objects. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@fm := FreeMonoid( 2, "f" );;|
  !gapprompt@gap>| !gapinput@em := One( fm );;|
  !gapprompt@gap>| !gapinput@gm := GeneratorsOfMonoid( fm );;|
  !gapprompt@gap>| !gapinput@mon := fm/[ [gm[1]^3,em], [gm[1]*gm[2],gm[2]] ];; |
  !gapprompt@gap>| !gapinput@M49 := MonoidWithObjects( mon, [-9,-4] ); |
  monoid with objects :-
      magma = Monoid( [ f1, f2 ] )
    objects = [ -9, -4 ]
  !gapprompt@gap>| !gapinput@ktpo := KnownTruePropertiesOfObject( M49 );|
  [ "IsDuplicateFree", "IsAssociative", "IsSinglePieceDomain", 
    "IsDirectProductWithCompleteDigraphDomain" ]
  !gapprompt@gap>| !gapinput@catobj := CategoriesOfObject( M49 );; |
  [ "IsListOrCollection", "IsCollection", "IsExtLElement", 
    "CategoryCollections(IsExtLElement)", "IsExtRElement", 
    "CategoryCollections(IsExtRElement)", 
    "CategoryCollections(IsMultiplicativeElement)", "IsGeneralizedDomain", 
    "IsDomainWithObjects", 
    "CategoryCollections(IsMultiplicativeElementWithObjects)", 
    "CategoryCollections(IsMultiplicativeElementWithObjectsAndOnes)", 
    "CategoryCollections(IsMultiplicativeElementWithObjectsAndInverses)", 
    "IsMagmaWithObjects", "IsSemigroupWithObjects", "IsMonoidWithObjects" ]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Generators of magmas with objects}}\label{genwo}
\logpage{[ 2, 4, 0 ]}
\hyperdef{L}{X842D1B0C7A76CC15}{}
{
  

\subsection{\textcolor{Chapter }{GeneratorsOfMagmaWithObjects}}
\logpage{[ 2, 4, 1 ]}\nobreak
\hyperdef{L}{X83239B307EE95054}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GeneratorsOfMagmaWithObjects({\mdseries\slshape mwo})\index{GeneratorsOfMagmaWithObjects@\texttt{GeneratorsOfMagmaWithObjects}}
\label{GeneratorsOfMagmaWithObjects}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GeneratorsOfSemigroupWithObjects({\mdseries\slshape swo})\index{GeneratorsOfSemigroupWithObjects@\texttt{GeneratorsOfSemigroupWithObjects}}
\label{GeneratorsOfSemigroupWithObjects}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GeneratorsOfMonoidWithObjects({\mdseries\slshape mwo})\index{GeneratorsOfMonoidWithObjects@\texttt{GeneratorsOfMonoidWithObjects}}
\label{GeneratorsOfMonoidWithObjects}
}\hfill{\scriptsize (operation)}}\\


 For a magma or semigroup with objects, the generating set consists of arrows $(g : u \to v)$ for every pair of objects $u,v$ and every generating element for the magma or semigroup. 

 For a monoid with objects, the generating set consists of two parts. Firstly,
there is a loop at the root object $r$ for each generator of the monoid. Secondly, for each object $u$ distinct from $r$, there are arrows $(1 : r \to u)$ and $(1 : u \to r)$. (Perhaps only one of each pair is required?) Then 
\[ (e : u \to v ) = (1 : u \to r)*(e : r \to r)*(1 : r \to v). \]
 

 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@GeneratorsOfMagmaWithObjects( M78 );|
  [ [m1 : -8 -> -8], [m2 : -8 -> -8], [m3 : -8 -> -8], [m4 : -8 -> -8], 
    [m1 : -8 -> -7], [m2 : -8 -> -7], [m3 : -8 -> -7], [m4 : -8 -> -7], 
    [m1 : -7 -> -8], [m2 : -7 -> -8], [m3 : -7 -> -8], [m4 : -7 -> -8], 
    [m1 : -7 -> -7], [m2 : -7 -> -7], [m3 : -7 -> -7], [m4 : -7 -> -7] ]
  !gapprompt@gap>| !gapinput@genS := GeneratorsOfSemigroupWithObjects( S123 );;|
  !gapprompt@gap>| !gapinput@Length( genS );                                   |
  27
  !gapprompt@gap>| !gapinput@genM := GeneratorsOfMonoidWithObjects( M49 );|
  [ [f1 : -9 -> -9], [f2 : -9 -> -9], [<identity ...> : -9 -> -4], 
    [<identity ...> : -4 -> -9] ]
  !gapprompt@gap>| !gapinput@g1:=genM[2];; g2:=genM[3];; g3:=genM[4];; g4:=genM[5];; |
  !gapprompt@gap>| !gapinput@[g4,g2,g1,g3];|
  [ [<identity ...> : -4 -> -9], [f2 : -9 -> -9], [f1 : -9 -> -9], 
    [<identity ...> : -9 -> -4] ]
  !gapprompt@gap>| !gapinput@g4*g2*g1*g3;|
  [f2*f1 : -4 -> -4]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Structures with more than one piece}}\label{sec-pieces}
\logpage{[ 2, 5, 0 ]}
\hyperdef{L}{X7C7007207FD91BB0}{}
{
  

\subsection{\textcolor{Chapter }{UnionOfPieces (for magmas with objects)}}
\logpage{[ 2, 5, 1 ]}\nobreak
\hyperdef{L}{X781FB06382E08115}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{UnionOfPieces({\mdseries\slshape pieces})\index{UnionOfPieces@\texttt{UnionOfPieces}!for magmas with objects}
\label{UnionOfPieces:for magmas with objects}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Pieces({\mdseries\slshape mwo})\index{Pieces@\texttt{Pieces}!for magmas with objects}
\label{Pieces:for magmas with objects}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PieceOfObject({\mdseries\slshape mwo, obj})\index{PieceOfObject@\texttt{PieceOfObject}}
\label{PieceOfObject}
}\hfill{\scriptsize (operation)}}\\


 A magma with objects whose underlying digraph has two or more connected
components can be constructed by taking the union of two or more connected
structures. These, in turn, can be combined together. The only requirement is
that all the object lists should be disjoint. The pieces are ordered by the
order of their root objects. 

 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@N1 := UnionOfPieces( [ M78, S123 ] ); |
  magma with objects having 2 pieces :-
  1: M78
  2: semigroup with objects :-
      magma = sgp<t,s,r>
    objects = [ -3, -2, -1 ]
  !gapprompt@gap>| !gapinput@ObjectList( N1 ); |
  [ -8, -7, -3, -2, -1 ]
  !gapprompt@gap>| !gapinput@Pieces(N1);|
  [ M78, semigroup with objects :-
          magma = sgp<t,s,r>
        objects = [ -3, -2, -1 ]
       ]
  !gapprompt@gap>| !gapinput@PieceOfObject( N1, -7 ); |
  M78
  !gapprompt@gap>| !gapinput@N2 := UnionOfPieces( [ M49, S0 ] );  |
  semigroup with objects having 2 pieces :-
  1: monoid with objects :-
      magma = Monoid( [ f1, f2 ] )
    objects = [ -9, -4 ]
  2: semigroup with objects :-
      magma = sgp<t,s,r>
    objects = [ 0 ]
  !gapprompt@gap>| !gapinput@ObjectList( N2 ); |
  [ -9, -4, 0 ]
  !gapprompt@gap>| !gapinput@N3 := UnionOfPieces( [ N1, N2] );  |
  magma with objects having 4 pieces :-
  1: monoid with objects :-
      magma = Monoid( [ f1, f2 ] )
    objects = [ -9, -4 ]
  2: M78
  3: semigroup with objects :-
      magma = sgp<t,s,r>
    objects = [ -3, -2, -1 ]
  4: semigroup with objects :-
      magma = sgp<t,s,r>
    objects = [ 0 ]
  !gapprompt@gap>| !gapinput@ObjectList( N3 ); |
  [ -9, -8, -7, -4, -3, -2, -1, 0 ]
  !gapprompt@gap>| !gapinput@Length( GeneratorsOfMagmaWithObjects( N3 ) ); |
  50
  !gapprompt@gap>| !gapinput@## the next command returns fail since the object sets are not disjoint: |
  !gapprompt@gap>| !gapinput@N4 := UnionOfPieces( [ S123, MagmaWithSingleObject( sgp, -2 ) ] );  |
  fail
  
\end{Verbatim}
 }

 }

  
\chapter{\textcolor{Chapter }{Mappings of many\texttt{\symbol{45}}object structures}}\label{chap-homwo}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X78FC7902804CED8E}{}
{
  A \emph{homomorphism} $f$ from a magma with objects $M$ to a magma with objects $N$ consists of 
\begin{itemize}
\item  a map $f_O$ from the objects of $M$ to those of $N$, 
\item  a map $f_A$ from the arrows of $M$ to those of $N$. 
\end{itemize}
 The map $f_A$ is required to be compatible with the tail and head maps and to preserve
multiplication: 
\[ f_A(a : u \to v) * f_A(b : v \to w) ~=~ f_A(a*b : u \to w) \]
 with tail $f_O(u)$ and head $f_O(w)$. 

 When the underlying magma of $M$ is a monoid or group, the map $f_A$ is required to preserve identities and inverses. 

 
\section{\textcolor{Chapter }{Homomorphisms of magmas with objects}}\label{sec-mwohom}
\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X82F856A086B93832}{}
{
  

\subsection{\textcolor{Chapter }{MagmaWithObjectsHomomorphism}}
\logpage{[ 3, 1, 1 ]}\nobreak
\hyperdef{L}{X86E00FEA7FF38FEA}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{MagmaWithObjectsHomomorphism({\mdseries\slshape args})\index{MagmaWithObjectsHomomorphism@\texttt{MagmaWithObjectsHomomorphism}}
\label{MagmaWithObjectsHomomorphism}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HomomorphismFromSinglePiece({\mdseries\slshape src, rng, hom, imobs})\index{HomomorphismFromSinglePiece@\texttt{HomomorphismFromSinglePiece}}
\label{HomomorphismFromSinglePiece}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HomomorphismToSinglePiece({\mdseries\slshape src, rng, images})\index{HomomorphismToSinglePiece@\texttt{HomomorphismToSinglePiece}!for magmas with objects}
\label{HomomorphismToSinglePiece:for magmas with objects}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{MappingToSinglePieceData({\mdseries\slshape mwohom})\index{MappingToSinglePieceData@\texttt{MappingToSinglePieceData}!for magmas with objects}
\label{MappingToSinglePieceData:for magmas with objects}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PiecesOfMapping({\mdseries\slshape mwohom})\index{PiecesOfMapping@\texttt{PiecesOfMapping}}
\label{PiecesOfMapping}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsomorphismNewObjects({\mdseries\slshape src, objlist})\index{IsomorphismNewObjects@\texttt{IsomorphismNewObjects}!for magmas with objects}
\label{IsomorphismNewObjects:for magmas with objects}
}\hfill{\scriptsize (operation)}}\\


 There are a variety of homomorphism constructors. 

 The simplest construction gives a homomorphism $M \to N$ with both $M$ and $N$ connected. It is implemented as \index{IsMappingToSinglePieceRep@\texttt{IsMappingToSinglePieceRep}} \texttt{IsMappingToSinglePieceRep} with attributes \index{Source@\texttt{Source}} \texttt{Source}, \index{Range@\texttt{Range}} \texttt{Range} and \texttt{MappingToSinglePieceData}. The operation requires the following information: 
\begin{itemize}
\item  a magma homomorphism \texttt{hom} from the underlying magma of $M$ to the underlying magma of $N$, 
\item  a list \texttt{imobs} of the images of the objects of $M$. 
\end{itemize}
 In the first example we construct endomappings of \texttt{m} and \texttt{M78}. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@tup1 := [ DirectProductElement([m1,m2]), DirectProductElement([m2,m1]), |
  !gapprompt@>| !gapinput@             DirectProductElement([m3,m4]), DirectProductElement([m4,m3]) ];; |
  !gapprompt@gap>| !gapinput@f1 := GeneralMappingByElements( m, m, tup1 ); |
  <general mapping: m -> m >
  !gapprompt@gap>| !gapinput@IsMagmaHomomorphism( f1 ); |
  true
  !gapprompt@gap>| !gapinput@hom1 := MagmaWithObjectsHomomorphism( M78, M78, f1, [-7,-8] ); |
  magma with objects homomorphism : M78 -> M78
  [ [ <mapping: m -> m >, [ -7, -8 ] ] ]
  !gapprompt@gap>| !gapinput@[ Source( hom1 ), Range( hom1 ) ]; |
  [ M78, M78 ]
  !gapprompt@gap>| !gapinput@b87;|
  [m4 : -8 -> -7]
  !gapprompt@gap>| !gapinput@im1 := ImageElm( hom1, b87 );|
  [m3 : -7 -> -8]
  !gapprompt@gap>| !gapinput@i65 := IsomorphismNewObjects( M78, [-6,-5] ); |
  magma with objects homomorphism : [ [ IdentityMapping( m ), [ -6, -5 ] ] ]
  !gapprompt@gap>| !gapinput@ib87 := ImageElm( i65, b87 );|
  [m4 : -6 -> -5]
  !gapprompt@gap>| !gapinput@M65 := Range( i65);; |
  !gapprompt@gap>| !gapinput@SetName( M65, "M65" ); |
  !gapprompt@gap>| !gapinput@j65 := InverseGeneralMapping( i65 );; |
  !gapprompt@gap>| !gapinput@ImagesOfObjects( j65 ); |
  [ -8, -7 ]
  !gapprompt@gap>| !gapinput@comp := j65 * hom1;|
  magma with objects homomorphism : M65 -> M78
  [ [ <mapping: m -> m >, [ -7, -8 ] ] ]
  !gapprompt@gap>| !gapinput@ImageElm( comp, ib87 );|
  [m3 : -7 -> -8]
  
\end{Verbatim}
 A homomorphism \emph{to} a connected magma with objects may have a source with several pieces, and so
is a union of homomorphisms \emph{from} single pieces. 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@M4 := UnionOfPieces( [ M78, M65 ] );;|
  !gapprompt@gap>| !gapinput@images := [ MappingToSinglePieceData( hom1 )[1], |
  !gapprompt@>| !gapinput@MappingToSinglePieceData( j65 )[1] ]; |
  [ [ <mapping: m -> m >, [ -7, -8 ] ], [ IdentityMapping( m ), [ -8, -7 ] ] ]
  !gapprompt@gap>| !gapinput@map4 := HomomorphismToSinglePiece( M4, M78, images ); |
  magma with objects homomorphism : 
  [ [ <mapping: m -> m >, [ -7, -8 ] ], [ IdentityMapping( m ), [ -8, -7 ] ] ]
  !gapprompt@gap>| !gapinput@ImageElm( map4, b87 ); |
  [m3 : -7 -> -8]
  !gapprompt@gap>| !gapinput@ImageElm( map4, ib87 );|
  [m4 : -8 -> -7]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Homomorphisms of semigroups and monoids with objects}}\label{sec-sgphom}
\logpage{[ 3, 2, 0 ]}
\hyperdef{L}{X7C4D1AEE80D41A35}{}
{
  The next example exhibits a homomorphism between transformation semigroups
with objects. 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@t2 := Transformation( [2,2,4,1] );; |
  !gapprompt@gap>| !gapinput@s2 := Transformation( [1,1,4,4] );;|
  !gapprompt@gap>| !gapinput@r2 := Transformation( [4,1,3,3] );; |
  !gapprompt@gap>| !gapinput@sgp2 := Semigroup( [ t2, s2, r2 ] );;|
  !gapprompt@gap>| !gapinput@SetName( sgp2, "sgp<t2,s2,r2>" );|
  !gapprompt@gap>| !gapinput@##  apparently no method for transformation semigroups available for: |
  !gapprompt@gap>| !gapinput@##  nat := NaturalHomomorphismByGenerators( sgp, sgp2 );  so we use: |
  !gapprompt@gap>| !gapinput@##  in the function flip below t is a transformation on [1..n] |
  !gapprompt@gap>| !gapinput@flip := function( t ) |
  !gapprompt@>| !gapinput@    local i, j, k, L, L2, n; |
  !gapprompt@>| !gapinput@    n := DegreeOfTransformation( t );  |
  !gapprompt@>| !gapinput@    L := ImageListOfTransformation( t ); |
  !gapprompt@>| !gapinput@    if IsOddInt(n) then n:=n+1; L1:=Concatenation(L,[n]); |
  !gapprompt@>| !gapinput@                   else L1:=L; fi; |
  !gapprompt@>| !gapinput@    L2 := ShallowCopy( L1 );|
  !gapprompt@>| !gapinput@    for i in [1..n] do |
  !gapprompt@>| !gapinput@        if IsOddInt(i) then j:=i+1; else j:=i-1; fi; |
  !gapprompt@>| !gapinput@        k := L1[j]; |
  !gapprompt@>| !gapinput@        if IsOddInt(k) then L2[i]:=k+1; else L2[i]:=k-1; fi; |
  !gapprompt@>| !gapinput@    od; |
  !gapprompt@>| !gapinput@    return( Transformation( L2 ) ); |
  !gapprompt@>| !gapinput@end;; |
  !gapprompt@gap>| !gapinput@smap := MappingByFunction( sgp, sgp2, flip );; |
  !gapprompt@gap>| !gapinput@ok := RespectsMultiplication( smap ); |
  true
  !gapprompt@gap>| !gapinput@[ t, ImageElm( smap, t ) ]; |
  [ Transformation( [ 1, 1, 2, 3 ] ), Transformation( [ 2, 2, 4, 1 ] ) ]
  !gapprompt@gap>| !gapinput@[ s, ImageElm( smap, s ) ]; |
  [ Transformation( [ 2, 2, 3, 3 ] ), Transformation( [ 1, 1, 4, 4 ] ) ]
  !gapprompt@gap>| !gapinput@[ r, ImageElm( smap, r ) ]; |
  [ Transformation( [ 2, 3, 4, 4 ] ), Transformation( [ 4, 1, 3, 3 ] ) ]
  !gapprompt@gap>| !gapinput@SetName( smap, "smap" ); |
  !gapprompt@gap>| !gapinput@T123 := SemigroupWithObjects( sgp2, [-13,-12,-11] );; |
  !gapprompt@gap>| !gapinput@shom := MagmaWithObjectsHomomorphism( S123, T123, smap, [-11,-12,-13] );; |
  !gapprompt@gap>| !gapinput@it12 := ImageElm( shom, t12 );;  [ t12, it12 ]; |
  [ [Transformation( [ 1, 1, 2, 3 ] ) : -1 -> -2], 
    [Transformation( [ 2, 2, 4, 1 ] ) : -13 -> -12] ]
  !gapprompt@gap>| !gapinput@is23 := ImageElm( shom, s23 );;  [ s23, is23 ]; |
  [ [Transformation( [ 2, 2, 3, 3 ] ) : -2 -> -3], 
    [Transformation( [ 1, 1, 4, 4 ] ) : -12 -> -11] ]
  !gapprompt@gap>| !gapinput@ir31 := ImageElm( shom, r31 );;  [ r31, ir31 ]; |
  [ [Transformation( [ 2, 3, 4, 4 ] ) : -3 -> -1], 
    [Transformation( [ 4, 1, 3, 3 ] ) : -11 -> -13] ]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Homomorphisms to more than one piece}}\label{sec-hompieces}
\logpage{[ 3, 3, 0 ]}
\hyperdef{L}{X795C8DE37AED7B44}{}
{
  

\subsection{\textcolor{Chapter }{HomomorphismByUnion (for magmas with objects)}}
\logpage{[ 3, 3, 1 ]}\nobreak
\hyperdef{L}{X7AE44D9485EB50F1}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HomomorphismByUnion({\mdseries\slshape src, rng, homs})\index{HomomorphismByUnion@\texttt{HomomorphismByUnion}!for magmas with objects}
\label{HomomorphismByUnion:for magmas with objects}
}\hfill{\scriptsize (operation)}}\\


 When $f : M \to N$ and $N$ has more than one connected component, then $M$ also has more than one component and $f$ is a union of homomorphisms, one for each piece in the range. 

 See section \ref{sec-genhoms} for the equivalent operation with groupoids. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@N4 := UnionOfPieces( [ M78, T123 ] );; |
  !gapprompt@gap>| !gapinput@h14 := HomomorphismByUnionNC( N1, N4, [ hom1, shom ] ); |
  magma with objects homomorphism : 
  [ magma with objects homomorphism : M78 -> M78
      [ [ <mapping: m -> m >, [ -7, -8 ] ] ], magma with objects homomorphism : 
      [ [ smap, [ -11, -12, -13 ] ] ] ]
  !gapprompt@gap>| !gapinput@ImageElm( h14, a78 );|
  [m1 : -8 -> -7]
  !gapprompt@gap>| !gapinput@ImageElm( h14, r31 );|
  [Transformation( [ 4, 1, 3, 3 ] ) : -11 -> -13]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsInjectiveOnObjects}}
\logpage{[ 3, 3, 2 ]}\nobreak
\hyperdef{L}{X7C053B0379DDCE13}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsInjectiveOnObjects({\mdseries\slshape mwohom})\index{IsInjectiveOnObjects@\texttt{IsInjectiveOnObjects}}
\label{IsInjectiveOnObjects}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsSurjectiveOnObjects({\mdseries\slshape mwohom})\index{IsSurjectiveOnObjects@\texttt{IsSurjectiveOnObjects}}
\label{IsSurjectiveOnObjects}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsBijectiveOnObjects({\mdseries\slshape mwohom})\index{IsBijectiveOnObjects@\texttt{IsBijectiveOnObjects}}
\label{IsBijectiveOnObjects}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsEndomorphismWithObjects({\mdseries\slshape mwohom})\index{IsEndomorphismWithObjects@\texttt{IsEndomorphismWithObjects}}
\label{IsEndomorphismWithObjects}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsAutomorphismWithObjects({\mdseries\slshape mwohom})\index{IsAutomorphismWithObjects@\texttt{IsAutomorphismWithObjects}}
\label{IsAutomorphismWithObjects}
}\hfill{\scriptsize (property)}}\\


 The meaning of these five properties is obvious. }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@IsInjectiveOnObjects( h14 );|
  true
  !gapprompt@gap>| !gapinput@IsSurjectiveOnObjects( h14 );|
  true
  !gapprompt@gap>| !gapinput@IsBijectiveOnObjects( h14 ); |
  true
  !gapprompt@gap>| !gapinput@IsEndomorphismWithObjects( h14 ); |
  false
  !gapprompt@gap>| !gapinput@IsAutomorphismWithObjects( h14 ); |
  false
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Mappings defined by a function}}\label{sec-mapbyfun}
\logpage{[ 3, 4, 0 ]}
\hyperdef{L}{X7B9D71BB7BAEFAAA}{}
{
  

\subsection{\textcolor{Chapter }{MappingWithObjectsByFunction}}
\logpage{[ 3, 4, 1 ]}\nobreak
\hyperdef{L}{X81B64F9A855D265F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{MappingWithObjectsByFunction({\mdseries\slshape src, rng, fun, imobs})\index{MappingWithObjectsByFunction@\texttt{MappingWithObjectsByFunction}}
\label{MappingWithObjectsByFunction}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsMappingWithObjectsByFunction({\mdseries\slshape map})\index{IsMappingWithObjectsByFunction@\texttt{IsMappingWithObjectsByFunction}}
\label{IsMappingWithObjectsByFunction}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{UnderlyingFunction({\mdseries\slshape map})\index{UnderlyingFunction@\texttt{UnderlyingFunction}}
\label{UnderlyingFunction}
}\hfill{\scriptsize (attribute)}}\\


 More general mappings, which need not preserve multiplication, are available
using this operation. See chapter \ref{chap-gpdaut} for an application. }

 
\begin{Verbatim}[commandchars=@|C,fontsize=\small,frame=single,label=Example]
  
  @gapprompt|gap>C @gapinput|swap := function(a) return Arrow(M78,a![1],a![3],a![2]); end;      C
  function( a ) ... end
  @gapprompt|gap>C @gapinput|swapmap := MappingWithObjectsByFunction( M78, M78, swap, [-7,-8] );C
  magma with objects mapping by function : M78 -> M78
  function: function ( a )
      return Arrow( M78, a![1], a![3], a![2] );
  end
  
  @gapprompt|gap>C @gapinput|a78; ImageElm( swapmap, a78 );              C
  [m2 : -7 -> -8]
  [m2 : -8 -> -7]
  
\end{Verbatim}
 }

 }

  
\chapter{\textcolor{Chapter }{Groupoids}}\label{chap-gpd}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X82F6A1AB798648F4}{}
{
  A \emph{groupoid} is a (mathematical) category in which every element is invertible. It consists
of a set of \emph{pieces}, each of which is a connected groupoid. The usual terminology is `connected
component', but in \textsf{GAP} `component' is used for `record component', so we use the term \emph{single piece}. 

 The simplest form for a \emph{single piece groupoid} is the direct product of a group and a complete digraph, and so is determined
by a set of \emph{objects} \texttt{obs} $= \Omega$ (the least of which is the \emph{root object}), and a \emph{root group} \texttt{grp} $= G$. Then the elements of the groupoid are \emph{arrows} $(g : o_1 \to o_2)$, stored as triples \texttt{[g,o1,o2]}, where $g \in G$ and $o_1,o_2 \in \Omega$. The objects will generally be chosen to be consecutive negative integers,
but any suitable ordered set is acceptable, and `consecutive' is not a
requirement. The root group will usually be taken to be a permutation group,
but pc\texttt{\symbol{45}}groups, fp\texttt{\symbol{45}}groups and matrix
groups are also supported. 

 A \emph{group} may be considered as a single piece groupoid with one object. 

 A \emph{groupoid} is a set of one or more single piece groupoids, its \emph{pieces}, and is represented as \texttt{IsGroupoidRep}, with attribute \texttt{PiecesOfGroupoid}. 

 The underlying digraph of a single piece groupoid is a regular, complete
digraph on the object set $\Omega$ with $|G|$ arrows from any one object to any other object. It will be convenient to
specify a set of \emph{rays} \index{rays@} consisting of $|\Omega|$ arrows $(r_i : o_1 \to o_i)$, where $o_1$ is the root object and $r_1$ is the identity in $G$. In the simplest examples all the $r_i$ will be identity elements, but other rays are useful when forming subgroupoids
(see \texttt{SubgroupoidWithRays} (\ref{SubgroupoidWithRays})). 

 A groupoid is \emph{homogeneous} if it has two of more isomorphic pieces, with identical groups. The special
case of \emph{homogeneous, discrete} groupoids, where each piece has a single object, is given its own
representation. These are used in the \textsf{XMod} package as the source of a crossed modules of groupoids. 

 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 properties and attributes}}\label{sec-gpds}
\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X7AC321DC7E3C6167}{}
{
  

\subsection{\textcolor{Chapter }{SinglePieceGroupoid}}
\logpage{[ 4, 1, 1 ]}\nobreak
\hyperdef{L}{X8406913B7ED86CFE}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SinglePieceGroupoid({\mdseries\slshape grp, obs})\index{SinglePieceGroupoid@\texttt{SinglePieceGroupoid}}
\label{SinglePieceGroupoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Groupoid({\mdseries\slshape args})\index{Groupoid@\texttt{Groupoid}}
\label{Groupoid}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{MagmaWithSingleObject({\mdseries\slshape gp, obj})\index{MagmaWithSingleObject@\texttt{MagmaWithSingleObject}!for groups}
\label{MagmaWithSingleObject:for groups}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGroupoid({\mdseries\slshape mwo})\index{IsGroupoid@\texttt{IsGroupoid}}
\label{IsGroupoid}
}\hfill{\scriptsize (Category)}}\\


 The simplest construction of a groupoid is as the direct product of a group
and a complete digraph. Such a groupoid will be called a \index{standard groupoid@standard groupoid} \emph{standard groupoid}. Many subgroupoids of such a groupoid do not have this simple form, and will
be considered in section \ref{sec-subgpds}. The global function \texttt{Groupoid} will normally find the appropriate constructor to call, the options being: 
\begin{itemize}
\item  the object group and a set of objects; 
\item  a group being converted to a groupoid and a single object; 
\item  a list of groupoids which have already been constructed (see \ref{sec-union-gpds}). 
\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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@a4 := Group( (1,2,3), (2,3,4) );; |
  !gapprompt@gap>| !gapinput@d8 := Group( (5,6,7,8), (5,7) );;|
  !gapprompt@gap>| !gapinput@SetName( a4, "a4" );  SetName( d8, "d8" ); |
  !gapprompt@gap>| !gapinput@Ga4 := SinglePieceGroupoid( a4, [-15 .. -11] ); |
  single piece groupoid: < a4, [ -15 .. -11 ] >
  !gapprompt@gap>| !gapinput@Gd8 := Groupoid( d8, [-9,-8,-7] );|
  single piece groupoid: < d8, [ -9, -8, -7 ] >
  !gapprompt@gap>| !gapinput@c6 := Group( (11,12,13)(14,15) );;|
  !gapprompt@gap>| !gapinput@SetName( c6, "c6" );|
  !gapprompt@gap>| !gapinput@Gc6 := MagmaWithSingleObject( c6, -10 );|
  single piece groupoid: < c6, [ -10 ] >
  !gapprompt@gap>| !gapinput@IsGroupoid( Gc6 ); |
  true
  !gapprompt@gap>| !gapinput@SetName( Ga4, "Ga4" );  SetName( Gd8, "Gd8" );  SetName( Gc6, "Gc6" );  |
  
\end{Verbatim}
 More operations for constructing groupoids are described in the following
subsections: 
\begin{itemize}
\item  Homogeneous groupoids (see \ref{sec-homogeneous}); 
\item  Direct products of groupoids (see \ref{sec-directprod}); 
\item  A variety of subgroupoid constructions in section \ref{sec-subgpds}; 
\item  Groupoids formed using group isomorphisms in section \ref{sec-gpd-isos}; 
\item  Groupoids whose objects form a monoid in section \ref{sec-mon-gpd}. 
\end{itemize}
 

\subsection{\textcolor{Chapter }{ObjectList (for groupoids)}}
\logpage{[ 4, 1, 2 ]}\nobreak
\hyperdef{L}{X813B084184AAA890}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ObjectList({\mdseries\slshape gpd})\index{ObjectList@\texttt{ObjectList}!for groupoids}
\label{ObjectList:for groupoids}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RootObject({\mdseries\slshape gpd})\index{RootObject@\texttt{RootObject}!for groupoids}
\label{RootObject:for groupoids}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RootGroup({\mdseries\slshape gpd})\index{RootGroup@\texttt{RootGroup}}
\label{RootGroup}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ObjectGroup({\mdseries\slshape gpd, obj})\index{ObjectGroup@\texttt{ObjectGroup}}
\label{ObjectGroup}
}\hfill{\scriptsize (operation)}}\\


 The \texttt{ObjectList} of a groupoid is the sorted list of its objects. The \texttt{RootObject} in a single\texttt{\symbol{45}}piece groupoid is the object with the least
label. A \emph{loop} is an arrow of the form $(g : o \to o)$, and the loops at a particular object $o$ form a group, the \texttt{ObjectGroup} at $o$. The \texttt{RootGroup} is the \texttt{ObjectGroup} at the \texttt{RootObject}. 

 In the example, the groupoids \texttt{Gf2c6} and \texttt{Gabc} illustrate that the objects need not be integers. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ObjectList( Ga4 );|
  [ -15 .. -11 ] 
  !gapprompt@gap>| !gapinput@f2 := FreeGroup(2);;|
  !gapprompt@gap>| !gapinput@Gf2d8 := Groupoid( d8, GeneratorsOfGroup(f2) );|
  single piece groupoid: < d8, [ f1, f2 ] >
  !gapprompt@gap>| !gapinput@Arrow( Gf2d8, (6,8), f2.1, f2.2 );|
  [(6,8) : f1 -> f2]
  !gapprompt@gap>| !gapinput@Gabc := Groupoid( c6, [ "a", "b", "c" ] );|
  single piece groupoid: < c6, [ "a", "b", "c" ] >
  !gapprompt@gap>| !gapinput@Arrow( Gabc, (14,15), "c", "b" );|
  [(14,15) : c -> b]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsPermGroupoid}}
\logpage{[ 4, 1, 3 ]}\nobreak
\hyperdef{L}{X8511D3EE845CC930}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsPermGroupoid({\mdseries\slshape gpd})\index{IsPermGroupoid@\texttt{IsPermGroupoid}}
\label{IsPermGroupoid}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsPcGroupoid({\mdseries\slshape gpd})\index{IsPcGroupoid@\texttt{IsPcGroupoid}}
\label{IsPcGroupoid}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsFpGroupoid({\mdseries\slshape gpd})\index{IsFpGroupoid@\texttt{IsFpGroupoid}}
\label{IsFpGroupoid}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsMatrixGroupoid({\mdseries\slshape gpd})\index{IsMatrixGroupoid@\texttt{IsMatrixGroupoid}}
\label{IsMatrixGroupoid}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsFreeGroupoid({\mdseries\slshape gpd})\index{IsFreeGroupoid@\texttt{IsFreeGroupoid}}
\label{IsFreeGroupoid}
}\hfill{\scriptsize (property)}}\\


 A groupoid is a permutation groupoid if all its pieces have permutation root
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\texttt{\symbol{45}}groupoid and also a free groupoid, \texttt{Gq8} is a pc\texttt{\symbol{45}}groupoid, and \texttt{Gsl43} is a matrix groupoid. See section \ref{sec-mxreps} for matrix representations of groupoids. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@f2 := FreeGroup( 2 );;|
  !gapprompt@gap>| !gapinput@Gf2 := Groupoid( f2, -20 );;|
  !gapprompt@gap>| !gapinput@SetName( f2, "f2" );  SetName( Gf2, "Gf2" ); |
  !gapprompt@gap>| !gapinput@q8 := QuaternionGroup( 8 );;|
  !gapprompt@gap>| !gapinput@genq8 := GeneratorsOfGroup( q8 );;|
  !gapprompt@gap>| !gapinput@x := genq8[1];;  y := genq8[2];;|
  !gapprompt@gap>| !gapinput@Gq8 := Groupoid( q8, [ -18, -17 ] );;|
  !gapprompt@gap>| !gapinput@SetName( q8, "q8" );  SetName( Gq8, "Gq8" );|
  !gapprompt@gap>| !gapinput@sl43 := SpecialLinearGroup( 4, 3 );;|
  !gapprompt@gap>| !gapinput@Gsl43 := SinglePieceGroupoid( sl43, [-23,-22,-21] );;|
  !gapprompt@gap>| !gapinput@SetName( sl43, "sl43" );  SetName( Gsl43, "Gsl43" );|
  !gapprompt@gap>| !gapinput@[ IsMatrixGroupoid( Gsl43 ), IsFpGroupoid( Gf2 ), IsFreeGroupoid( Gf2 ),|
  !gapprompt@>| !gapinput@     IsPcGroupoid( Gq8 ), IsPermGroupoid( Ga4 ) ]; |
  [ true, true, true, true, true ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{UnionOfPieces (for groupoids)}}
\logpage{[ 4, 1, 4 ]}\nobreak
\label{sec-union-gpds}
\hyperdef{L}{X8681D15C7CA15F87}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{UnionOfPieces({\mdseries\slshape pieces})\index{UnionOfPieces@\texttt{UnionOfPieces}!for groupoids}
\label{UnionOfPieces:for groupoids}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Pieces({\mdseries\slshape gpd})\index{Pieces@\texttt{Pieces}!for groupoids}
\label{Pieces:for groupoids}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Size({\mdseries\slshape gpd})\index{Size@\texttt{Size}}
\label{Size}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ReplaceOnePieceInUnion({\mdseries\slshape U, old{\textunderscore}piece, new{\textunderscore}piece})\index{ReplaceOnePieceInUnion@\texttt{ReplaceOnePieceInUnion}}
\label{ReplaceOnePieceInUnion}
}\hfill{\scriptsize (operation)}}\\


 When a groupoid consists of two or more pieces, we require their object lists
to be disjoint. The operation \texttt{UnionOfPieces} and the attribute \texttt{Pieces}, introduced in section \ref{sec-pieces}, are also used for groupoids. The pieces are sorted by the least object in
their object lists. The \index{ObjectList@\texttt{ObjectList}!for groupoids} \texttt{ObjectList} is the sorted concatenation of the objects in the pieces. 

 The \texttt{Size} of a groupoid is the number of its arrows. For a single piece groupoid, this
is the product of the size of the group with the square of the number of
objects. For a non\texttt{\symbol{45}}connected groupoid, the size is the sum
of the sizes of its pieces. 

 One of the pieces in a groupoid may be replaced by an alternative piece using
the operation \texttt{ReplaceOnePieceInUnion}. The \emph{old{\textunderscore}piece} may be either the \emph{position} of the piece to be replaced, or one of the pieces in \texttt{U}. The objects in the new piece may or may not overlap the objects in the piece
being removed \texttt{\symbol{45}}\texttt{\symbol{45}} we just require that
the object lists in the new union are disjoint. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@U3 := UnionOfPieces( [ Ga4, Gc6, Gd8 ] );;|
  !gapprompt@gap>| !gapinput@Display( U3 );|
  groupoid with 3 pieces:
  < objects: [ -15 .. -11 ]
      group: a4 = <[ (1,2,3), (2,3,4) ]> >
  < objects: [ -10 ]
      group: c6 = <[ (11,12,13)(14,15) ]> >
  < objects: [ -9, -8, -7 ]
      group: d8 = <[ (5,6,7,8), (5,7) ]> >
  !gapprompt@gap>| !gapinput@Pieces( U3 );|
  [ Ga4, Gc6, Gd8 ]
  !gapprompt@gap>| !gapinput@ObjectList( U3 );|
  [ -15, -14, -13, -12, -11, -10, -9, -8, -7 ]
  !gapprompt@gap>| !gapinput@[ Size(Ga4), Size(Gd8), Size(Gc6), Size(U3) ];|
  [ 300, 72, 6, 378 ]
  !gapprompt@gap>| !gapinput@U2 := Groupoid( [ Gf2, Gq8 ] );;|
  !gapprompt@gap>| !gapinput@[ Size(Gf2), Size(Gq8), Size(U2) ];           |
  [ infinity, 32, infinity ]
  !gapprompt@gap>| !gapinput@U5 := UnionOfPieces( [ U3, U2 ] );|
  groupoid with 5 pieces:
  [ Gf2, Gq8, Ga4, Gc6, Gd8 ]
  !gapprompt@gap>| !gapinput@V3 := ReplaceOnePieceInUnion( U3, Gd8, Gq8 ); |
  groupoid with 3 pieces:
  [ Gq8, Ga4, Gc6 ]
  !gapprompt@gap>| !gapinput@ObjectList( V3 );             |
  [ -18, -17, -15, -14, -13, -12, -11, -10 ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{HomogeneousGroupoid}}
\logpage{[ 4, 1, 5 ]}\nobreak
\label{sec-homogeneous}
\hyperdef{L}{X855F318181808814}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HomogeneousGroupoid({\mdseries\slshape gpd, oblist})\index{HomogeneousGroupoid@\texttt{HomogeneousGroupoid}}
\label{HomogeneousGroupoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PieceIsomorphisms({\mdseries\slshape hgpd})\index{PieceIsomorphisms@\texttt{PieceIsomorphisms}}
\label{PieceIsomorphisms}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HomogeneousDiscreteGroupoid({\mdseries\slshape gp, obs})\index{HomogeneousDiscreteGroupoid@\texttt{HomogeneousDiscreteGroupoid}}
\label{HomogeneousDiscreteGroupoid}
}\hfill{\scriptsize (operation)}}\\


 Special functions are provided for the case where a groupoid has more than one
connected component, and when these components are identical except for their
object sets. Such groupoids are said to be \emph{homogeneous}. 

 The operation \texttt{HomogeneousGroupoid} is used when the components each contain more than one object. The arguments
consist of a single piece groupoid \texttt{gpd} and a list of lists of objects \texttt{oblist}, each of whose lists has the same length as the object list \texttt{obs} of \texttt{gpd}. Note that \texttt{gpd} is \emph{not} included as one of the pieces in the output unless \texttt{obs} is included as one of the lists in \texttt{oblist}. 

 The \texttt{PieceIsomorphisms} of a homogeneous groupoid are isomorphisms from the first piece to each of the
others. See Chapter \ref{chap-gpdhom} for details of groupoid isomorphisms. 

 The operation \texttt{HomogeneousDiscreteGroupoid} is used when the components each have a single object. In this case the first
argument is just a group \texttt{\symbol{45}}\texttt{\symbol{45}} the root
group for each component. These groupoids are used in the \textsf{XMod} package as the source of many crossed modules of groupoids. 

 Both types of groupoid have the property \index{IsHomogeneousDomainWithObjects@\texttt{IsHomogeneousDomainWithObjects}} \texttt{IsHomogeneousDomainWithObjects}. In the latter case a separate representation \index{IsHomogeneousDomainWithObjectsRep@\texttt{IsHomogeneousDiscreteGroupoidRep}} \texttt{IsHomogeneousDiscreteGroupoidRep} is used. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@HGd8 := HomogeneousGroupoid( Gd8, |
  !gapprompt@>| !gapinput@               [ [-39,-38,-37], [-36,-35,-34], [-33,-32,-31] ] );|
  homogeneous groupoid with 3 pieces:
  1:  single piece groupoid: < d8, [ -39, -38, -37 ] >
  2:  single piece groupoid: < d8, [ -36, -35, -34 ] >
  3:  single piece groupoid: < d8, [ -33, -32, -31 ] >
  !gapprompt@gap>| !gapinput@Size( HGd8 );   ## 8x3x3 + 8x3x3 + 8x3x3|
  216
  !gapprompt@gap>| !gapinput@PieceIsomorphisms( HGd8 );|
  [ groupoid homomorphism : 
      [ [ [(5,6,7,8) : -39 -> -39], [(5,7) : -39 -> -39], [() : -39 -> -38], 
            [() : -39 -> -37] ], 
        [ [(5,6,7,8) : -36 -> -36], [(5,7) : -36 -> -36], [() : -36 -> -35], 
            [() : -36 -> -34] ] ], groupoid homomorphism : 
      [ [ [(5,6,7,8) : -39 -> -39], [(5,7) : -39 -> -39], [() : -39 -> -38], 
            [() : -39 -> -37] ], 
        [ [(5,6,7,8) : -33 -> -33], [(5,7) : -33 -> -33], [() : -33 -> -32], 
            [() : -33 -> -31] ] ] ]
  !gapprompt@gap>| !gapinput@HDc6 := HomogeneousDiscreteGroupoid( c6, [-27..-24] ); |
  homogeneous, discrete groupoid: < c6, [ -27 .. -24 ] >
  !gapprompt@gap>| !gapinput@Size( HDc6 );   ## 6x4|
  24
  !gapprompt@gap>| !gapinput@RepresentationsOfObject( Gd8 );|
  [ "IsComponentObjectRep", "IsAttributeStoringRep", "IsMWOSinglePieceRep" ]
  !gapprompt@gap>| !gapinput@RepresentationsOfObject( HGd8 );|
  [ "IsComponentObjectRep", "IsAttributeStoringRep", "IsPiecesRep" ]
  !gapprompt@gap>| !gapinput@RepresentationsOfObject( HDc6 );|
  [ "IsComponentObjectRep", "IsAttributeStoringRep", 
    "IsHomogeneousDiscreteGroupoidRep" ]
  !gapprompt@gap>| !gapinput@ktpo := KnownTruePropertiesOfObject( HDc6 );; |
  !gapprompt@gap>| !gapinput@ans := |
  !gapprompt@>| !gapinput@[ "IsDuplicateFree", "IsAssociative", "IsCommutative", |
  !gapprompt@>| !gapinput@  "IsDiscreteDomainWithObjects", "IsHomogeneousDomainWithObjects" ];;|
  !gapprompt@gap>| !gapinput@ForAll( ans, a -> ( a in ktpo ) ); |
  true
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{DirectProductOp}}
\logpage{[ 4, 1, 6 ]}\nobreak
\label{sec-directprod}
\hyperdef{L}{X78E8FE0C7F599F5A}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DirectProductOp({\mdseries\slshape list, gpd})\index{DirectProductOp@\texttt{DirectProductOp}}
\label{DirectProductOp}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Projection({\mdseries\slshape gpd, pos})\index{Projection@\texttt{Projection}!for groupoids}
\label{Projection:for groupoids}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Embedding({\mdseries\slshape gpd, pos})\index{Embedding@\texttt{Embedding}!for groupoids}
\label{Embedding:for groupoids}
}\hfill{\scriptsize (operation)}}\\


 The direct product of groupoids $G,H$ has as root group the direct product of the root groups in $G$ and $H$ and as object list the cartesian product of their object lists. As usual with \texttt{DirectProductOp} the two parameters are a list of groupoids followed by the first entry in the
list. 

 Operations \texttt{Projection} and \texttt{Embedding} are as for direct product of groups. See Chapter \ref{chap-gpdhom} for details of groupoid homomorphisms. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@prod := DirectProductOp( [Gd8,Gc6], Gd8 );|
  single piece groupoid: < Group( [ (1,2,3,4), (1,3), (5,6,7)(8,9) ] ), 
  [ [ -9, -10 ], [ -8, -10 ], [ -7, -10 ] ] >
  !gapprompt@gap>| !gapinput@Embedding( prod, 2 );                        |
  groupoid homomorphism : 
  [ [ [(11,12,13)(14,15) : -10 -> -10] ], 
    [ [(5,6,7)(8,9) : [ -9, -10 ] -> [ -9, -10 ]] ] ]
  !gapprompt@gap>| !gapinput@## note that the first embedding has not yet been created|
  !gapprompt@gap>| !gapinput@DirectProductInfo( prod );|
  rec( embeddings := [ , groupoid homomorphism : 
          [ [ [(11,12,13)(14,15) : -10 -> -10] ], 
            [ [(5,6,7)(8,9) : [ -9, -10 ] -> [ -9, -10 ]] ] ] ], first := Gd8, 
    groupoids := [ Gd8, Gc6 ], groups := [ d8, c6 ], 
    objectlists := [ [ -9, -8, -7 ], [ -10 ] ], projections := [  ] )
  !gapprompt@gap>| !gapinput@Projection( prod, 1 );  |
  groupoid homomorphism : 
  [ [ [(1,2,3,4) : [ -9, -10 ] -> [ -9, -10 ]], 
        [(1,3) : [ -9, -10 ] -> [ -9, -10 ]], 
        [(5,6,7)(8,9) : [ -9, -10 ] -> [ -9, -10 ]], 
        [() : [ -9, -10 ] -> [ -8, -10 ]], [() : [ -9, -10 ] -> [ -7, -10 ]] ], 
    [ [(5,6,7,8) : -9 -> -9], [(5,7) : -9 -> -9], [() : -9 -> -9], 
        [() : -9 -> -8], [() : -9 -> -7] ] ]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Groupoid elements; stars; costars; homsets}}\label{sec-elements}
\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X7F23BE3F85C9BA06}{}
{
  

\subsection{\textcolor{Chapter }{GroupoidElement}}
\logpage{[ 4, 2, 1 ]}\nobreak
\hyperdef{L}{X7D028B3B8385ED07}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupoidElement({\mdseries\slshape gpd, elt, tail, head})\index{GroupoidElement@\texttt{GroupoidElement}}
\label{GroupoidElement}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ElementOfArrow({\mdseries\slshape elt})\index{ElementOfArrow@\texttt{ElementOfArrow}!for groupoids}
\label{ElementOfArrow:for groupoids}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{TailOfArrow({\mdseries\slshape elt})\index{TailOfArrow@\texttt{TailOfArrow}!for groupoids}
\label{TailOfArrow:for groupoids}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HeadOfArrow({\mdseries\slshape elt})\index{HeadOfArrow@\texttt{HeadOfArrow}!for groupoids}
\label{HeadOfArrow:for groupoids}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGroupoidElement({\mdseries\slshape arrow})\index{IsGroupoidElement@\texttt{IsGroupoidElement}}
\label{IsGroupoidElement}
}\hfill{\scriptsize (Category)}}\\


 \index{Arrow@\texttt{Arrow}!for groupoid elements} The operation \texttt{GroupoidElement} is a synonym for the operation \texttt{Arrow}, as described in subsection \ref{man-arrow}. To recapitulate, an arrow \texttt{e} consists of a group element, \texttt{ElementOfArrow(e)}; the tail (source) object, \texttt{TailOfArrow(e)}; and the head (target) object, \texttt{HeadOfArrow(e)}. Arrows have a \emph{partial composition}: two arrows may be multiplied when the head of the first coincides with the
tail of the second. If an attempt is made to multiply arrows where this
condition does not hold, then the value \texttt{fail} is returned. 

 }

 \index{* for groupoid elements} 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@e1 := GroupoidElement( Gd8, (5,6,7,8), -9, -8 );|
  [(5,6,7,8) : -9 -> -8]
  !gapprompt@gap>| !gapinput@e2 := Arrow( Gd8, (5,7), -8, -7 );|
  [(5,7) : -8 -> -7]
  !gapprompt@gap>| !gapinput@Print( [ ElementOfArrow(e1), TailOfArrow(e1), HeadOfArrow(e1) ], "\n" );|
  [ (5,6,7,8), -9, -8 ]
  !gapprompt@gap>| !gapinput@IsGroupoidElement( e1 );|
  true
  !gapprompt@gap>| !gapinput@e1e2 := e1*e2;|
  [(5,6)(7,8) : -9 -> -7]
  !gapprompt@gap>| !gapinput@e2*e1;|
  fail
  !gapprompt@gap>| !gapinput@e3 := Arrow( Gd8, (6,8), -7, -9 );;|
  !gapprompt@gap>| !gapinput@loop := e1e2*e3;|
  [(5,8,7,6) : -9 -> -9]
  !gapprompt@gap>| !gapinput@loop^2;|
  [(5,7)(6,8) : -9 -> -9]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IdentityArrow}}
\logpage{[ 4, 2, 2 ]}\nobreak
\hyperdef{L}{X78C3228682279032}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IdentityArrow({\mdseries\slshape gpd, obj})\index{IdentityArrow@\texttt{IdentityArrow}}
\label{IdentityArrow}
}\hfill{\scriptsize (operation)}}\\


 The identity arrow $1_o$ of $G$ at object $o$ is $(e:o \to o)$ where $e$ is the identity element in the object group. The \index{inverse arrow@inverse arrow} \emph{inverse arrow} $e^{-1}$ of $e = (c : p \to q)$ is $(c^{-1} : q \to p)$, so that $e*e^{-1}=1_p$ and $e^{-1}*e = 1_q$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@i8 := IdentityArrow( Gd8, -8 );|
  [() : -8 -> -8]
  !gapprompt@gap>| !gapinput@[ e1*i8, i8*e1, e1^-1]; |
  [ [(5,6,7,8) : -9 -> -8], fail, [(5,8,7,6) : -8 -> -9] ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{Order}}
\logpage{[ 4, 2, 3 ]}\nobreak
\hyperdef{L}{X84F59A2687C62763}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Order({\mdseries\slshape arr})\index{Order@\texttt{Order}}
\label{Order}
}\hfill{\scriptsize (attribute)}}\\


 A groupoid element is a \index{loop@loop} \emph{loop} when the tail and head coincide. In this case the order of the arrow is
defined to be the order of its group element. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@[ i8, loop ]; |
  [ [() : -8 -> -8], [(5,8,7,6) : -9 -> -9] ]
  !gapprompt@gap>| !gapinput@[ Order( i8 ), Order(loop) ];|
  [ 1, 4 ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{ObjectStar}}
\logpage{[ 4, 2, 4 ]}\nobreak
\hyperdef{L}{X7B561BAE7D471C60}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ObjectStar({\mdseries\slshape gpd, obj})\index{ObjectStar@\texttt{ObjectStar}}
\label{ObjectStar}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ObjectCostar({\mdseries\slshape gpd, obj})\index{ObjectCostar@\texttt{ObjectCostar}}
\label{ObjectCostar}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Homset({\mdseries\slshape gpd, tail, head})\index{Homset@\texttt{Homset}}
\label{Homset}
}\hfill{\scriptsize (operation)}}\\


 \index{star@} \index{costar@} The \emph{star} at \texttt{obj} is the set of arrows which have \texttt{obj} as tail, while the \emph{costar} is the set of arrows which have \texttt{obj} as head. The \emph{homset} from \texttt{obj1} to \texttt{obj2} is the set of arrows with the specified tail and head, and so is bijective
with the elements of the object groups. Indeed, \texttt{Homset(G,o,o)} is the object group at \texttt{o}. Thus every star and every costar is a union of homsets. The identity arrow
at an object is a left identity for the star and a right identity for the
costar at that object. 

 In order not to create unneccessarily 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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@star9 := ObjectStar( Gd8, -9 );|
  <star at -9 with vertex group d8>
  !gapprompt@gap>| !gapinput@Size( star9 ); |
  24
  !gapprompt@gap>| !gapinput@## print the elements in star9 from 19 to 24|
  !gapprompt@gap>| !gapinput@iter := Iterator( star9 );;              |
  !gapprompt@gap>| !gapinput@for i in [1..18] do a := NextIterator( iter ); od; |
  !gapprompt@gap>| !gapinput@for i in [19..24] do Print( i, " : ", NextIterator( iter ), "\n" ); od; |
  19 : [(5,6,7,8) : -9 -> -9]
  20 : [(5,6,7,8) : -9 -> -8]
  21 : [(5,6,7,8) : -9 -> -7]
  22 : [(5,6)(7,8) : -9 -> -9]
  23 : [(5,6)(7,8) : -9 -> -8]
  24 : [(5,6)(7,8) : -9 -> -7]
  !gapprompt@gap>| !gapinput@costar12 := ObjectCostar( Ga4, -12 );|
  <costar at -12 with vertex group a4>
  !gapprompt@gap>| !gapinput@Size( costar12 );|
  60
  !gapprompt@gap>| !gapinput@Elements( q8 );|
  [ <identity> of ..., x, y, y2, x*y, x*y2, y*y2, x*y*y2 ]
  !gapprompt@gap>| !gapinput@hsetq8 := Homset( Gq8, -18, -17 );|
  <homset -18 -> -17 with head group q8>
  !gapprompt@gap>| !gapinput@Perform( hsetq8, Display );|
  [<identity> of ... : -18 -> -17]
  [x : -18 -> -17]
  [y : -18 -> -17]
  [y2 : -18 -> -17]
  [x*y : -18 -> -17]
  [x*y2 : -18 -> -17]
  [y*y2 : -18 -> -17]
  [x*y*y2 : -18 -> -17]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Subgroupoids}}\label{sec-subgpds}
\logpage{[ 4, 3, 0 ]}
\hyperdef{L}{X7BDBA72C852C4625}{}
{
  

\subsection{\textcolor{Chapter }{Subgroupoid}}
\logpage{[ 4, 3, 1 ]}\nobreak
\hyperdef{L}{X80780D287EDDB7BB}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Subgroupoid({\mdseries\slshape args})\index{Subgroupoid@\texttt{Subgroupoid}}
\label{Subgroupoid}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsSubgroupoid({\mdseries\slshape gpd, sgpd})\index{IsSubgroupoid@\texttt{IsSubgroupoid}}
\label{IsSubgroupoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsWideSubgroupoid({\mdseries\slshape gpd, sgpd})\index{IsWideSubgroupoid@\texttt{IsWideSubgroupoid}}
\label{IsWideSubgroupoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsFullSubgroupoid({\mdseries\slshape gpd, sgpd})\index{IsFullSubgroupoid@\texttt{IsFullSubgroupoid}}
\label{IsFullSubgroupoid}
}\hfill{\scriptsize (operation)}}\\


 Let $S$ be a \emph{subgroupoid} of a groupoid $G$. Then the object set of $S$ is a subset of the objects of $G$, and the object groups are subgroups of the object groups in $G$. $S$ is \emph{wide} in $G$ if both groupoids have the same object set. \texttt{S} is \emph{full} if, for any two of its objects, the \texttt{Homset} is the same as that in $G$. The arrows of $S$ form a subset of those of $G$, closed under multiplication and with tails and heads in the chosen object
set. 

 There are a variety of constructors for a subgroupoid of a standard groupoid,
as described in the following sections. The global function \texttt{Subgroupoid} should call the operation appropriate to the parameters provided. 

 }

 

\subsection{\textcolor{Chapter }{SubgroupoidByObjects}}
\logpage{[ 4, 3, 2 ]}\nobreak
\label{sec-subgpd-obs}
\hyperdef{L}{X8600FA7B8051C9AC}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SubgroupoidByObjects({\mdseries\slshape gpd, obs})\index{SubgroupoidByObjects@\texttt{SubgroupoidByObjects}}
\label{SubgroupoidByObjects}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SubgroupoidBySubgroup({\mdseries\slshape gpd, sgp})\index{SubgroupoidBySubgroup@\texttt{SubgroupoidBySubgroup}}
\label{SubgroupoidBySubgroup}
}\hfill{\scriptsize (attribute)}}\\


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

 The \texttt{SubgroupoidBySubgroup} of a connected groupoid \texttt{gpd} determinded by a subgroup \texttt{sgp} of the root group is the wide subgroupoid with root group \texttt{sgp} and containing the rays of \texttt{gpd}. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Ha4 := SubgroupoidByObjects( Ga4, [-14,-13,-12] );  |
  single piece groupoid: < a4, [ -14, -13, -12 ] >
  !gapprompt@gap>| !gapinput@SetName( Ha4, "Ha4" );|
  !gapprompt@gap>| !gapinput@IsSubgroupoid( Ga4, Ha4 );|
  true
  !gapprompt@gap>| !gapinput@c3a := Subgroup( a4, [ (1,2,3) ] );; |
  !gapprompt@gap>| !gapinput@SetName( c3a, "c3a" );|
  !gapprompt@gap>| !gapinput@Hc3a := SubgroupoidBySubgroup( Ha4, c3a );|
  single piece groupoid: < c3a, [ -14, -13, -12 ] >
  !gapprompt@gap>| !gapinput@[ IsWideSubgroupoid( Ga4, Ha4 ), IsWideSubgroupoid( Ha4, Hc3a ) ];|
  [ false, true ]
  !gapprompt@gap>| !gapinput@[ IsFullSubgroupoid( Ga4, Ha4 ), IsFullSubgroupoid( Ha4, Hc3a ) ];|
  [ true, false ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{SubgroupoidWithRays}}
\logpage{[ 4, 3, 3 ]}\nobreak
\label{sec=subgpd-rays}
\hyperdef{L}{X873E0914871858E8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SubgroupoidWithRays({\mdseries\slshape gpd, sgp, rays})\index{SubgroupoidWithRays@\texttt{SubgroupoidWithRays}}
\label{SubgroupoidWithRays}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RaysOfGroupoid({\mdseries\slshape gpd})\index{RaysOfGroupoid@\texttt{RaysOfGroupoid}}
\label{RaysOfGroupoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RayArrowsOfGroupoid({\mdseries\slshape gpd})\index{RayArrowsOfGroupoid@\texttt{RayArrowsOfGroupoid}}
\label{RayArrowsOfGroupoid}
}\hfill{\scriptsize (operation)}}\\


 If groupoid $G$ is of type \texttt{IsDirectProductWithCompleteDigraph} with group $g$ and $n$ objects, then a typical wide subgroupoid $H$ of $G$ is formed by choosing a subgroup $h$ of $g$ to be the object group at the root object $q$, and an arrow $r : q \to p$ for each of the objects $p$. The chosen loop arrow at $q$ must be the identity arrow. These $n$ arrows are called the \emph{ray arrows} of the subgroupoid. The arrows in the homset from $p$ to $p'$ have the form $r^{-1}xr'$ where $r,r'$ are the rays from $q$ to $p,p'$ respectively, and $x \in h$. 

 The operation \texttt{RayArrowsOfGroupoid} returns a list of arrows, one for each object, while the operation \texttt{RaysOfGroupoid} returns the list of group elements in these arrows. 

 Note that it is also possible to construct a subgroupoid with rays of a
subgroupoid with rays. 

 In the following example we construct a subgroupoid \texttt{Gk4} of the groupoid \texttt{Ga4}, and then a second subgroupoid \texttt{Gc2}. The initial standard groupoid \texttt{Ga4} is set as the parent for both \texttt{Gk4} and \texttt{Gc2}. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@k4 := Subgroup( a4, [ (1,2)(3,4), (1,3)(2,4) ] );;|
  !gapprompt@gap>| !gapinput@SetName( k4, "k4" );|
  !gapprompt@gap>| !gapinput@Gk4 := SubgroupoidWithRays( Ga4, k4, |
  !gapprompt@>| !gapinput@              [ (), (1,2,3), (1,2,4), (1,3,4), (2,3,4) ] );|
  single piece groupoid with rays: < k4, [ -15 .. -11 ], 
  [ (), (1,2,3), (1,2,4), (1,3,4), (2,3,4) ] >
  !gapprompt@gap>| !gapinput@SetName( Gk4, "Gk4" );|
  !gapprompt@gap>| !gapinput@RaysOfGroupoid( Gk4 );       |
  [ (), (1,2,3), (1,2,4), (1,3,4), (2,3,4) ]
  !gapprompt@gap>| !gapinput@RayArrowsOfGroupoid( Gk4 );  |
  [ [() : -15 -> -15], [(1,2,3) : -15 -> -14], [(1,2,4) : -15 -> -13],
    [(1,3,4) : -15 -> -12], [(2,3,4) : -15 -> -11] ]
  !gapprompt@gap>| !gapinput@IsDirectProductWithCompleteDigraph( Gk4 );|
  false
  !gapprompt@gap>| !gapinput@ObjectGroup( Gk4, -14 );|
  Group([ (1,4)(2,3), (1,2)(3,4) ])
  !gapprompt@gap>| !gapinput@c2 := Subgroup( k4, [ (1,4)(2,3) ] );;  SetName( c2, "c2" );|
  !gapprompt@gap>| !gapinput@Gc2 := Subgroupoid( Gk4, c2, [ (), (1,3,4), (1,4,3), (1,2,3), (1,3,2) ] );|
  single piece groupoid with rays: < c2, [ -15 .. -11 ], 
  [ (), (1,3,4), (1,4,3), (1,2,3), (1,3,2) ] >
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{SubgroupoidByPieces}}
\logpage{[ 4, 3, 4 ]}\nobreak
\label{sec-subgpd-pieces}
\hyperdef{L}{X7AEA9BF780CD6957}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SubgroupoidByPieces({\mdseries\slshape gpd, pieces})\index{SubgroupoidByPieces@\texttt{SubgroupoidByPieces}}
\label{SubgroupoidByPieces}
}\hfill{\scriptsize (operation)}}\\


 The most general way to construct a subgroupoid is to use the operation \texttt{SubgroupoidByPieces}. Its two parameters are a groupoid and a list of \emph{pieces}, each piece being specified either as a list \texttt{[sgp,obs]}, where \texttt{sgp} is a subgroup of the root group in that piece, and \texttt{obs} is a subset of the objects in that piece, or as a list \texttt{[sgp,obs,rays]} when a set of rays is required. In the example both types of piece are used. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Display( Ga4 );|
  perm single piece groupoid: Ga4
    objects: [ -15 .. -11 ]
      group: a4 = <[ (1,2,3), (2,3,4) ]>
  !gapprompt@gap>| !gapinput@c3b := Subgroup( a4, [ (1,2,4) ] );;|
  !gapprompt@gap>| !gapinput@SetName( c3b, "c3b" );|
  !gapprompt@gap>| !gapinput@pieces := [ [ c3a, [-14] ], [ c3b, [-13,-12], [(),(1,4)(2,3)] ] ];;|
  !gapprompt@gap>| !gapinput@Jc3 := Subgroupoid( Ha4, pieces );;|
  !gapprompt@gap>| !gapinput@SetName( Jc3, "Jc3" );|
  !gapprompt@gap>| !gapinput@Display( Jc3 );|
  groupoid with 2 pieces:
  < objects: [ -14 ]
      group: c3a = <[ (1,2,3) ]> >
  <     objects: [ -13, -12 ]
     parent gpd: single piece groupoid: < a4, [ -13, -12 ] >
     root group: c3b = <[ (1,2,4) ]>
           rays: [ (), (1,4)(2,3) ]
  !gapprompt@gap>| !gapinput@[ Parent( Jc3 ), IsWideSubgroupoid( Ha4, Jc3 ) ]; |
  [ Ga4, true ]
  !gapprompt@gap>| !gapinput@pJc3 := Pieces( Jc3 );;|
  !gapprompt@gap>| !gapinput@SetName( pJc3[1], "Jc3a" );  SetName( pJc3[2], "Jc3b" );|
  !gapprompt@gap>| !gapinput@U2;|
  groupoid with 2 pieces:
  [ Gf2, Gq8 ]
  !gapprompt@gap>| !gapinput@genf2b := List( GeneratorsOfGroup(f2), g -> g^2 );|
  [ f1^2, f2^2 ]
  !gapprompt@gap>| !gapinput@f2b := Subgroup( f2, genf2b );;|
  !gapprompt@gap>| !gapinput@JU2 := SubgroupoidByPieces( U2, [ [f2b,[-20]], [q8,[-17]] ] );|
  groupoid with 2 pieces:
  1:  single piece groupoid: < Group( [ f1^2, f2^2 ] ), [ -20 ] >
  2:  single piece groupoid: < q8, [ -17 ] >
  !gapprompt@gap>| !gapinput@[ IsWideSubgroupoid(U2,JU2), IsSubgroupoid(Gf2,Groupoid(f2b,[-20])) ];|
  [ false, true ]
  !gapprompt@gap>| !gapinput@pJU2 := Pieces( JU2 );; |
  !gapprompt@gap>| !gapinput@SetName( pJU2[1], "JU2a" );  SetName( pJU2[2], "JU2b" );|
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{PiecePositions}}
\logpage{[ 4, 3, 5 ]}\nobreak
\label{sec-pieces-pos}
\hyperdef{L}{X78C7A83980BAE937}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PiecePositions({\mdseries\slshape gpd, sgpd})\index{PiecePositions@\texttt{PiecePositions}}
\label{PiecePositions}
}\hfill{\scriptsize (operation)}}\\


 When $G$ is a groupoid with a number of pieces and $H$ is a subgroupid of $G$, it is useful to know for each piece of $H$ the piece of $G$ of which it is a subgroupoid. The inclusion mapping of $H$ in $G$ will be described in subsection \texttt{InclusionMappingGroupoids} (\ref{InclusionMappingGroupoids}). 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@T1 := UnionOfPieces( [Ha4,U2] );;  Pieces( T1 );|
  [ Gf2, Gq8, Ha4 ]
  !gapprompt@gap>| !gapinput@T2 := UnionOfPieces( [Jc3,JU2] );;  Pieces( T2 );|
  [ JU2a, JU2b, Jc3a, Jc3b ]
  !gapprompt@gap>| !gapinput@PiecePositions( T1, T2 );                                               |
  [ 1, 2, 3, 3 ]
  !gapprompt@gap>| !gapinput@InclusionMappingGroupoids( T1, T2 );|
  groupoid homomorphism from several pieces : 
  groupoid homomorphism : JU2a -> Gf2
  [ [ [ [f1^2 : -20 -> -20], [f2^2 : -20 -> -20] ], 
        [ [f1^2 : -20 -> -20], [f2^2 : -20 -> -20] ] ] ]
  groupoid homomorphism : JU2b -> Gq8
  [ [ [ [x : -17 -> -17], [y : -17 -> -17], [y2 : -17 -> -17] ], 
        [ [x : -17 -> -17], [y : -17 -> -17], [y2 : -17 -> -17] ] ] ]
  groupoid homomorphism : 
  [ [ [ [(1,2,3) : -14 -> -14] ], [ [(1,2,3) : -14 -> -14] ] ], 
    [ [ [(1,2,4) : -13 -> -13], [(1,4)(2,3) : -13 -> -12] ], 
        [ [(1,2,4) : -13 -> -13], [(1,4)(2,3) : -13 -> -12] ] ] ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{FullTrivialSubgroupoid}}
\logpage{[ 4, 3, 6 ]}\nobreak
\label{sec-subgpd-triv}
\hyperdef{L}{X7FE8F09A7C8CEC5B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FullTrivialSubgroupoid({\mdseries\slshape gpd})\index{FullTrivialSubgroupoid@\texttt{FullTrivialSubgroupoid}}
\label{FullTrivialSubgroupoid}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DiscreteTrivialSubgroupoid({\mdseries\slshape gpd})\index{DiscreteTrivialSubgroupoid@\texttt{DiscreteTrivialSubgroupoid}}
\label{DiscreteTrivialSubgroupoid}
}\hfill{\scriptsize (attribute)}}\\


 A \index{trivial subgroupoid@trivial subgroupoid} \emph{trivial subgroupoid} has trivial object groups, but need not be discrete. A single piece trivial
groupoid is sometimes called a \index{tree groupoid@tree groupoid} \emph{tree groupoid}. (The term \index{identity subgroupoid@identity subgroupoid} \emph{identity subgroupoid} was used in versions up to 1.14.) In the example \texttt{id(G)} denotes the identity subgroup of $G$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@FullTrivialSubgroupoid( Jc3 );|
  groupoid with 2 pieces:
  1:  single piece groupoid: < id(c3a), [ -14 ] >
  2:  single piece groupoid: < id(c3b), [ -13, -12 ] >
  !gapprompt@gap>| !gapinput@DiscreteTrivialSubgroupoid( Gd8 );|
  homogeneous, discrete groupoid: < id(d8), [ -9, -8, -7 ] >
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{DiscreteSubgroupoid}}
\logpage{[ 4, 3, 7 ]}\nobreak
\label{sec-subgpd-discrete}
\hyperdef{L}{X7ACFBE7D855A82A3}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DiscreteSubgroupoid({\mdseries\slshape gpd, sgps, obs})\index{DiscreteSubgroupoid@\texttt{DiscreteSubgroupoid}}
\label{DiscreteSubgroupoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HomogeneousDiscreteSubgroupoid({\mdseries\slshape gpd, gp, obs})\index{HomogeneousDiscreteSubgroupoid@\texttt{HomogeneousDiscreteSubgroupoid}}
\label{HomogeneousDiscreteSubgroupoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{MaximalDiscreteSubgroupoid({\mdseries\slshape gpd})\index{MaximalDiscreteSubgroupoid@\texttt{MaximalDiscreteSubgroupoid}}
\label{MaximalDiscreteSubgroupoid}
}\hfill{\scriptsize (attribute)}}\\


 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\texttt{\symbol{45}}object full subgroupoids of \texttt{gpd}. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@U3;|
  groupoid with 3 pieces:
  [ Ga4, Gc6, Gd8 ]
  !gapprompt@gap>| !gapinput@c4 := Subgroup( d8, [ (5,6,7,8) ] );;  SetName( c4, "c4" );|
  !gapprompt@gap>| !gapinput@DiscreteSubgroupoid( U3, [ c3a, c3b, c6, c4 ], [-15,-13,-10,-7] );|
  groupoid with 4 pieces:
  1:  single piece groupoid: < c3a, [ -15 ] >
  2:  single piece groupoid: < c3b, [ -13 ] >
  3:  single piece groupoid: < c6, [ -10 ] >
  4:  single piece groupoid: < c4, [ -7 ] >
  !gapprompt@gap>| !gapinput@HomogeneousDiscreteSubgroupoid( Ga4, k4, [-15,-13,-11] ); |
  homogeneous, discrete groupoid: < a4, [ -15, -13, -11 ] >
  !gapprompt@gap>| !gapinput@MaximalDiscreteSubgroupoid( Jc3 );|
  groupoid with 3 pieces:
  1:  single piece groupoid: < c3a, [ -14 ] >
  2:  single piece groupoid: < c3b, [ -13 ] >
  3:  single piece groupoid: < Group( [ (1,4,3) ] ), [ -12 ] >
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{SinglePieceSubgroupoidByGenerators}}
\logpage{[ 4, 3, 8 ]}\nobreak
\label{sec-subgpd-gens}
\hyperdef{L}{X7A9F29BD7D64DCC1}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SinglePieceSubgroupoidByGenerators({\mdseries\slshape parent, gens})\index{SinglePieceSubgroupoidByGenerators@\texttt{SinglePieceSubgroupoidByGenerators}}
\label{SinglePieceSubgroupoidByGenerators}
}\hfill{\scriptsize (operation)}}\\


 A set of arrows generates a groupoid by taking all possible products and
inverses. So far, the only implementation is for the case of loops generating
a group at an object $o$ together with a set of rays from $o$, where $o$ is \emph{not} the least object. A suitably large supergroupoid, which must be a direct
product with a complete digraph, should be provided. This is the case needed
for \texttt{ConjugateGroupoid} in section \ref{subsec-conjgpd}. Other cases will be added as time permits. }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@a1 := Arrow( Gk4, (1,2)(3,4), -15, -15 );;|
  !gapprompt@gap>| !gapinput@a2 := Arrow( Gk4, (1,3,2), -15, -13 );;|
  !gapprompt@gap>| !gapinput@a3 := Arrow( Gk4, (2,3,4), -15, -11 );;|
  !gapprompt@gap>| !gapinput@SinglePieceSubgroupoidByGenerators( Gk4, [a1,a2,a3] );|
  single piece groupoid with rays: < Group( [ (1,2)(3,4) ] ), [ -15, -13, -11  ],
   [ (), (1,3,2), (2,3,4) ] >
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Left, right and double cosets}}\label{sec-cosets}
\logpage{[ 4, 4, 0 ]}
\hyperdef{L}{X831AA9E8780235F2}{}
{
  \index{Cosets (left,right,double)@} \index{double coset@} 

\subsection{\textcolor{Chapter }{RightCoset}}
\logpage{[ 4, 4, 1 ]}\nobreak
\hyperdef{L}{X8412ABD57986B9FC}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RightCoset({\mdseries\slshape G, U, elt})\index{RightCoset@\texttt{RightCoset}}
\label{RightCoset}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RightCosetRepresentatives({\mdseries\slshape G, U})\index{RightCosetRepresentatives@\texttt{RightCosetRepresentatives}}
\label{RightCosetRepresentatives}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RightCosets({\mdseries\slshape G, U})\index{RightCosets@\texttt{RightCosets}}
\label{RightCosets}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LeftCoset({\mdseries\slshape G, U, elt})\index{LeftCoset@\texttt{LeftCoset}}
\label{LeftCoset}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LeftCosetRepresentatives({\mdseries\slshape G, U})\index{LeftCosetRepresentatives@\texttt{LeftCosetRepresentatives}}
\label{LeftCosetRepresentatives}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LeftCosetRepresentativesFromObject({\mdseries\slshape G, U, obj})\index{LeftCosetRepresentativesFromObject@\texttt{LeftCosetRepresentativesFromObject}}
\label{LeftCosetRepresentativesFromObject}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LeftCosets({\mdseries\slshape G, U})\index{LeftCosets@\texttt{LeftCosets}}
\label{LeftCosets}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DoubleCoset({\mdseries\slshape G, U, V, elt})\index{DoubleCoset@\texttt{DoubleCoset}}
\label{DoubleCoset}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DoubleCosetRepresentatives({\mdseries\slshape G, U, V})\index{DoubleCosetRepresentatives@\texttt{DoubleCosetRepresentatives}}
\label{DoubleCosetRepresentatives}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DoubleCosets({\mdseries\slshape G, U, V})\index{DoubleCosets@\texttt{DoubleCosets}}
\label{DoubleCosets}
}\hfill{\scriptsize (operation)}}\\


 If \texttt{U} is a subgroupoid of $G$, the \emph{right cosets} $Ug$ of $U$ in $G$ are the equivalence classes for the relation on the arrows of $G$ where $g1$ is related to $g2$ if and only if $g2 = u*g1$ for some arrow $u$ of $U$. The right coset containing $g$ is written $Ug$. These right cosets partition the costars of $G$ and, in particular, the costar $U1\_{o}$ of $U$ at object $o$. So (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 arrow for each coset where, in a particular piece
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 and right cosets. The operation \texttt{LeftCosetRepresentativesFromObject( G, U, obj )} is used in Chapter \ref{chap-ggraph}, 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 piece, cosets may have differing lengths. 

 In the example the representative for the right coset \texttt{re4} is the seventeenth one in the printed list \texttt{rcra4}, namely \texttt{[():\texttt{\symbol{45}}12\texttt{\symbol{45}}{\textgreater}\texttt{\symbol{45}}12]}. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@e4 := Arrow( Jc3, (2,4,3), -13, -12 );;;                            |
  !gapprompt@gap>| !gapinput@re4 := RightCoset( Ha4, Jc3, e4 );|
  <right coset of Jc3b with representative [(2,4,3) : -13 -> -12]>
  !gapprompt@gap>| !gapinput@Perform( re4, Display );|
  [(2,4,3) : -13 -> -12]
  [(1,3,4) : -12 -> -12]
  [(1,3,2) : -13 -> -12]
  [(1,4,3) : -12 -> -12]
  [(1,4)(2,3) : -13 -> -12]
  [() : -12 -> -12]
  !gapprompt@gap>| !gapinput@rcra4 := RightCosetRepresentatives( Ha4, Jc3 );|
  [ [() : -14 -> -14], [(1,2)(3,4) : -14 -> -14], [(1,3)(2,4) : -14 -> -14], 
    [(1,4)(2,3) : -14 -> -14], [() : -14 -> -13], [(1,2)(3,4) : -14 -> -13], 
    [(1,3)(2,4) : -14 -> -13], [(1,4)(2,3) : -14 -> -13], [() : -14 -> -12], 
    [(1,2)(3,4) : -14 -> -12], [(1,3)(2,4) : -14 -> -12], 
    [(1,4)(2,3) : -14 -> -12], [() : -13 -> -13], [(1,2)(3,4) : -13 -> -13], 
    [(1,3)(2,4) : -13 -> -13], [(1,4)(2,3) : -13 -> -13], [() : -12 -> -12], 
    [(1,2)(3,4) : -12 -> -12], [(1,3)(2,4) : -12 -> -12], 
    [(1,4)(2,3) : -12 -> -12], [() : -13 -> -14], [(1,2)(3,4) : -13 -> -14], 
    [(1,3)(2,4) : -13 -> -14], [(1,4)(2,3) : -13 -> -14] ]
  !gapprompt@gap>| !gapinput@le4 := LeftCoset( Ha4, Jc3, e4 ); |
  <left coset of Jc3b with representative [(1,4,2) : -13 -> -13]>
  !gapprompt@gap>| !gapinput@Perform( le4, Display );|
  [(1,4,2) : -13 -> -13]
  [(2,4,3) : -13 -> -12]
  [() : -13 -> -13]
  [(1,4)(2,3) : -13 -> -12]
  [(1,2,4) : -13 -> -13]
  [(1,3,2) : -13 -> -12]
  !gapprompt@gap>| !gapinput@lcra4 := LeftCosetRepresentatives( Ha4, Jc3 );|
  [ [() : -14 -> -14], [(1,2)(3,4) : -14 -> -14], [(1,3)(2,4) : -14 -> -14], 
    [(1,4)(2,3) : -14 -> -14], [() : -13 -> -14], [(1,2)(3,4) : -13 -> -14], 
    [(1,3)(2,4) : -13 -> -14], [(1,4)(2,3) : -13 -> -14], [() : -12 -> -14], 
    [(1,2)(3,4) : -12 -> -14], [(1,3)(2,4) : -12 -> -14], 
    [(1,4)(2,3) : -12 -> -14], [() : -13 -> -13], [(1,2)(3,4) : -13 -> -13], 
    [(1,3)(2,4) : -13 -> -13], [(1,4)(2,3) : -13 -> -13], [() : -12 -> -12], 
    [(1,2)(3,4) : -12 -> -12], [(1,3)(2,4) : -12 -> -12], 
    [(1,4)(2,3) : -12 -> -12], [() : -14 -> -13], [(1,2)(3,4) : -14 -> -13], 
    [(1,3)(2,4) : -14 -> -13], [(1,4)(2,3) : -14 -> -13] ]
  !gapprompt@gap>| !gapinput@lcr11 := LeftCosetRepresentativesFromObject( Ha4, Jc3, -12 );|
  [ [() : -12 -> -14], [(1,2)(3,4) : -12 -> -14], [(1,3)(2,4) : -12 -> -14], 
    [(1,4)(2,3) : -12 -> -14], [() : -12 -> -12], [(1,2)(3,4) : -12 -> -12], 
    [(1,3)(2,4) : -12 -> -12], [(1,4)(2,3) : -12 -> -12] ]
  !gapprompt@gap>| !gapinput@de4 := DoubleCoset( Ha4, Jc3, Jc3, e4 );|
  <double coset of [ Jc3b, Jc3b ] with representative [(1,4,2) : -13 -> -13]>
  !gapprompt@gap>| !gapinput@Perform( de4, Display );|
  [() : -13 -> -13]
  [(1,4)(2,3) : -13 -> -12]
  [(1,4)(2,3) : -12 -> -13]
  [() : -12 -> -12]
  [(1,4,2) : -13 -> -13]
  [(2,4,3) : -13 -> -12]
  [(1,2,3) : -12 -> -13]
  [(1,3,4) : -12 -> -12]
  [(1,2,4) : -13 -> -13]
  [(1,3,2) : -13 -> -12]
  [(2,3,4) : -12 -> -13]
  [(1,4,3) : -12 -> -12]
  !gapprompt@gap>| !gapinput@dcra4 := DoubleCosetRepresentatives( Ha4, Jc3, Jc3 );|
  [ [() : -14 -> -14], [(1,2)(3,4) : -14 -> -14], [() : -14 -> -13], 
    [(1,2)(3,4) : -14 -> -13], [() : -13 -> -14], [(1,2)(3,4) : -13 -> -14], 
    [() : -13 -> -13], [(1,2)(3,4) : -13 -> -13] ]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Conjugation}}\label{sec-conj}
\logpage{[ 4, 5, 0 ]}
\hyperdef{L}{X8653FC9786E3209A}{}
{
  \index{\texttt{\symbol{92}}\texttt{\symbol{94}}!for arrows} 

\subsection{\textcolor{Chapter }{\texttt{\symbol{92}}\texttt{\symbol{94}}}}
\logpage{[ 4, 5, 1 ]}\nobreak
\hyperdef{L}{X7D21FB1A7D21FB1A}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{\texttt{\symbol{92}}\texttt{\symbol{94}}({\mdseries\slshape a})\index{\texttt{\symbol{92}}\texttt{\symbol{94}}@\texttt{\texttt{\symbol{92}}\texttt{\symbol{94}}}}
\label{bSlash^}
}\hfill{\scriptsize (operation)}}\\


 Conjugation by an arrow $a = (c : p \to q)$ is the groupoid inner automorphism (see chapter \ref{chap-gpdaut}) defined as follows. There are two cases to consider. In the case $p \neq q$, 
\begin{itemize}
\item  objects $p,q$ are interchanged, and the remaining objects are fixed; 
\item  loops at $p,q$: $(b : p \to p) \mapsto (b^c : q \to q)$ and $(b: q \to q) \mapsto (b^{c^{-1}} : p \to p)$; 
\item  arrows between $p$ and $q$: $(b : p \to q) \mapsto (c^{-1}bc^{-1} : q \to p)$ and $(b : q \to p) \mapsto (cbc : p \to q)$; 
\item  costars at $p,q$: $(b : r \to p) \mapsto (bc : r \to q)$ and $(b : r \to q) \mapsto (bc^{-1} : r \to p)$; 
\item  stars at $p,q$: $(b : p \to r) \mapsto (c^{-1}b : \to q)$ and $(b : q \to r) \mapsto (cb : p \to r)$; 
\item  the remaining arrows are unchanged. 
\end{itemize}
 

 In the case $p=q$, 
\begin{itemize}
\item  all the objects are fixed; 
\item  loops at $p$ are conjugated by $c$, so $(b : p \to p) \mapsto (b^c : p \to p)$; 
\item  the rest of the costar and star at $p$ are permuted, 
\[ (b : r \to p) \mapsto (bc : r \to p) \quad\mbox{and}\quad (b : p \to r)
\mapsto (c^{-1}b : p \to r); \]
 
\item  the remaining arrows are unchanged. 
\end{itemize}
 

 The details of this construction may be found in section 3.2 of \cite{AlWe}. 

 See section \texttt{GroupoidInnerAutomorphism} (\ref{GroupoidInnerAutomorphism}) where conjugation is used to construct groupoid automorphisms. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@p := Arrow( Gd8, (5,7), -9, -9 );; |
  !gapprompt@gap>| !gapinput@q := Arrow( Gd8, (5,6,7,8), -8, -9 );; |
  !gapprompt@gap>| !gapinput@r := Arrow( Gd8, (5,6)(7,8), -9, -7 );; |
  !gapprompt@gap>| !gapinput@s := Arrow( Gd8, (5,6,7,8), -7, -8 );; |
  !gapprompt@gap>| !gapinput@##  conjugation with elements p, q, and r in Gd8: |
  !gapprompt@gap>| !gapinput@p^q;|
  [(6,8) : -8 -> -8]
  !gapprompt@gap>| !gapinput@p^r;|
  [(6,8) : -7 -> -7]
  !gapprompt@gap>| !gapinput@q^p;|
  [() : -8 -> -9]
  !gapprompt@gap>| !gapinput@q^r;|
  [(6,8) : -8 -> -7]
  !gapprompt@gap>| !gapinput@r^p;|
  [(5,8,7,6) : -9 -> -7]
  !gapprompt@gap>| !gapinput@r^q;|
  [(6,8) : -8 -> -7]
  !gapprompt@gap>| !gapinput@s^p;                           |
  [(5,6,7,8) : -7 -> -8]
  !gapprompt@gap>| !gapinput@s^q;|
  [(5,7)(6,8) : -7 -> -9]
  !gapprompt@gap>| !gapinput@s^r;|
  [(5,7) : -9 -> -8]
  
\end{Verbatim}
 \index{\texttt{\symbol{92}}\texttt{\symbol{94}}!for groupoids} 

\subsection{\textcolor{Chapter }{ConjugateGroupoid}}
\logpage{[ 4, 5, 2 ]}\nobreak
\label{subsec-conjgpd}
\hyperdef{L}{X78218F357BFEDE82}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ConjugateGroupoid({\mdseries\slshape gpd, e})\index{ConjugateGroupoid@\texttt{ConjugateGroupoid}}
\label{ConjugateGroupoid}
}\hfill{\scriptsize (operation)}}\\


 When $H$ is a subgroupoid of a groupoid $G$ and $a$ is an arrow of $G$, then the conjugate of $H$ by $a$ is the subgroupoid generated by the conjugates of the generators of $H$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@a5 := Arrow( Ga4, (1,2,3), -13, -12 ); |
  [(1,2,3) : -13 -> -12]
  !gapprompt@gap>| !gapinput@ConjugateGroupoid( Gk4, a5 );|
  single piece groupoid with rays: < Group( [ (1,2)(3,4), (1,3)(2,4) ] ), 
  [ -15, -14, -13, -12, -11 ], [ (), (1,2,3), (1,2)(3,4), (1,3)(2,4), (2,3,4) ] >
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Groupoids formed using isomorphisms}}\label{sec-gpd-isos}
\logpage{[ 4, 6, 0 ]}
\hyperdef{L}{X86DD749283068705}{}
{
  Here we describe an alternative way of constructing a connected groupoid. 

 Object groups in a connected groupoid are isomorphic, so we may use a
collection of isomorphisms to form a groupoid. Let $G_1,G_2,\ldots,G_n$ be isomorphic groups and, for $2 \leqslant i \leqslant n$, let $\mu_i : G_1 \to G_i$ be isomorphisms. Then $\mu_{ij} = \mu_i^{-1}*\mu_j$ is an isomorphism from $G_i$ to $G_j$. If we take $\{u_1,\ldots,u_n\}$ to be our set of objects, with $G_i$ the object group at $u_i$, we may consider the arrows in the groupoid to have the form $[[g_i,g_j] : u_i \to u_j]$ where $g_i \in G_i$ and $g_j = \mu_{ij}(g_i) \in G_j$. The product of $[[g_i,g_j] : u_i \to u_j]$ and $[[g'_j,g_k] : u_j \to u_k]$ is $[[\mu_{ij}^{-1}(g_jg'_j), \mu_{jk}(g_jg'_j)] : u_i \to u_k]$. 

 

\subsection{\textcolor{Chapter }{GroupoidByIsomorphisms}}
\logpage{[ 4, 6, 1 ]}\nobreak
\hyperdef{L}{X7B066DE28574A768}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupoidByIsomorphisms({\mdseries\slshape gp, obs, isos})\index{GroupoidByIsomorphisms@\texttt{GroupoidByIsomorphisms}}
\label{GroupoidByIsomorphisms}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGroupoidByIsomorphisms({\mdseries\slshape gpd})\index{IsGroupoidByIsomorphisms@\texttt{IsGroupoidByIsomorphisms}}
\label{IsGroupoidByIsomorphisms}
}\hfill{\scriptsize (property)}}\\


 The operation \texttt{GroupoidByIsomorphisms} takes a group \texttt{G1} as root group; a set of $n$ objects; and a set of $n$ isomorphisms from the root group, where the first isomorphism should be the
identity mapping on \texttt{G1}. The output is a single piece groupoid of type \texttt{IsGroupoidByIsomorphisms}. Its rays have the form \texttt{[One(G1),One(Gi)]} where \texttt{Gi} is the image of the $i$\texttt{\symbol{45}}th isomorphism. 

 In the example we first take three permutation groups isomorphic to the
symmetric group $S_3$. There follows an isomorphic groupoid whose object groups are a permutation
group; a pc\texttt{\symbol{45}}group and an fp\texttt{\symbol{45}}group. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@s3a := Group( (1,2), (2,3) );; |
  !gapprompt@gap>| !gapinput@s3b := Group( (4,6,8)(5,7,9), (4,9)(5,8)(6,7) );;|
  !gapprompt@gap>| !gapinput@s3c := Group( (4,6,8)(5,7,9), (5,9)(6,8) );;|
  !gapprompt@gap>| !gapinput@SetName( s3a, "s3a" );;|
  !gapprompt@gap>| !gapinput@SetName( s3b, "s3b" );;|
  !gapprompt@gap>| !gapinput@SetName( s3c, "s3c" );; |
  !gapprompt@gap>| !gapinput@ida := IdentityMapping( s3a );; |
  !gapprompt@gap>| !gapinput@isoab := IsomorphismGroups( s3a, s3b );; |
  !gapprompt@gap>| !gapinput@isoac := IsomorphismGroups( s3a, s3c );;|
  !gapprompt@gap>| !gapinput@isos1 := [ ida, isoab, isoac ];; |
  !gapprompt@gap>| !gapinput@G1 := GroupoidByIsomorphisms( s3a, [-3,-2,-1], isos1 );; |
  !gapprompt@gap>| !gapinput@gens1 := GeneratorsOfGroupoid( G1 );                    |
  [ [[ (1,2), (1,2) ] : -3 -> -3], [[ (2,3), (2,3) ] : -3 -> -3], 
    [[ (), () ] : -3 -> -2], [[ (), () ] : -3 -> -1] ]
  !gapprompt@gap>| !gapinput@x1 := ImageElm( isos1[2], (1,2) );;|
  !gapprompt@gap>| !gapinput@a1 := Arrow( G1, [ (1,2), x1 ], -3, -2 );|
  [[ (1,2), (4,5)(6,9)(7,8) ] : -3 -> -2]
  !gapprompt@gap>| !gapinput@a1^-1;|
  [[ (4,5)(6,9)(7,8), (1,2) ] : -2 -> -3]
  !gapprompt@gap>| !gapinput@y1 := ImageElm( isos1[2], (2,3) );;|
  !gapprompt@gap>| !gapinput@z1 := ImageElm( isos1[3], (2,3) );;|
  !gapprompt@gap>| !gapinput@b1 := Arrow( G1, [ y1, z1 ], -2, -1 );|
  [[ (4,9)(5,8)(6,7), (5,9)(6,8) ] : -2 -> -1]
  !gapprompt@gap>| !gapinput@c1 := a1*b1;|
  [[ (1,3,2), (4,8,6)(5,9,7) ] : -3 -> -1]
  
  !gapprompt@gap>| !gapinput@isopc := IsomorphismPcGroup( s3a );; |
  !gapprompt@gap>| !gapinput@s3p := Image( isopc );;|
  !gapprompt@gap>| !gapinput@f2 := FreeGroup( 2 );; |
  !gapprompt@gap>| !gapinput@s3f := f2/[ f2.1^3, f2.2^2, (f2.1*f2.2)^2 ];; |
  !gapprompt@gap>| !gapinput@isofp := GroupHomomorphismByImages(s3a,s3f,[(1,2,3),(2,3)],[s3f.1,s3f.2]);;|
  !gapprompt@gap>| !gapinput@isos2 := [ ida, isopc, isofp ];;|
  !gapprompt@gap>| !gapinput@G2 := GroupoidByIsomorphisms( s3a, [-6,-5,-4], isos2 );; |
  !gapprompt@gap>| !gapinput@gens2 := GeneratorsOfGroupoid( G2 );|
  [ [[ (1,2), (1,2) ] : -6 -> -6], [[ (2,3), (2,3) ] : -6 -> -6], 
    [[ (), <identity> of ... ] : -6 -> -5], [[ (), <identity ...> ] : -6 -> -4] 
   ]
  !gapprompt@gap>| !gapinput@x2 := ImageElm( isos2[2], (1,2) );;|
  !gapprompt@gap>| !gapinput@a2 := Arrow( G2, [ (1,2), x2 ], -6, -5 );|
  [[ (1,2), f1*f2 ] : -6 -> -5]
  !gapprompt@gap>| !gapinput@a2^-1;|
  [[ f1*f2, (1,2) ] : -5 -> -6]
  !gapprompt@gap>| !gapinput@y2 := ImageElm( isos2[2], (2,3) );;|
  !gapprompt@gap>| !gapinput@z2 := ImageElm( isos2[3], (2,3) );;|
  !gapprompt@gap>| !gapinput@b2 := Arrow( G2, [ y2, z2 ], -5, -4 );|
  [[ f1, f2^-1 ] : -5 -> -4]
  !gapprompt@gap>| !gapinput@c2 := a2*b2; |
  [[ (1,3,2), f1^2 ] : -6 -> -4]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Groupoids whose objects form a monoid}}\label{sec-mon-gpd}
\logpage{[ 4, 7, 0 ]}
\hyperdef{L}{X795DEB3D825B2120}{}
{
  Let $M$ be a monoid with $G$ its maximal subgroup. We may form a groupoid with the elements of $M$ as its objects and with arrows $t \to t*g$ for all $t \in M$ and $g \in G$. 

 This construction is used in the \textsf{XMod} package to construct the group\texttt{\symbol{45}}groupoid which corresponds
to a crossed module or cat$^2$\texttt{\symbol{45}}group. 

 

\subsection{\textcolor{Chapter }{SinglePieceGroupoidWithRays}}
\logpage{[ 4, 7, 1 ]}\nobreak
\hyperdef{L}{X805FA9F687C7F2A7}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SinglePieceGroupoidWithRays({\mdseries\slshape gp, obs, rays})\index{SinglePieceGroupoidWithRays@\texttt{SinglePieceGroupoidWithRays}}
\label{SinglePieceGroupoidWithRays}
}\hfill{\scriptsize (operation)}}\\


 When $M$ is a group, $G=M$ and the groupoid so constructed is a single piece which represents the regular
representation of $G$. The ray from $1$ to $g$ is just $g$ since $1*g=g$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@d8 := Group( (5,6,7,8), (5,7) );; |
  !gapprompt@gap>| !gapinput@ed8 := Elements( d8 );; |
  !gapprompt@gap>| !gapinput@Rd8 := SinglePieceGroupoidWithRays( d8, ed8, ed8 );|
  single piece groupoid with rays: < Group( [ (5,6,7,8), (5,7) ] ), 
  [ (), (6,8), (5,6)(7,8), (5,6,7,8), (5,7), (5,7)(6,8), (5,8,7,6), (5,8)(6,7) 
   ], [ (), (6,8), (5,6)(7,8), (5,6,7,8), (5,7), (5,7)(6,8), (5,8,7,6), 
    (5,8)(6,7) ] >
  !gapprompt@gap>| !gapinput@Homset( Rd8, (6,8), (5,7) );|
  <homset (6,8) -> (5,7) with head group Group( [ (5,8,7,6), (5,7) ] )>
  !gapprompt@gap>| !gapinput@Display( last ); |
  <homset (6,8) -> (5,7) with elements:
  [(5,7)(6,8) : (6,8) -> (5,7)]
  [(5,7) : (6,8) -> (5,7)]
  [() : (6,8) -> (5,7)]
  [(6,8) : (6,8) -> (5,7)]
  [(5,8,7,6) : (6,8) -> (5,7)]
  [(5,8)(6,7) : (6,8) -> (5,7)]
  [(5,6,7,8) : (6,8) -> (5,7)]
  [(5,6)(7,8) : (6,8) -> (5,7)]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{RightActionGroupoid}}
\logpage{[ 4, 7, 2 ]}\nobreak
\hyperdef{L}{X7E399664868937C8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RightActionGroupoid({\mdseries\slshape mon})\index{RightActionGroupoid@\texttt{RightActionGroupoid}}
\label{RightActionGroupoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGroupoidWithMonoidObjects({\mdseries\slshape gpd})\index{IsGroupoidWithMonoidObjects@\texttt{IsGroupoidWithMonoidObjects}}
\label{IsGroupoidWithMonoidObjects}
}\hfill{\scriptsize (property)}}\\


 When $M$ is a monoid, rather than a group, this construction produces several
components. One of these has as objects the elements of the group $G$. 

 When $M$ \emph{is} a group, this operation gives the same result as \texttt{SinglePieceGroupoidWithRays}. 

 As a simple example we take a monoid $M$ of size $13$ generated by $2$ transformations of degree $4$. The groupoid has $8$ components, of which $3$ have a single object and group $C_2$ generated by \texttt{Transformation([1,2,4,3])}, while $5$ have two objects and trivial group. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@M := Monoid( Transformation( [1,1,2,3] ), Transformation( [1,2,4,3] ) );|
  <transformation monoid of degree 4 with 2 generators>
  !gapprompt@gap>| !gapinput@rag := RightActionGroupoid( M );|
  groupoid with 8 pieces:
  1:  single piece groupoid with rays: < Group( 
  [ IdentityTransformation, Transformation( [ 1, 2, 4, 3 ] ) ] ), 
  [ Transformation( [ 1, 1, 1, 1 ] ) ], [ IdentityTransformation ] >
  2:  single piece groupoid with rays: < Group( 
  [ IdentityTransformation, Transformation( [ 1, 2, 4, 3 ] ) ] ), 
  [ Transformation( [ 1, 1, 1, 2 ] ) ], [ IdentityTransformation ] >
  3:  single piece groupoid with rays: < Group( [ IdentityTransformation ] ), 
  [ Transformation( [ 1, 1, 1, 3 ] ), Transformation( [ 1, 1, 1 ] ) ], 
  [ IdentityTransformation, Transformation( [ 1, 2, 4, 3 ] ) ] >
  4:  single piece groupoid with rays: < Group( 
  [ IdentityTransformation, Transformation( [ 1, 2, 4, 3 ] ) ] ), 
  [ Transformation( [ 1, 1, 2, 1 ] ) ], [ IdentityTransformation ] >
  5:  single piece groupoid with rays: < Group( [ IdentityTransformation ] ), 
  [ Transformation( [ 1, 1, 2, 3 ] ), Transformation( [ 1, 1, 2 ] ) ], 
  [ IdentityTransformation, Transformation( [ 1, 2, 4, 3 ] ) ] >
  6:  single piece groupoid with rays: < Group( [ IdentityTransformation ] ), 
  [ Transformation( [ 1, 1, 3, 1 ] ), Transformation( [ 1, 1, 4, 1 ] ) ], 
  [ IdentityTransformation, Transformation( [ 1, 2, 4, 3 ] ) ] >
  7:  single piece groupoid with rays: < Group( [ IdentityTransformation ] ), 
  [ Transformation( [ 1, 1, 3, 2 ] ), Transformation( [ 1, 1, 4, 2 ] ) ], 
  [ IdentityTransformation, Transformation( [ 1, 2, 4, 3 ] ) ] >
  8:  single piece groupoid with rays: < Group( [ IdentityTransformation ] ), 
  [ IdentityTransformation, Transformation( [ 1, 2, 4, 3 ] ) ], 
  [ IdentityTransformation, Transformation( [ 1, 2, 4, 3 ] ) ] >
  !gapprompt@gap>| !gapinput@IsGroupoidWithMonoidObjects( rag );|
  true
  !gapprompt@gap>| !gapinput@orag := ObjectList( rag );;|
  !gapprompt@gap>| !gapinput@hs := Homset( rag, orag[3], orag[4] );;  |
  !gapprompt@gap>| !gapinput@Display( hs );                  |
  <homset Transformation( [ 1, 1, 1, 3 ] ) -> Transformation( [ 1, 1, 1 ] )
    with elements:
  [Transformation( [ 1, 2, 4, 3 ] ) : Transformation( [ 1, 1, 1, 3 ] ) -> 
  Transformation( [ 1, 1, 1 ] )]
  
\end{Verbatim}
 }

 }

  
\chapter{\textcolor{Chapter }{Homomorphisms of Groupoids}}\label{chap-gpdhom}
\logpage{[ 5, 0, 0 ]}
\hyperdef{L}{X879ED2A7878B5A7A}{}
{
  A \emph{homomorphism} $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 homomorphism is not injective on objects, the image of the
source need not be a subgroupoid of the range. A simple example of this is
given by a homomorphism from the two\texttt{\symbol{45}}object,
four\texttt{\symbol{45}}element groupoid with trivial group to the free group $\langle a \rangle$ on one generator, when the image is $[1,a^n,a^{-n}]$ for some $n>0$. 

 A variety of homomorphism operations are available. 
\begin{itemize}
\item  The basic construction is a homomorphism $\phi : G \to H$ \emph{from} a connected groupoid $G$ to a connected groupoid $H$, constructed using \texttt{GroupoidHomomorphismFromSinglePiece}, (see \ref{sec-homsfrom}). 
\item  Since more than one connected groupoid may be mapped \emph{to} the same range, we then have the operation \texttt{GroupoidHomomorphismToSinglePiece}, (see \ref{sec-homsto}). 
\item  The third case arises when both source and range are unions of connected
groupoids, in which case \texttt{HomomorphismByUnion} is called, (see \ref{sec-genhoms}). 
\item  Fourthly, there are is an additional operation for the case where the source
is homogeneous and discrete, \texttt{GroupoidHomomorphismFromHomogeneousDiscrete}, (see \ref{subsec-hom-from-disc}). 
\item  Finally, there are special operations for inclusion mappings, restricted
mappings (see \ref{sec-spec-homs}). and groupoid automorphisms (see \ref{chap-gpdaut}). 
\end{itemize}
 

 
\section{\textcolor{Chapter }{Homomorphisms from a connected groupoid}}\label{sec-homsfrom}
\logpage{[ 5, 1, 0 ]}
\hyperdef{L}{X85D28690823636CD}{}
{
  

\subsection{\textcolor{Chapter }{GroupoidHomomorphismFromSinglePiece}}
\logpage{[ 5, 1, 1 ]}\nobreak
\hyperdef{L}{X870288C6803D9005}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupoidHomomorphismFromSinglePiece({\mdseries\slshape src, rng, gens, images})\index{GroupoidHomomorphismFromSinglePiece@\texttt{GroupoidHomomorphismFromSinglePiece}}
\label{GroupoidHomomorphismFromSinglePiece}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupoidHomomorphism({\mdseries\slshape args})\index{GroupoidHomomorphism@\texttt{GroupoidHomomorphism}}
\label{GroupoidHomomorphism}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGroupoidHomomorphism({\mdseries\slshape mwohom})\index{IsGroupoidHomomorphism@\texttt{IsGroupoidHomomorphism}}
\label{IsGroupoidHomomorphism}
}\hfill{\scriptsize (Category)}}\\


 The simplest groupoid homomorphism is a mapping $\phi : G \to H$ from a connected groupoid $G$ to a connected groupoid $H$. There are two equivalent sets of input data which may be used. Both require
the \texttt{Source} $G$ and the \texttt{Range} $H$. The first then requires: 
\begin{itemize}
\item  the set of generating arrows, \texttt{genG = GeneratorsOfGroupoid(G)}; 
\item  a list of image arrows \texttt{imphi} in $H$. 
\end{itemize}
 This may be implemented by the call \texttt{GroupoidHomomorphismFromSinglePiece(G,H,genG,imphi)}, and the data is stored in the attribute \texttt{MappingGeneratorsImages}. Alternatively, use the global function \texttt{GroupoidHomomorphism} with the same four parameters. 

 The alternative input data consists of: 
\begin{itemize}
\item  a homomorphism \texttt{rhom} from the root group of $G$ to the group at the image object in $H$; 
\item  a list \texttt{imobs} of the images of the objects of $G$; 
\item  a list \texttt{imrays} of the elements in the images of the rays of $G$, so that the image $\phi(r_i : o_1 \to o_i)$ of the $i$\texttt{\symbol{45}}th ray is \texttt{(imrays[i]:imobs[1]}$\to$\texttt{imobs[i])}. 
\end{itemize}
 This data is stored in the attribute \texttt{MappingToSinglePieceData}. 

 So an alternative way to construct this homomorphism of groupoids is to make a
call of the form \texttt{GroupoidHomomorphism(G,H,rhom,imobs,imrays)}. 

 In the following example the same homomorphism is constructed using both
methods. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Kk4 := SubgroupoidWithRays( Ha4, k4, [ (), (1,3,4), (1,4)(2,3) ] );;|
  !gapprompt@gap>| !gapinput@SetName( Kk4, "Kk4" );|
  !gapprompt@gap>| !gapinput@gen1 := GeneratorsOfGroupoid( Gd8 ); |
  [ [(5,6,7,8) : -9 -> -9], [(5,7) : -9 -> -9], [() : -9 -> -8], 
    [() : -9 -> -7] ]
  !gapprompt@gap>| !gapinput@gen2 := GeneratorsOfGroupoid( Kk4 ); |
  [ [(1,2)(3,4) : -14 -> -14], [(1,3)(2,4) : -14 -> -14], 
    [(1,3,4) : -14 -> -13], [(1,4)(2,3) : -14 -> -12] ]
  !gapprompt@gap>| !gapinput@images := [ gen2[1]*gen2[2], gen2[1]^2, gen2[3], gen2[4] ];|
  [ [(1,4)(2,3) : -14 -> -14], [() : -14 -> -14], [(1,3,4) : -14 -> -13],
   [(1,4)(2,3) : -14 -> -12] ]
  !gapprompt@gap>| !gapinput@hom8 := GroupoidHomomorphismFromSinglePiece( Gd8, Kk4, gen1, images );|
  groupoid homomorphism : Gd8 -> Kk4
  [ [ [(5,6,7,8) : -9 -> -9], [(5,7) : -9 -> -9], [() : -9 -> -8], 
        [() : -9 -> -7] ], 
    [ [(1,4)(2,3) : -14 -> -14], [() : -14 -> -14], [(1,3,4) : -14 -> -13], 
        [(1,4)(2,3) : -14 -> -12] ] ]
  !gapprompt@gap>| !gapinput@gend8 := GeneratorsOfGroup( d8 );;|
  !gapprompt@gap>| !gapinput@imh := [ (1,4)(2,3), () ];;|
  !gapprompt@gap>| !gapinput@h := GroupHomomorphismByImages( d8, a4, gend8, imh );                     |
  [ (5,6,7,8), (5,7) ] -> [ (1,4)(2,3), () ]
  !gapprompt@gap>| !gapinput@hom9 := GroupoidHomomorphism( Gd8, Kk4, h, [-14,-13,-12],|
  !gapprompt@>| !gapinput@                [ (), (1,3,4), (1,4)(2,3) ] );;|
  !gapprompt@gap>| !gapinput@hom8 = hom9;|
  true
  !gapprompt@gap>| !gapinput@e1 := Arrow( Gd8, (5,6,7,8), -7, -8 );;|
  !gapprompt@gap>| !gapinput@ImageElm( hom8, e1 );|
  [(1,3,4) : -12 -> -13]
  !gapprompt@gap>| !gapinput@IsGroupoidHomomorphism( hom8 );|
  true
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Properties and attributes of groupoid homomorphisms}}\label{sec-hom-attr-prop}
\logpage{[ 5, 2, 0 ]}
\hyperdef{L}{X7BFF46FD8308846F}{}
{
  
\subsection{\textcolor{Chapter }{Properties of a groupoid homomorphism}}\label{subsec-prop-homs}
\logpage{[ 5, 2, 1 ]}
\hyperdef{L}{X83DDA9528396451A}{}
{
  The properties listed in subsection \ref{sec-hompieces} for homomorphisms of magmas with objects also apply to groupoid homomorphisms. \index{IsInjectiveOnObjects@!for groupoid homomorphisms} \index{IsSurjectiveOnObjects@!for groupoid homomorphisms} \index{IsBijectiveOnObjects@!for groupoid homomorphisms} \index{IsAutomorphismWithObjects@!for groupoid homomorphisms} \index{IsEndomorphismWithObjects@!for groupoid homomorphisms} \index{IsInjective@!for groupoid homomorphisms} \index{IsSurjective@!for groupoid homomorphisms} 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@[ IsInjectiveOnObjects( hom8 ), IsSurjectiveOnObjects( hom8 ) ]; |
  [ true, true ]
  !gapprompt@gap>| !gapinput@[ IsInjective( hom8 ), IsSurjective( hom8 ) ];|
  [ false, false ]
  !gapprompt@gap>| !gapinput@ad8 := GroupHomomorphismByImages( d8, d8, |
  !gapprompt@>| !gapinput@              [ (5,6,7,8), (5,7) ], [ (5,8,7,6), (6,8) ] );; |
  !gapprompt@gap>| !gapinput@md8 := GroupoidHomomorphism( Gd8, Gd8, ad8,|
  !gapprompt@>| !gapinput@              [-7,-9,-8], [(),(5,7),(6,8)] );|
  groupoid homomorphism : Gd8 -> Gd8
  [ [ [(5,6,7,8) : -9 -> -9], [(5,7) : -9 -> -9], [() : -9 -> -8], 
        [() : -9 -> -7] ], 
    [ [(5,8,7,6) : -7 -> -7], [(6,8) : -7 -> -7], [(5,7) : -7 -> -9], 
        [(6,8) : -7 -> -8] ] ]
  !gapprompt@gap>| !gapinput@IsBijectiveOnObjects( md8 );|
  true
  !gapprompt@gap>| !gapinput@[ IsInjective( md8 ), IsSurjective( md8 ) ];  |
  [ true, true ]
  !gapprompt@gap>| !gapinput@[ IsEndomorphismWithObjects( md8 ), IsAutomorphismWithObjects( md8 ) ];|
  [ true, true ]
  
\end{Verbatim}
 }

 
\subsection{\textcolor{Chapter }{Attributes of a groupoid homomorphism}}\label{subsec-attr-homs}
\logpage{[ 5, 2, 2 ]}
\hyperdef{L}{X870565948381B921}{}
{
  The attributes of a groupoid homomorphism \texttt{mor} from a single piece groupoid cover both forms of construction defined above. 
\begin{itemize}
\item  \texttt{S = Source(mor)} is the source groupoid of the homomorphism; 
\item  \texttt{R = Range(mor)} is the range groupoid of the homomorphism; 
\item  \texttt{RootGroupHomomorphism(mor)} is the group homomorphism from the root group of \texttt{S} to the group at the image object in \texttt{R} of the root object in \texttt{S}; 
\item  \texttt{ImagesOfObjects(mor)} is the list of objects in \texttt{R} which are the images of the objects in \texttt{S}; 
\item  \texttt{ImageElementsOfRays(mor)} is the list of group elements in those arrows in \texttt{R} which are the images of the rays in \texttt{S}; 
\item  \texttt{MappingGeneratorsImages(mor)} is the two element list containing the list of generators in \texttt{S} and the list of their images in \texttt{R}; 
\item  \texttt{MappingToSinglePieceData(mor)} is a list with three elements: the root group homomorphism; the images of the
objects; and the images of the rays. 
\end{itemize}
 For other types of homomorphism the attributes are very similar. 

 The function \texttt{ObjectGroupHomomorphism}, though an operation, is included in this section for convenience. }

 

\subsection{\textcolor{Chapter }{RootGroupHomomorphism}}
\logpage{[ 5, 2, 3 ]}\nobreak
\hyperdef{L}{X85A99D8A83511DDE}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RootGroupHomomorphism({\mdseries\slshape hom})\index{RootGroupHomomorphism@\texttt{RootGroupHomomorphism}}
\label{RootGroupHomomorphism}
}\hfill{\scriptsize (attribute)}}\\


 This is the group homomorphism from the root group of the source groupoid to
the group at the image object in the range groupoid of the root object in the
source. }

 

\subsection{\textcolor{Chapter }{ImagesOfObjects}}
\logpage{[ 5, 2, 4 ]}\nobreak
\hyperdef{L}{X837EEB9578EA1A78}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ImagesOfObjects({\mdseries\slshape hom})\index{ImagesOfObjects@\texttt{ImagesOfObjects}}
\label{ImagesOfObjects}
}\hfill{\scriptsize (attribute)}}\\


 This is the list of objects in the range groupoid which are the images of the
objects in the source. }

 

\subsection{\textcolor{Chapter }{ImageElementsOfRays}}
\logpage{[ 5, 2, 5 ]}\nobreak
\hyperdef{L}{X791DC3F3852A6422}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ImageElementsOfRays({\mdseries\slshape hom})\index{ImageElementsOfRays@\texttt{ImageElementsOfRays}}
\label{ImageElementsOfRays}
}\hfill{\scriptsize (attribute)}}\\


 This is the list of group elements in those arrows in the range groupoid which
are the images of the rays in the source. }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@RootGroupHomomorphism( hom8 );|
  [ (5,6,7,8), (5,7) ] -> [ (1,4)(2,3), () ]
  !gapprompt@gap>| !gapinput@ImagesOfObjects( hom8 );|
  [ -14, -13, -12 ]
  !gapprompt@gap>| !gapinput@ImageElementsOfRays( hom8 );|
  [ (), (1,3,4), (1,4)(2,3) ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{MappingToSinglePieceData (for groupoids)}}
\logpage{[ 5, 2, 6 ]}\nobreak
\hyperdef{L}{X8391526C7A02FF19}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{MappingToSinglePieceData({\mdseries\slshape map})\index{MappingToSinglePieceData@\texttt{MappingToSinglePieceData}!for groupoids}
\label{MappingToSinglePieceData:for groupoids}
}\hfill{\scriptsize (attribute)}}\\


 As mentioned earlier, this attribute stores the root group homomorphism; a
list of the images of the objects; and a list of the elements in the images of
the rays. }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@MappingGeneratorsImages( hom8 );|
  [ [ [(5,6,7,8) : -9 -> -9], [(5,7) : -9 -> -9], [() : -9 -> -8], 
        [() : -9 -> -7] ], 
    [ [(1,4)(2,3) : -14 -> -14], [() : -14 -> -14], [(1,3,4) : -14 -> -13], 
        [(1,4)(2,3) : -14 -> -12] ] ]
  !gapprompt@gap>| !gapinput@MappingToSinglePieceData( hom8 );|
  [ [ [ (5,6,7,8), (5,7) ] -> [ (1,4)(2,3), () ], [ -14, -13, -12 ], 
        [ (), (1,3,4), (1,4)(2,3) ] ] ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{ObjectGroupHomomorphism}}
\logpage{[ 5, 2, 7 ]}\nobreak
\hyperdef{L}{X7C6775A178DB9D39}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ObjectGroupHomomorphism({\mdseries\slshape gpdhom, obj})\index{ObjectGroupHomomorphism@\texttt{ObjectGroupHomomorphism}}
\label{ObjectGroupHomomorphism}
}\hfill{\scriptsize (operation)}}\\


 For a given groupoid homomorphism, this operation gives the group homomorphism
from an object group of the source to the object group at the image object in
the range. 

 }

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

 
\section{\textcolor{Chapter }{Special types of groupoid homomorphism}}\label{sec-spec-homs}
\logpage{[ 5, 3, 0 ]}
\hyperdef{L}{X7DBC80D8817CDA04}{}
{
  In this section we mention inclusion mappings of subgroupoids; and mappings
restricted to a source subgroupoid. We also discuss various types of
isomorphism: to a different set of objects; to a permutation groupoid; to a
pc\texttt{\symbol{45}}groupoid. 

\subsection{\textcolor{Chapter }{InclusionMappingGroupoids}}
\logpage{[ 5, 3, 1 ]}\nobreak
\hyperdef{L}{X855DB6C8815CDCC3}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{InclusionMappingGroupoids({\mdseries\slshape gpd, sgpd})\index{InclusionMappingGroupoids@\texttt{InclusionMappingGroupoids}}
\label{InclusionMappingGroupoids}
}\hfill{\scriptsize (operation)}}\\


 The operation \texttt{InclusionMappingGroupoids(gpd,sgpd)} returns the inclusion homomorphism from the subgroupoid \texttt{sgpd} to \texttt{gpd}. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@incKk4 := InclusionMappingGroupoids( Ha4, Kk4 );     |
  groupoid homomorphism : Kk4 -> Ha4
  [ [ [(1,2)(3,4) : -14 -> -14], [(1,3)(2,4) : -14 -> -14], 
        [(1,3,4) : -14 -> -13], [(1,4)(2,3) : -14 -> -12] ], 
    [ [(1,2)(3,4) : -14 -> -14], [(1,3)(2,4) : -14 -> -14], 
        [(1,3,4) : -14 -> -13], [(1,4)(2,3) : -14 -> -12] ] ]
  
\end{Verbatim}
 For another example, refer back to subsection \texttt{PiecePositions} (\ref{PiecePositions}). 

\subsection{\textcolor{Chapter }{RestrictedMappingGroupoids}}
\logpage{[ 5, 3, 2 ]}\nobreak
\hyperdef{L}{X7946BC207D455A98}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RestrictedMappingGroupoids({\mdseries\slshape mor, sgpd})\index{RestrictedMappingGroupoids@\texttt{RestrictedMappingGroupoids}}
\label{RestrictedMappingGroupoids}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParentMappingGroupoids({\mdseries\slshape mor})\index{ParentMappingGroupoids@\texttt{ParentMappingGroupoids}}
\label{ParentMappingGroupoids}
}\hfill{\scriptsize (attribute)}}\\


 The operation \texttt{RestrictedMappingGroupoids(mor,sgpd)} returns the restriction of the homomorphism \texttt{mor} to the subgroupoid \texttt{sgpd} of its source. The range is usually set to the \texttt{ImagesSource} of the restriction. The restriction is assigned the attribute \texttt{ParentMappingGroupoids} with value \texttt{mor} (or that of \texttt{mor} is one exists). For another example see section \ref{sec-mxreps}. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Gc4 := Subgroupoid( Gd8, c4 );;  SetName( Gc4, "Gc4" );|
  !gapprompt@gap>| !gapinput@res4 := RestrictedMappingGroupoids( hom8, Gc4 );|
  groupoid homomorphism : 
  [ [ [(5,6,7,8) : -9 -> -9], [() : -9 -> -8], [() : -9 -> -7] ], 
    [ [(1,4)(2,3) : -14 -> -14], [(1,3,4) : -14 -> -13], 
        [(1,4)(2,3) : -14 -> -12] ] ]
  !gapprompt@gap>| !gapinput@ParentMappingGroupoids( res4 ) = hom8; |
  true
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsomorphismNewObjects (for groupoids)}}
\logpage{[ 5, 3, 3 ]}\nobreak
\hyperdef{L}{X83B8AB6D7C9DB264}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsomorphismNewObjects({\mdseries\slshape src, objlist})\index{IsomorphismNewObjects@\texttt{IsomorphismNewObjects}!for groupoids}
\label{IsomorphismNewObjects:for groupoids}
}\hfill{\scriptsize (operation)}}\\


 The operation \texttt{IsomorphismNewObjects(gpd,obs)} returns the isomorphism from a groupoid \texttt{gpd} to a groupoid with the same object group and ray elements but with a different
set \texttt{obs} of objects. 

 We then compute the composite homomorphism, \texttt{ mor8 : Gd8 \texttt{\symbol{45}}{\textgreater} Kk4
\texttt{\symbol{45}}{\textgreater} Ha4 \texttt{\symbol{45}}{\textgreater} Ga4}. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@isoHa4 := IsomorphismNewObjects( Ha4, [-30,-29,-28] );|
  groupoid homomorphism : 
  [ [ [(1,2,3) : -14 -> -14], [(2,3,4) : -14 -> -14], [() : -14 -> -13], 
        [() : -14 -> -12] ], 
    [ [(1,2,3) : -30 -> -30], [(2,3,4) : -30 -> -30], [() : -30 -> -29], 
        [() : -30 -> -28] ] ]
  !gapprompt@gap>| !gapinput@Ka4 := Range( isoHa4 );  SetName( Ka4, "Ka4" );|
  single piece groupoid: < a4, [ -30, -29, -28 ] >
  !gapprompt@gap>| !gapinput@IsSubgroupoid( Gk4, Kk4 );|
  true
  !gapprompt@gap>| !gapinput@incHa4 := InclusionMappingGroupoids( Ga4, Ha4 );; |
  !gapprompt@gap>| !gapinput@mor8 := hom8 * incKk4 * incHa4;                 |
  groupoid homomorphism : Gd8 -> Ga4
  [ [ [(5,6,7,8) : -9 -> -9], [(5,7) : -9 -> -9], [() : -9 -> -8], 
        [() : -9 -> -7] ], 
    [ [(1,4)(2,3) : -14 -> -14], [() : -14 -> -14], [(1,3,4) : -14 -> -13], 
        [(1,4)(2,3) : -14 -> -12] ] ]
  !gapprompt@gap>| !gapinput@ImageElm( mor8, e1 );|
  [(1,3,4) : -12 -> -13]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsomorphismStandardGroupoid}}
\logpage{[ 5, 3, 4 ]}\nobreak
\hyperdef{L}{X87C54BB581181400}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsomorphismStandardGroupoid({\mdseries\slshape gpd, obs})\index{IsomorphismStandardGroupoid@\texttt{IsomorphismStandardGroupoid}}
\label{IsomorphismStandardGroupoid}
}\hfill{\scriptsize (operation)}}\\


 The operation \texttt{IsomorphismStandardGroupoid(gpd,obs)} returns the isomorphism from a groupoid with rays to the groupoid of type \texttt{IsDirectProductWithCompleteDigraphDomain} on the given set \texttt{obs} of objects. \texttt{Gk4}, a subgroupoid of \texttt{Ga4}, was our first example of a groupoid with rays (see \texttt{SubgroupoidWithRays} (\ref{SubgroupoidWithRays})), and a standard isomorphic copy is formed here. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@isoGk4 := IsomorphismStandardGroupoid( Gk4, [-45..-41] );|
  groupoid homomorphism : 
  [ [ [(1,2)(3,4) : -15 -> -15], [(1,3)(2,4) : -15 -> -15], 
        [(1,2,3) : -15 -> -14], [(1,2,4) : -15 -> -13], [(1,3,4) : -15 -> -12], 
        [(2,3,4) : -15 -> -11] ], 
    [ [(1,2)(3,4) : -45 -> -45], [(1,3)(2,4) : -45 -> -45], [() : -45 -> -44], 
        [() : -45 -> -43], [() : -45 -> -42], [() : -45 -> -41] ] ]
  !gapprompt@gap>| !gapinput@G2k4 := Image( isoGk4 );  SetName( G2k4, "G2k4" );|
  single piece groupoid: < k4, [ -45 .. -41 ] >
  !gapprompt@gap>| !gapinput@e5 := Arrow( Gk4, (1,2,4) , -13, -12 );|
  [(1,2,4) : -13 -> -12]
  !gapprompt@gap>| !gapinput@ImageElm( isoGk4, e5 );|
  [(1,3)(2,4) : -43 -> -42]
  !gapprompt@gap>| !gapinput@invGk4 := InverseGeneralMapping( isoGk4 );|
  groupoid homomorphism : 
  [ [ [(1,2)(3,4) : -45 -> -45], [(1,3)(2,4) : -45 -> -45], [() : -45 -> -44], 
        [() : -45 -> -43], [() : -45 -> -42], [() : -45 -> -41] ], 
    [ [(1,2)(3,4) : -15 -> -15], [(1,3)(2,4) : -15 -> -15], 
        [(1,2,3) : -15 -> -14], [(1,2,4) : -15 -> -13], [(1,3,4) : -15 -> -12], 
        [(2,3,4) : -15 -> -11] ] ]
  
\end{Verbatim}
 This operation may also be used to provide a standard form for groupoids of
type \texttt{IsGroupoidByIsomorphisms} as described in subsection \texttt{GroupoidByIsomorphisms} (\ref{GroupoidByIsomorphisms}). 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G2;|
  single piece groupoid with rays: < s3a, [ -6, -5, -4 ], 
  [ [ (), () ], [ (), <identity> of ... ], [ (), <identity ...> ] ] >
  !gapprompt@gap>| !gapinput@isoG2 := IsomorphismStandardGroupoid( G2, [-44,-43,-42] ); |
  groupoid homomorphism : 
  [ [ [[ (1,2), (1,2) ] : -6 -> -6], [[ (2,3), (2,3) ] : -6 -> -6], 
        [[ (), <identity> of ... ] : -6 -> -5], [[ (), <identity ...> ] : -6 -> 
          -4] ], 
    [ [(1,2) : -44 -> -44], [(2,3) : -44 -> -44], [() : -44 -> -43], 
        [() : -44 -> -42] ] ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsomorphismPermGroupoid}}
\logpage{[ 5, 3, 5 ]}\nobreak
\hyperdef{L}{X7CF33CCD8278A904}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsomorphismPermGroupoid({\mdseries\slshape gpd})\index{IsomorphismPermGroupoid@\texttt{IsomorphismPermGroupoid}}
\label{IsomorphismPermGroupoid}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RegularActionHomomorphismGroupoid({\mdseries\slshape gpd})\index{RegularActionHomomorphismGroupoid@\texttt{RegularActionHomomorphismGroupoid}}
\label{RegularActionHomomorphismGroupoid}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsomorphismPcGroupoid({\mdseries\slshape gpd})\index{IsomorphismPcGroupoid@\texttt{IsomorphismPcGroupoid}}
\label{IsomorphismPcGroupoid}
}\hfill{\scriptsize (attribute)}}\\


 The attribute \texttt{IsomorphismPermGroupoid(gpd)} returns an isomorphism from a groupoid \texttt{gpd} to a groupoid with the same objects but with an isomorphic permutation group. 

 The attribute \texttt{RegularActionHomomorphismGroupoid} returns an isomorphism from a groupoid \texttt{gpd} to a groupoid with the same objects but with an isomorphic regular
presentation. In the example below these two operations produce equivalent
permutation groupoids. Only the second is printed as the first is liable to
change from one run to the next. 

 Similarly, the attribute \texttt{IsomorphismPcGroupoid(gpd)} attempts to return an isomorphism from the group to a
pc\texttt{\symbol{45}}group with the same objects. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@isoGq8 := IsomorphismPermGroupoid( Gq8 );;|
  !gapprompt@gap>| !gapinput@regGq8 := RegularActionHomomorphismGroupoid( Gq8 );|
  groupoid homomorphism : 
  [ [ [x : -19 -> -19], [y : -19 -> -19], [y2 : -19 -> -19], 
        [<identity> of ... : -19 -> -18], [<identity> of ... : -19 -> -17] ], 
    [ [(1,2,4,6)(3,8,7,5) : -19 -> -19], [(1,3,4,7)(2,5,6,8) : -19 -> -19], 
        [(1,4)(2,6)(3,7)(5,8) : -19 -> -19], [() : -19 -> -18], 
        [() : -19 -> -17] ] ]
  !gapprompt@gap>| !gapinput@Pq8 := Image( regGq8 );  SetName( Pq8, "Pq8" );|
  single piece groupoid: < Group( [ (1,2,4,6)(3,8,7,5), (1,3,4,7)(2,5,6,8), 
    (1,4)(2,6)(3,7)(5,8) ] ), [ -19, -18, -17 ] >
  !gapprompt@gap>| !gapinput@e7 := Arrow( Gq8, x*y, -18, -17 );;|
  !gapprompt@gap>| !gapinput@ImageElm( regGq8, e7 );|
  [(1,5,4,8)(2,7,6,3) : -18 -> -17]
  !gapprompt@gap>| !gapinput@Gc4 := Subgroupoid( Gd8, c4 );  SetName( Gc4, "Gc4" );|
  single piece groupoid: < c4, [ -9, -8, -7 ] >
  !gapprompt@gap>| !gapinput@isoGc4 := IsomorphismPcGroupoid( Gc4 );|
  groupoid homomorphism : 
  [ [ [(5,6,7,8) : -9 -> -9], [() : -9 -> -8], [() : -9 -> -7] ], 
    [ [f1 : -9 -> -9], [<identity> of ... : -9 -> -8], 
        [<identity> of ... : -9 -> -7] ] ]
        [<identity> of ... : -9 -> -7] ] ]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Homomorphisms to a connected groupoid}}\label{sec-homsto}
\logpage{[ 5, 4, 0 ]}
\hyperdef{L}{X7EAAB2A97E097FB6}{}
{
  

\subsection{\textcolor{Chapter }{HomomorphismToSinglePiece (for groupoids)}}
\logpage{[ 5, 4, 1 ]}\nobreak
\hyperdef{L}{X8700B5977B2513C1}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HomomorphismToSinglePiece({\mdseries\slshape src, rng, piecehoms})\index{HomomorphismToSinglePiece@\texttt{HomomorphismToSinglePiece}!for groupoids}
\label{HomomorphismToSinglePiece:for groupoids}
}\hfill{\scriptsize (operation)}}\\


 When $G$ is made up of two or more pieces, all of which get mapped to a connected
groupoid, we have a \emph{homomorphism to a single piece}. The third input parameter in this case is a list of the individual
homomorphisms \emph{from} the single pieces (in the correct order!). See section \ref{sec-mwohom} for the corresponding operation on homomorphisms of magmas with objects. 

 In the following example the source \texttt{V2} of \texttt{homV2} has two pieces, and both of the component homomorphisms are isomorphisms. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@V2 := UnionOfPieces( Gq8, Gc4 );;|
  !gapprompt@gap>| !gapinput@imGc4 := [ genPq8[1], genPq8[4], genPq8[5] ];|
  [ [(1,2,4,6)(3,8,7,5) : -19 -> -19], [() : -19 -> -18], [() : -19 -> -17] ]
  !gapprompt@gap>| !gapinput@homGc4 := GroupoidHomomorphism( Gc4, Pq8, genGc4, imGc4 );|
  groupoid homomorphism : Gc4 -> Pq8
  [ [ [(5,6,7,8) : -9 -> -9], [() : -9 -> -8], [() : -9 -> -7] ], 
    [ [(1,2,4,6)(3,8,7,5) : -19 -> -19], [() : -19 -> -18], [() : -19 -> -17] ] ]
  !gapprompt@gap>| !gapinput@homV2 := HomomorphismToSinglePiece( V2, Pq8, [ regGq8, homGc4 ] );|
  groupoid homomorphism : 
  [ [ [ [x : -19 -> -19], [y : -19 -> -19], [y2 : -19 -> -19], 
            [<identity> of ... : -19 -> -18], [<identity> of ... : -19 -> -17] ], 
        [ [(1,2,4,6)(3,8,7,5) : -19 -> -19], [(1,3,4,7)(2,5,6,8) : -19 -> -19], 
            [(1,4)(2,6)(3,7)(5,8) : -19 -> -19], [() : -19 -> -18], 
            [() : -19 -> -17] ] ], 
    [ [ [(5,6,7,8) : -9 -> -9], [() : -9 -> -8], [() : -9 -> -7] ], 
        [ [(1,2,4,6)(3,8,7,5) : -19 -> -19], [() : -19 -> -18], 
            [() : -19 -> -17] ] ] ]
  !gapprompt@gap>| !gapinput@ImageElm( homV2, e7 );            |
  [(1,5,4,8)(2,7,6,3) : -18 -> -17]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{GroupoidHomomorphismFromHomogeneousDiscrete}}
\logpage{[ 5, 4, 2 ]}\nobreak
\label{subsec-hom-from-disc}
\hyperdef{L}{X87225D86785DEBC2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupoidHomomorphismFromHomogeneousDiscrete({\mdseries\slshape src, rng, homs, oims})\index{GroupoidHomomorphismFromHomogeneousDiscrete@\texttt{Groupoid}\-\texttt{Homomorphism}\-\texttt{From}\-\texttt{Homogeneous}\-\texttt{Discrete}}
\label{GroupoidHomomorphismFromHomogeneousDiscrete}
}\hfill{\scriptsize (operation)}}\\


 This operation requires the source; the range; a list of homomorphisms from
the object groups to the image object groups; and a list of the image objects.
The source must be homogeneous and discrete, and the range must be a single
piece. The example uses the groupoid \texttt{HDc6} constructed in subsection \texttt{HomogeneousGroupoid} (\ref{HomogeneousGroupoid}). 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@c3a := Subgroup( a4, [(1,2,3)] );; c3b := Subgroup( a4, [(1,2,4)] );;|
  !gapprompt@gap>| !gapinput@c3c := Subgroup( a4, [(1,3,4)] );; c3d := Subgroup( a4, [(2,3,4)] );;|
  !gapprompt@gap>| !gapinput@hc6a := GroupHomomorphismByImages( c6, c3a, |
  !gapprompt@>| !gapinput@               [(11,12,13)(14,15)], [(1,2,3)] );;|
  !gapprompt@gap>| !gapinput@hc6b := GroupHomomorphismByImages( c6, c3b, |
  !gapprompt@>| !gapinput@               [(11,12,13)(14,15)], [(1,2,4)] );;|
  !gapprompt@gap>| !gapinput@hc6c := GroupHomomorphismByImages( c6, c3c, |
  !gapprompt@>| !gapinput@               [(11,12,13)(14,15)], [(1,3,4)] );;|
  !gapprompt@gap>| !gapinput@hc6d := GroupHomomorphismByImages( c6, c3d, |
  !gapprompt@>| !gapinput@               [(11,12,13)(14,15)], [(2,3,4)] );;|
  !gapprompt@gap>| !gapinput@mor6 := GroupoidHomomorphismFromHomogeneousDiscrete( HDc6, Ga4,|
  !gapprompt@>| !gapinput@             [ hc6a, hc6b, hc6c, hc6d ], [-15,-14,-12,-11] );|
  groupoid homomorphism : HDc6 -> Ga4
  !gapprompt@gap>| !gapinput@e6 := Arrow( HDc6, (11,12,13), -25, -25 );;|
  !gapprompt@gap>| !gapinput@ImageElm( mor6, e6 );|
  [(1,3,4) : -12 -> -12]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Homomorphisms to more than one piece}}\label{sec-genhoms}
\logpage{[ 5, 5, 0 ]}
\hyperdef{L}{X795C8DE37AED7B44}{}
{
  

\subsection{\textcolor{Chapter }{HomomorphismByUnion (for groupoids)}}
\logpage{[ 5, 5, 1 ]}\nobreak
\hyperdef{L}{X847094F478113EA6}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HomomorphismByUnion({\mdseries\slshape src, rng, homs})\index{HomomorphismByUnion@\texttt{HomomorphismByUnion}!for groupoids}
\label{HomomorphismByUnion:for groupoids}
}\hfill{\scriptsize (operation)}}\\


 As in section \ref{sec-hompieces}, when the range $H$ has more than one connected component, a homomorphism is a union of
homomorphisms, one for each piece in the range. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@W1 := UnionOfPieces( Ha4, Gd8 );;|
  !gapprompt@gap>| !gapinput@W2 := UnionOfPieces( Ka4, Kk4 );;|
  !gapprompt@gap>| !gapinput@SetName( W1, "[Ha4,Gd8]" );  SetName( W2, "[Ka4,Kk4]" );|
  !gapprompt@gap>| !gapinput@homW := HomomorphismByUnion( W1, W2, [ isoHa4, hom8 ] );;|
  !gapprompt@gap>| !gapinput@Display( homW );           |
  groupoid homomorphism: [Ha4,Gd8] -> [Ka4,Kk4] with pieces :
  homomorphism to single piece groupoid: Ha4 -> Ka4
  root group homomorphism:
  (1,2,3) -> (1,2,3)
  (2,3,4) -> (2,3,4)
  object map: [ -14, -13, -12 ] -> [ -30, -29, -28 ]
  ray images: [ (), (), () ]
  homomorphism to single piece groupoid: Gd8 -> Kk4
  root group homomorphism:
  (5,6,7,8) -> (1,4)(2,3)
  (5,7) -> ()
  object map: [ -9, -8, -7 ] -> [ -14, -13, -12 ]
  ray images: [ (), (1,3,4), (1,4)(2,3) ]
   
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsomorphismGroupoids}}
\logpage{[ 5, 5, 2 ]}\nobreak
\hyperdef{L}{X7E2C6BCC7AAB25BE}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsomorphismGroupoids({\mdseries\slshape A, B})\index{IsomorphismGroupoids@\texttt{IsomorphismGroupoids}}
\label{IsomorphismGroupoids}
}\hfill{\scriptsize (operation)}}\\


 When $A,B$ are two single piece groupoids, they are isomorphic provided they have the
same number of objects and the root groups are isomorphic. 

 When $A=[A_1,\ldots,A_n],~ B=[B_1,\ldots,B_n]$ are both unions of connected groupoids, they are isomorphic if there is a
permutation $\pi$ of $[1,\ldots,n]$ such that $A_i$ is isomorphic to $B_{\pi(i)}$ for all $i$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@s3b := Group( (4,6,8)(5,7,9), (4,9)(5,8)(6,7) );;|
  !gapprompt@gap>| !gapinput@s3c := Group( (4,6,8)(5,7,9), (5,9)(6,8) );;|
  !gapprompt@gap>| !gapinput@Gb := SinglePieceGroupoid( s3b, [-6,-5,-4] );; |
  !gapprompt@gap>| !gapinput@Gc := SinglePieceGroupoid( s3c, [-16,-15,-14] );; |
  !gapprompt@gap>| !gapinput@SetName( Gb, "Gb" );  SetName( Gc, "Gc" );  |
  !gapprompt@gap>| !gapinput@c6b := Group( (1,2,3,4,5,6) );; |
  !gapprompt@gap>| !gapinput@c6c := Group( (7,8)(9,10,11) );;|
  !gapprompt@gap>| !gapinput@Hb := SinglePieceGroupoid( c6b, [-10,-9,-8,-7] );; |
  !gapprompt@gap>| !gapinput@Hc := SinglePieceGroupoid( c6c, [-20,-19,-18,-17] );; |
  !gapprompt@gap>| !gapinput@SetName( Hb, "Hb" );  SetName( Hc, "Hc" ); |
  !gapprompt@gap>| !gapinput@IsomorphismGroupoids( Gb, Gc );|
  groupoid homomorphism : Gb -> Gc
  [ [ [(4,6,8)(5,7,9) : -6 -> -6], [(4,9)(5,8)(6,7) : -6 -> -6], 
        [() : -6 -> -5], [() : -6 -> -4] ], 
    [ [(4,6,8)(5,7,9) : -16 -> -16], [(5,9)(6,8) : -16 -> -16], 
        [() : -16 -> -15], [() : -16 -> -14] ] ]
  !gapprompt@gap>| !gapinput@IsomorphismGroupoids( Gb, Hb );|
  fail
  !gapprompt@gap>| !gapinput@B := UnionOfPieces( [ Gb, Hb ] );; |
  !gapprompt@gap>| !gapinput@C := UnionOfPieces( [ Gc, Hc ] );;|
  !gapprompt@gap>| !gapinput@isoBC := IsomorphismGroupoids( B, C );; |
  !gapprompt@gap>| !gapinput@Print( List( PiecesOfMapping(isoBC), p -> [Source(p),Range(p)] ) );|
  [ [ Hb, Hc ], [ Gb, Gc ] ]
  
\end{Verbatim}
 }

 }

  
\chapter{\textcolor{Chapter }{Automorphisms of Groupoids}}\label{chap-gpdaut}
\logpage{[ 6, 0, 0 ]}
\hyperdef{L}{X803E01577A2B37D2}{}
{
  In this chapter we consider automorphisms of single piece groupoids; then
homogeneous discrete groupoids; and finally homogeneous groupoids. We also
consider matrix representations and groupooid actions. 
\section{\textcolor{Chapter }{Automorphisms of single piece groupoids}}\label{sec-autos-single}
\logpage{[ 6, 1, 0 ]}
\hyperdef{L}{X7935832881320667}{}
{
  

\subsection{\textcolor{Chapter }{GroupoidAutomorphismByObjectPerm}}
\logpage{[ 6, 1, 1 ]}\nobreak
\hyperdef{L}{X79DA704A8051CB72}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupoidAutomorphismByObjectPerm({\mdseries\slshape gpd, imobs})\index{GroupoidAutomorphismByObjectPerm@\texttt{GroupoidAutomorphismByObjectPerm}}
\label{GroupoidAutomorphismByObjectPerm}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupoidAutomorphismByGroupAuto({\mdseries\slshape gpd, gpiso})\index{GroupoidAutomorphismByGroupAuto@\texttt{GroupoidAutomorphismByGroupAuto}}
\label{GroupoidAutomorphismByGroupAuto}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupoidAutomorphismByNtuple({\mdseries\slshape gpd, imrays})\index{GroupoidAutomorphismByNtuple@\texttt{GroupoidAutomorphismByNtuple}}
\label{GroupoidAutomorphismByNtuple}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupoidAutomorphismByRayShifts({\mdseries\slshape gpd, imrays})\index{GroupoidAutomorphismByRayShifts@\texttt{GroupoidAutomorphismByRayShifts}}
\label{GroupoidAutomorphismByRayShifts}
}\hfill{\scriptsize (operation)}}\\


 We first describe automorphisms of a groupoid $G$ where $G$ is the direct product of a group $g$ and a complete digraph with $n$ objects.. The automorphism group is generated by three types of automorphism: 
\begin{itemize}
\item  given a permutation $\pi$ of the $n$ objects, we define 
\[ \alpha_{\pi} : G \to G,~ (g : o_i \to o_j) \mapsto (g : o_{\pi i} \to o_{\pi
j}); \]
 
\item  given an automorphism $\theta$ of the root group $g$, we define 
\[ \alpha_{\theta} : G \to G,~ (g : o_i \to o_j) \mapsto (\theta g : o_i \to
o_j); \]
 
\item  given $L = [g_1,g_2,g_3,\ldots,g_n] \in g^n$ we define 
\[ \alpha_L : G \to G,~ (g : o_i \to o_j) \mapsto (g_i^{-1}gg_j : o_i \to o_j). \]
 If $g_1 = 1_g$, then for all $j$ the rays $(r_j : o_1 \to o_j)$ are shifted by $g_j\;$: so they map to $(r_jg_j : o_1 \to o_j)$. So the operation \texttt{GroupoidAutomorphismByRayShifts} is the special case of \texttt{GroupoidAutomorphismByNtuple} when $g_1=1$. 
\end{itemize}
 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@perm1 := [-13,-12,-14];;|
  !gapprompt@gap>| !gapinput@aut1 := GroupoidAutomorphismByObjectPerm( Ha4, perm1 );; |
  !gapprompt@gap>| !gapinput@Display( aut1 ); |
  homomorphism to single piece groupoid: Ha4 -> Ha4
  root group homomorphism:
  (1,2,3) -> (1,2,3)
  (2,3,4) -> (2,3,4)
  object map: [ -14, -13, -12 ] -> [ -13, -12, -14 ]
  ray images: [ (), (), () ]
  !gapprompt@gap>| !gapinput@d := Arrow( Ha4, (1,3,4), -12, -13 ); |
  [(1,3,4) : -12 -> -13]
  !gapprompt@gap>| !gapinput@d1 := ImageElm( aut1, d ); |
  [(1,3,4) : -14 -> -12]
  !gapprompt@gap>| !gapinput@gensa4 := GeneratorsOfGroup( a4 );; |
  !gapprompt@gap>| !gapinput@alpha2 := GroupHomomorphismByImages( a4, a4, gensa4, [(2,3,4), (1,3,4)] );; |
  !gapprompt@gap>| !gapinput@aut2 := GroupoidAutomorphismByGroupAuto( Ha4, alpha2 );; |
  !gapprompt@gap>| !gapinput@Display( aut2 ); |
  homomorphism to single piece groupoid: Ha4 -> Ha4
  root group homomorphism:
  (1,2,3) -> (2,3,4)
  (2,3,4) -> (1,3,4)
  object map: [ -14, -13, -12 ] -> [ -14, -13, -12 ]
  ray images: [ (), (), () ]
  !gapprompt@gap>| !gapinput@d2 := ImageElm( aut2, d1 );|
  [(1,2,4) : -14 -> -12]
  !gapprompt@gap>| !gapinput@L3 := [(1,2)(3,4), (1,3)(2,4), (1,4)(2,3)];; |
  !gapprompt@gap>| !gapinput@aut3 := GroupoidAutomorphismByNtuple( Ha4, L3 );; |
  !gapprompt@gap>| !gapinput@Display( aut3 ); |
  homomorphism to single piece groupoid: Ha4 -> Ha4
  root group homomorphism:
  (1,2,3) -> (1,4,2)
  (2,3,4) -> (1,4,3)
  object map: [ -14, -13, -12 ] -> [ -14, -13, -12 ]
  ray images: [ (), (1,4)(2,3), (1,3)(2,4) ]
  !gapprompt@gap>| !gapinput@d3 := ImageElm( aut3, d2 );|
  [(2,3,4) : -14 -> -12]
  !gapprompt@gap>| !gapinput@L4 := [(), (1,3,2), (2,4,3)];; |
  !gapprompt@gap>| !gapinput@aut4 := GroupoidAutomorphismByRayShifts( Ha4, L4 );; |
  !gapprompt@gap>| !gapinput@Display( aut4 ); |
  homomorphism to single piece groupoid: Ha4 -> Ha4
  root group homomorphism:
  (1,2,3) -> (1,2,3)
  (2,3,4) -> (2,3,4)
  object map: [ -14, -13, -12 ] -> [ -14, -13, -12 ]
  ray images: [ (), (1,3,2), (2,4,3) ]
  !gapprompt@gap>| !gapinput@d4 := ImageElm( aut4, d3 );|
  [() : -14 -> -12]
  !gapprompt@gap>| !gapinput@h4 := Arrow( Ha4, (2,3,4), -12, -13 );; |
  !gapprompt@gap>| !gapinput@aut1234 := aut1*aut2*aut3*aut4;; |
  !gapprompt@gap>| !gapinput@Display( aut1234 ); |
  homomorphism to single piece groupoid: Ha4 -> Ha4
  root group homomorphism:
  (1,2,3) -> (1,4,3)
  (2,3,4) -> (1,2,3)
  object map: [ -14, -13, -12 ] -> [ -13, -12, -14 ]
  ray images: [ (), (2,3,4), (1,3,4) ]
  !gapprompt@gap>| !gapinput@d4  = ImageElm( aut1234, d );|
  true
  !gapprompt@gap>| !gapinput@inv1234 := InverseGeneralMapping( aut1234 );; |
  !gapprompt@gap>| !gapinput@Display( inv1234 ); |
  homomorphism to single piece groupoid: Ha4 -> Ha4
  root group homomorphism:
  (1,2,3) -> (1,4,3)
  (2,3,4) -> (2,4,3)
  object map: [ -14, -13, -12 ] -> [ -12, -14, -13 ]
  ray images: [ (), (1,3,2), (1,3,4) ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{GroupoidInnerAutomorphism}}
\logpage{[ 6, 1, 2 ]}\nobreak
\hyperdef{L}{X86BD61567B41B139}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupoidInnerAutomorphism({\mdseries\slshape gpd, arrow})\index{GroupoidInnerAutomorphism@\texttt{GroupoidInnerAutomorphism}}
\label{GroupoidInnerAutomorphism}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupoidInnerAutomorphismNormalSubgroupoid({\mdseries\slshape gpd, subgpd, arrow})\index{GroupoidInnerAutomorphismNormalSubgroupoid@\texttt{Groupoid}\-\texttt{Inner}\-\texttt{Automorphism}\-\texttt{Normal}\-\texttt{Subgroupoid}}
\label{GroupoidInnerAutomorphismNormalSubgroupoid}
}\hfill{\scriptsize (operation)}}\\


 \index{inner automorphism} Given an arrow $a = (c : p \to q) \in G$ with $p \neq q$, the \emph{inner automorphism} $\alpha_a$ of $G$ by $a$ is the mapping $g \mapsto g^a$ where conjugation of arrows is defined in section \ref{sec-conj}. It is easily checked that if $L_a = [1,\ldots,1,c^{-1},1,\ldots,1,c,1,\ldots,1]$, with $c^{-1}$ in position $p$ and $c$ in position $q$, then 
\[ \alpha_a ~=~ \alpha_{(p,q)} * \alpha_{L_a}. \]
 Similarly, when $p=q$, then $\alpha_a = \alpha_{L_a}$ where now $ L_a = [1,\ldots,1,c,1,\ldots,1]$, with $c$ in position $p$. }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@inn1 := GroupoidInnerAutomorphism( Ha4, h4 );;|
  !gapprompt@gap>| !gapinput@Display( inn1 );|
  homomorphism to single piece groupoid: Ha4 -> Ha4
  root group homomorphism:
  (1,2,3) -> (1,2,3)
  (2,3,4) -> (2,3,4)
  object map: [ -14, -13, -12 ] -> [ -14, -12, -13 ]
  ray images: [ (), (2,4,3), (2,3,4) ]
  !gapprompt@gap>| !gapinput@d5 := ImageElm( inn1, d4 );|
  [(2,3,4) : -14 -> -13]
  
\end{Verbatim}
 Conjugation may also be applied to certain normal subgroupoids of $G$. Firstly, let $N$ be the wide subgroupoid of $G$ determined by a normal subgroup $n$ of the root group. Then, provided the group element of $a$ is in $n$, the inner automorphism by $a$ may be applied to $N$. 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Nk4 := SubgroupoidBySubgroup( Ha4, k4 );;|
  !gapprompt@gap>| !gapinput@SetName( Nk4, "Nk4" );|
  !gapprompt@gap>| !gapinput@e4 := Arrow( Ha4, (1,2)(3,4), -14, -13 );;|
  !gapprompt@gap>| !gapinput@inn2 := GroupoidInnerAutomorphismNormalSubgroupoid( Ha4, Nk4, e4 );;|
  !gapprompt@gap>| !gapinput@Display( inn2 );|
  homomorphism to single piece groupoid: Nk4 -> Nk4
  root group homomorphism:
  (1,2)(3,4) -> (1,2)(3,4)
  (1,3)(2,4) -> (1,3)(2,4)
  object map: [ -14, -13, -12 ] -> [ -13, -14, -12 ]
  ray images: [ (), (), (1,2)(3,4) ]
  
\end{Verbatim}
 Secondly, if $H$ is a homogeneous, discrete subgroupoid of $G$ and if the group element of $a$ is in the common vertex groups, then the inner automorphism may be applied to $H$. 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Ma4 := MaximalDiscreteSubgroupoid( Ha4 );;|
  !gapprompt@gap>| !gapinput@SetName( Ma4, "Ma4" );|
  !gapprompt@gap>| !gapinput@inn3 := GroupoidInnerAutomorphism( Ha4, Ma4, e4 );;|
  !gapprompt@gap>| !gapinput@Display( inn3 );|
  homogeneous discrete groupoid mapping: [ Ma4 ] -> [ Ma4 ]
  images of objects: [ -13, -14, -12 ]
  object homomorphisms:
  GroupHomomorphismByImages( a4, a4, [ (1,2,3), (2,3,4) ], [ (1,4,2), (1,4,3)  ] )
  GroupHomomorphismByImages( a4, a4, [ (1,2,3), (2,3,4) ], [ (1,4,2), (1,4,3)  ] )
  GroupHomomorphismByImages( a4, a4, [ (1,2,3), (2,3,4) ], [ (1,2,3), (2,3,4)  ] )
  
\end{Verbatim}
 
\subsection{\textcolor{Chapter }{Automorphisms of a groupoid with rays}}\label{subsec-autos-with-rays}
\logpage{[ 6, 1, 3 ]}
\hyperdef{L}{X8278B93E7F78038C}{}
{
  Let $S$ be a wide subgroupoid with rays of a standard groupoid $G$. 

 An automorphism $\alpha$ of the root group $H$ extends to the whole of $S$ with the rays fixed by the automorphism: $(r^{-1}_ihr_j : o_i \to o_j) \mapsto (r^{-1}_i (\alpha h)r_j : o_i \to o_j)$. 

 An automorphism of $G$ obtained by permuting the objects may map $S$ to a different subgroupoid. So we construct an isomorphism $\iota$ from $S$ to a standard groupoid $T$, construct $\alpha$ permuting the objects of $T$, and return $\iota*\alpha*\iota^{-1}$. 

 For an automorphism by ray shifts we require that the shifts are elements of
the root group of $S$. 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@## (1) automorphism by group auto |
  !gapprompt@gap>| !gapinput@a6 := GroupHomomorphismByImages( k4, k4,|
  !gapprompt@>| !gapinput@             [ (1,2)(3,4), (1,3)(2,4) ], [ (1,3)(2,4), (1,4)(2,3) ] );;|
  !gapprompt@gap>| !gapinput@aut6 := GroupoidAutomorphismByGroupAuto( Kk4, a6 );|
  groupoid homomorphism : Kk4 -> Kk4
  [ [ [(1,2)(3,4) : -14 -> -14], [(1,3)(2,4) : -14 -> -14], 
        [(1,3,4) : -14 -> -13], [(1,4)(2,3) : -14 -> -12] ], 
    [ [(1,3)(2,4) : -14 -> -14], [(1,4)(2,3) : -14 -> -14], 
        [(1,3,4) : -14 -> -13], [(1,4)(2,3) : -14 -> -12] ] ]
  !gapprompt@gap>| !gapinput@a := Arrow( Kk4, (1,3)(2,4), -12, -12 );;|
  !gapprompt@gap>| !gapinput@ImageElm( aut6, a );|
  [(1,4)(2,3) : -12 -> -12]
  !gapprompt@gap>| !gapinput@b := Arrow( Kk4, (1,4,2), -12, -13 );;|
  !gapprompt@gap>| !gapinput@ImageElm( aut6, b );|
  [(1,2,3) : -12 -> -13]
  !gapprompt@gap>| !gapinput@## (2) automorphism by object perm |
  !gapprompt@gap>| !gapinput@aut7 := GroupoidAutomorphismByObjectPerm( Kk4, [-13,-12,-14] );|
  groupoid homomorphism : Kk4 -> Kk4
  [ [ [(1,2)(3,4) : -14 -> -14], [(1,3)(2,4) : -14 -> -14], 
        [(1,3,4) : -14 -> -13], [(1,4)(2,3) : -14 -> -12] ], 
    [ [(1,4)(2,3) : -13 -> -13], [(1,2)(3,4) : -13 -> -13], 
        [(2,3,4) : -13 -> -12], [(1,4,3) : -13 -> -14] ] ]
  !gapprompt@gap>| !gapinput@ImageElm( aut7, a );                                           |
  [(1,3)(2,4) : -14 -> -14]
  !gapprompt@gap>| !gapinput@ImageElm( aut7, b );                                           |
  [(1,3)(2,4) : -14 -> -12]
  !gapprompt@gap>| !gapinput@## (3) automorphism by ray shifts |
  !gapprompt@gap>| !gapinput@aut8 := GroupoidAutomorphismByRayShifts( Kk4,|
  !gapprompt@>| !gapinput@               [ (), (1,4)(2,3), (1,3)(2,4) ] );|
  groupoid homomorphism : Kk4 -> Kk4
  [ [ [(1,2)(3,4) : -14 -> -14], [(1,3)(2,4) : -14 -> -14], 
        [(1,3,4) : -14 -> -13], [(1,4)(2,3) : -14 -> -12] ], 
    [ [(1,2)(3,4) : -14 -> -14], [(1,3)(2,4) : -14 -> -14], 
        [(1,2,3) : -14 -> -13], [(1,2)(3,4) : -14 -> -12] ] ]
  !gapprompt@gap>| !gapinput@ImageElm( aut8, a );|
  [(1,3)(2,4) : -12 -> -12]
  !gapprompt@gap>| !gapinput@ImageElm( aut8, b );|
  [(1,2,3) : -12 -> -13]
  !gapprompt@gap>| !gapinput@## (4) combine these three automorphisms |
  !gapprompt@gap>| !gapinput@aut678 := aut6 * aut7 * aut8;|
  groupoid homomorphism : Kk4 -> Kk4
  [ [ [(1,2)(3,4) : -14 -> -14], [(1,3)(2,4) : -14 -> -14], 
        [(1,3,4) : -14 -> -13], [(1,4)(2,3) : -14 -> -12] ], 
    [ [(1,2)(3,4) : -13 -> -13], [(1,3)(2,4) : -13 -> -13], 
        [(1,4,3) : -13 -> -12], [(1,3,2) : -13 -> -14] ] ]
  !gapprompt@gap>| !gapinput@ImageElm( aut678, a ); |
  [(1,4)(2,3) : -14 -> -14]
  !gapprompt@gap>| !gapinput@ImageElm( aut678, b );|
  [(1,4)(2,3) : -14 -> -12]
  !gapprompt@gap>| !gapinput@## (5) conjgation by an arrow|
  !gapprompt@gap>| !gapinput@e8 := Arrow( Kk4, (1,3)(2,4), -14, -12 );;|
  !gapprompt@gap>| !gapinput@aut9 := GroupoidInnerAutomorphism( Kk4, e8 );|
  groupoid homomorphism : Kk4 -> Kk4
  [ [ [(1,2)(3,4) : -14 -> -14], [(1,3)(2,4) : -14 -> -14], 
        [(1,3,4) : -14 -> -13], [(1,4)(2,3) : -14 -> -12] ], 
    [ [(1,2)(3,4) : -12 -> -12], [(1,3)(2,4) : -12 -> -12], 
        [(1,4,2) : -12 -> -13], [(1,4)(2,3) : -12 -> -14] ] ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AutomorphismGroupOfGroupoid}}
\logpage{[ 6, 1, 4 ]}\nobreak
\hyperdef{L}{X7DB9D5737EB8C260}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AutomorphismGroupOfGroupoid({\mdseries\slshape gpd})\index{AutomorphismGroupOfGroupoid@\texttt{AutomorphismGroupOfGroupoid}}
\label{AutomorphismGroupOfGroupoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NiceObjectAutoGroupGroupoid({\mdseries\slshape gpd, aut})\index{NiceObjectAutoGroupGroupoid@\texttt{NiceObjectAutoGroupGroupoid}}
\label{NiceObjectAutoGroupGroupoid}
}\hfill{\scriptsize (operation)}}\\


 As above, let $G$ be the direct product of a group $g$ and a complete digraph with $n$ objects. The \index{AutomorphismGroup@\texttt{AutomorphismGroup}} \texttt{AutomorphismGroup} $\Aut(G)$ of $G$ is isomorphic to the quotient of $S_n \times A \times g^n$ by a subgroup isomorphic to $g$, where $A$ is the automorphism group of $g$ and $S_n$ is the symmetric group on the $n$ objects. This is one of the main topics in \cite{AlWe}. 

 If $H$ is the union of $k$ groupoids, all isomorphic to $G$, then $\Aut(H)$ is isomorphic to $S_k \ltimes \Aut(G)$. 

 The function \texttt{NiceObjectAutoGroupGroupoid} takes a groupoid and a subgroup of its automorphism group and retuns a \emph{nice monomorphism} from this automorphism group to a pc\texttt{\symbol{45}}group, if one is
available. The current implementation is experimental. Note that \texttt{ImageElm} at present only works on generating elements. 

 }

 
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=Example]
  
  @gapprompt|gap>B @gapinput|AHa4 := AutomorphismGroupOfGroupoid( Ha4 ); B
  Aut(Ha4)
  @gapprompt|gap>B @gapinput|Agens := GeneratorsOfGroup( AHa4);; B
  @gapprompt|gap>B @gapinput|Length( Agens );B
  8
  @gapprompt|gap>B @gapinput|NHa4 := NiceObject( AHa4 );; B
  @gapprompt|gap>B @gapinput|MHa4 := NiceMonomorphism( AHa4 );; B
  @gapprompt|gap>B @gapinput|Size( AHa4 );    ## (3!)x24x(12^2)B
  20736
  @gapprompt|gap>B @gapinput|SetName( AHa4, "AHa4" ); B
  @gapprompt|gap>B @gapinput|SetName( NHa4, "NHa4" );B
  @gapprompt|gap>B @gapinput|## either of these names may be returnedB
  @gapprompt|gap>B @gapinput|names := [ "(((A4 x A4 x A4) : C2) : C3) : C2",B
  @gapprompt|>B @gapinput|   "(C2 x C2 x C2 x C2 x C2 x C2) : (((C3 x C3 x C3) : C3) : (C2 x C2))" ];;B
  @gapprompt|gap>B @gapinput|StructureDescription( NHa4 ) in names;B
  true
  @gapprompt|gap>B @gapinput|##  cannot test images of Agens because of random variations B
  @gapprompt|gap>B @gapinput|##  Now do some tests!B
  @gapprompt|gap>B @gapinput|mgi := MappingGeneratorsImages( MHa4 );; B
  @gapprompt|gap>B @gapinput|autgen := mgi[1];;B
  @gapprompt|gap>B @gapinput|pcgen := mgi[2];;B
  @gapprompt|gap>B @gapinput|ngen := Length( autgen );; B
  @gapprompt|gap>B @gapinput|ForAll( [1..ngen], i -> Order(autgen[i]) = Order(pcgen[i]) ); B
  true
  
\end{Verbatim}
 
\subsection{\textcolor{Chapter }{Inner automorphisms}}\label{subsec-inner-autos}
\logpage{[ 6, 1, 5 ]}
\hyperdef{L}{X7EC237ED7E1978B0}{}
{
  The inner automorphism subgroup $\mathrm{Inn}(G)$ \index{inner automorphism group@inner automorphism group} of the automorphism group of $G$ is the group of inner automorphisms $\wedge a : b \mapsto b^a$ for $a \in G$. It is \emph{not} the case that the map $G \to \mathrm{Inn}(G), a \mapsto \wedge a$ preserves multiplication. Indeed, when $a=(o,g,p), b=(p,h,r) \in G$ with objects $p,q,r$ all distict, then 
\[ \wedge(ab) ~=~ (\wedge a)(\wedge b)(\wedge a) ~=~ (\wedge b)(\wedge a)(\wedge
b). \]
 (Compare this with the permutation identity $(pq)(qr)(pq) = (pr) = (qr)(pq)(qr)$.) So the map $G \to \mathrm{Inn}(G)$ is of type \texttt{IsMappingWithObjectsByFunction}. 

 In the example we convert the automorphism group \texttt{AGa4} into a single object groupoid, and then define the inner automorphism map. 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@AHa40 := Groupoid( AHa4, [0] );|
  single piece groupoid: < Aut(Ha4), [ 0 ] >
  !gapprompt@gap>| !gapinput@conj := function(a) |
  !gapprompt@>| !gapinput@       return ArrowNC( Ha4, true, GroupoidInnerAutomorphism(Ha4,a), 0, 0 ); |
  !gapprompt@>| !gapinput@   end;; |
  !gapprompt@gap>| !gapinput@inner := MappingWithObjectsByFunction( Ha4, AHa40, conj, [0,0,0] );;|
  !gapprompt@gap>| !gapinput@a1 := Arrow( Ha4, (1,2,3), -14, -13 );;|
  !gapprompt@gap>| !gapinput@inner1 := ImageElm( inner, a1 );;                        |
  !gapprompt@gap>| !gapinput@a2 := Arrow( Ha4, (2,3,4), -13, -12 );;|
  !gapprompt@gap>| !gapinput@inner2 := ImageElm( inner, a2 );;       |
  !gapprompt@gap>| !gapinput@a3 := a1*a2;                      |
  [(1,3)(2,4) : -14 -> -12]
  !gapprompt@gap>| !gapinput@inner3 := ImageElm( inner, a3 );  |
  [groupoid homomorphism : Ha4 -> Ha4
  [ [ [(1,2,3) : -14 -> -14], [(2,3,4) : -14 -> -14], [() : -14 -> -13], 
        [() : -14 -> -12] ], 
    [ [(1,3,4) : -12 -> -12], [(1,2,4) : -12 -> -12], [(1,3)(2,4) : -12 -> -13],
        [() : -12 -> -14] ] ] : 0 -> 0]
  !gapprompt@gap>| !gapinput@(inner3 = inner1*inner2*inner1) and (inner3 = inner2*inner1*inner2);|
  true
  true
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{GroupoidAutomorphismByGroupAutos}}
\logpage{[ 6, 1, 6 ]}\nobreak
\hyperdef{L}{X80F9594481CA9FDE}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupoidAutomorphismByGroupAutos({\mdseries\slshape gpd, auts})\index{GroupoidAutomorphismByGroupAutos@\texttt{GroupoidAutomorphismByGroupAutos}}
\label{GroupoidAutomorphismByGroupAutos}
}\hfill{\scriptsize (operation)}}\\


 Homogeneous, discrete groupoids are the second type of groupoid for which a
method is provided for \texttt{AutomorphismGroupOfGroupoid}. This is used in the \textsf{XMod} package for constructing crossed modules of groupoids. The two types of
generating automorphism are \texttt{GroupoidAutomorphismByGroupAutos}, which requires a list of group automorphisms, one for each object group, and \texttt{GroupoidAutomorphismByObjectPerm}, which permutes the objects. So, if the object groups $g$ have automorphism group $\Aut(g)$ and there are $n$ objects, the autmorphism group of the groupoid has size $n!|\Aut(g)|^n$. 

 }

 
\begin{Verbatim}[commandchars=@|C,fontsize=\small,frame=single,label=Example]
  
  @gapprompt|gap>C @gapinput|Dd8 := HomogeneousDiscreteGroupoid( d8, [ -13..-10] ); C
  homogeneous, discrete groupoid: < d8, [ -13 .. -10 ] >
  @gapprompt|gap>C @gapinput|aut10 := GroupoidAutomorphismByObjectPerm( Dd8, [-12,-10,-11,-13] ); C
  groupoid homomorphism : morphism from a homogeneous discrete groupoid:
  [ -13, -12, -11, -10 ] -> [ -12, -10, -11, -13 ]
  object homomorphisms:
  IdentityMapping( d8 )
  IdentityMapping( d8 )
  IdentityMapping( d8 )
  IdentityMapping( d8 )
  @gapprompt|gap>C @gapinput|gend8 := GeneratorsOfGroup( d8 );; C
  @gapprompt|gap>C @gapinput|g1 := gend8[1];; C
  @gapprompt|gap>C @gapinput|g2 := gend8[2];;C
  @gapprompt|gap>C @gapinput|b1 := IdentityMapping( d8 );;C
  @gapprompt|gap>C @gapinput|b2 := GroupHomomorphismByImages( d8, d8, gend8, [g1, g2*g1 ] );; C
  @gapprompt|gap>C @gapinput|b3 := GroupHomomorphismByImages( d8, d8, gend8, [g1^g2, g2 ] );; C
  @gapprompt|gap>C @gapinput|b4 := GroupHomomorphismByImages( d8, d8, gend8, [g1^g2, g2^(g1*g2) ] );; C
  @gapprompt|gap>C @gapinput|aut11 := GroupoidAutomorphismByGroupAutos( Dd8, [b1,b2,b3,b4] ); C
  groupoid homomorphism : morphism from a homogeneous discrete groupoid:
  [ -13, -12, -11, -10 ] -> [ -13, -12, -11, -10 ]
  object homomorphisms:
  IdentityMapping( d8 )
  GroupHomomorphismByImages( d8, d8, [ (5,6,7,8), (5,7) ], 
  [ (5,6,7,8), (5,8)(6,7) ] )
  GroupHomomorphismByImages( d8, d8, [ (5,6,7,8), (5,7) ], [ (5,8,7,6), (5,7) ] )
  GroupHomomorphismByImages( d8, d8, [ (5,6,7,8), (5,7) ], [ (5,8,7,6), (6,8) ] )
  @gapprompt|gap>C @gapinput|ADd8 := AutomorphismGroupOfGroupoid( Dd8 ); C
  <group with 4 generators>
  @gapprompt|gap>C @gapinput|Size( ADd8 );    ## 4!*8^4C
  98304
  @gapprompt|gap>C @gapinput|genADd8 := GeneratorsOfGroup( ADd8 );;C
  @gapprompt|gap>C @gapinput|Length( genADd8 ); C
  4  
  @gapprompt|gap>C @gapinput|w := GroupoidAutomorphismByGroupAutos( Dd8, [b2,b1,b1,b1] );; C
  @gapprompt|gap>C @gapinput|x := GroupoidAutomorphismByGroupAutos( Dd8, [b3,b1,b1,b1] );; C
  @gapprompt|gap>C @gapinput|y := GroupoidAutomorphismByObjectPerm( Dd8, [ -12, -11, -10, -13 ] );; C
  @gapprompt|gap>C @gapinput|z := GroupoidAutomorphismByObjectPerm( Dd8, [ -12, -13, -11, -10 ] );; C
  @gapprompt|gap>C @gapinput|ok := ForAll( genADd8, a -> a in[ w, x, y, z ] ); C
  true
  @gapprompt|gap>C @gapinput|NADd8 := NiceObject( ADd8 );; C
  @gapprompt|gap>C @gapinput|MADd8 := NiceMonomorphism( ADd8 );;C
  @gapprompt|gap>C @gapinput|w1 := ImageElm( MADd8, w );; C
  @gapprompt|gap>C @gapinput|x1 := ImageElm( MADd8, x );; C
  @gapprompt|gap>C @gapinput|y1 := ImageElm( MADd8, y );; C
  @gapprompt|gap>C @gapinput|z1 := ImageElm( MADd8, z );; C
  @gapprompt|gap>C @gapinput|u := z*w*y*x*z; C
  groupoid homomorphism : morphism from a homogeneous discrete groupoid:
  [ -13, -12, -11, -10 ] -> [ -11, -13, -10, -12 ]
  object homomorphisms:
  IdentityMapping( d8 )
  GroupHomomorphismByImages( d8, d8, [ (5,6,7,8), (5,7) ], 
  [ (5,6,7,8), (5,8)(6,7) ] )
  IdentityMapping( d8 )
  GroupHomomorphismByImages( d8, d8, [ (5,6,7,8), (5,7) ], [ (5,8,7,6), (5,7) ] )
  @gapprompt|gap>C @gapinput|u1 := z1*w1*y1*x1*z1; C
  (1,2,4,3)(5,17,23,11,6,18,24,16)(7,19,25,15,9,21,27,13)(8,20,26,14,10,22,28,12)
  @gapprompt|gap>C @gapinput|imu := ImageElm( MADd8, u );; C
  @gapprompt|gap>C @gapinput|u1 = imu;C
  true
  
\end{Verbatim}
 

 

\subsection{\textcolor{Chapter }{AutomorphismGroupoidOfGroupoid}}
\logpage{[ 6, 1, 7 ]}\nobreak
\hyperdef{L}{X7A93C6507BC697CD}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AutomorphismGroupoidOfGroupoid({\mdseries\slshape gpd})\index{AutomorphismGroupoidOfGroupoid@\texttt{AutomorphismGroupoidOfGroupoid}}
\label{AutomorphismGroupoidOfGroupoid}
}\hfill{\scriptsize (attribute)}}\\


 If $G$ is a single piece groupoid with automorphism group $\Aut(G)$, and if $H$ is the union of $k$ pieces, all isomorphic to $G$, then the automorphism group of $H$ is the wreath product $S_k \ltimes \Aut(G)$. However, we find it more convenient to construct the \emph{automorphism groupoid} of $H$. This is a single piece groupoid $\AUT(H)$ with $k$ objects \texttt{\symbol{45}} the object lists of the pieces of $H$ \texttt{\symbol{45}} and root group $\Aut(G)$. Isomorphisms between the root groups of the $k$ pieces may be applied to the generators of $\Aut(G)$ to construct automorphism groups of these pieces, and then isomorphisms
between these automorphism groups. We then construct $\AUT(H)$ using \texttt{GroupoidByIsomorphisms}. 

 In the special case that $H$ is homogeneous, there is no need to construct a collection of automorphism
groups. Rather, the rays of $\AUT(H)$ are given by \texttt{IsomorphismNewObjects}. For the example we use \texttt{HGd8} constructed in subsection \texttt{HomogeneousGroupoid} (\ref{HomogeneousGroupoid}). 

 }

 
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=Example]
  
  @gapprompt|gap>B @gapinput|HGd8 := HomogeneousGroupoid( Gd8, B
  @gapprompt|>B @gapinput|               [ [-39,-38,-37], [-36,-35,-34], [-33,-32,-31] ] );;B
  @gapprompt|gap>B @gapinput|SetName( HGd8, "HGd8" );B
  @gapprompt|gap>B @gapinput|AHGd8 := AutomorphismGroupoidOfGroupoid( HGd8 ); B
  Aut(HGd8)
  @gapprompt|gap>B @gapinput|ObjectList( AHGd8 );B
  [ [ -39, -38, -37 ], [ -36, -35, -34 ], [ -33, -32, -31 ] ]
  @gapprompt|gap>B @gapinput|RaysOfGroupoid( AHGd8 ){[2..3]};B
  [ groupoid homomorphism : 
      [ [ [(5,6,7,8) : -39 -> -39], [(5,7) : -39 -> -39], [() : -39 -> -38], 
            [() : -39 -> -37] ], 
        [ [(5,6,7,8) : -36 -> -36], [(5,7) : -36 -> -36], [() : -36 -> -35], 
            [() : -36 -> -34] ] ], groupoid homomorphism : 
      [ [ [(5,6,7,8) : -39 -> -39], [(5,7) : -39 -> -39], [() : -39 -> -38], 
            [() : -39 -> -37] ], 
        [ [(5,6,7,8) : -33 -> -33], [(5,7) : -33 -> -33], [() : -33 -> -32], 
            [() : -33 -> -31] ] ] ]
  @gapprompt|gap>B @gapinput|obgp := ObjectGroup( AHGd8, [ -36, -35, -34 ] );; B
  @gapprompt|gap>B @gapinput|Size( obgp );    ## 3!*8^3B
  3072
  
\end{Verbatim}
 

 }

 
\section{\textcolor{Chapter }{Matrix representations of groupoids}}\label{sec-mxreps}
\logpage{[ 6, 2, 0 ]}
\hyperdef{L}{X8003AF117B956D16}{}
{
  \index{matrix representation@matrix representation} \index{representation by matrices@representation by matrices} Suppose that \texttt{gpd} is the direct product of a group $G$ and a complete digraph, and that $\rho : G \to M$ is an isomorphism to a matrix group $M$. Then, if \texttt{rep} is the isomorphic groupoid with the same objects and root group $M$, there is an isomorphism $\mu$ from \texttt{gpd} to \texttt{rep} mapping $(g : i \to j)$ to $(\rho g : i \to j)$. 

 When \texttt{gpd} is a groupoid with rays, a representation can be obtained by restricting a
representation of its parent. 

 
\begin{Verbatim}[commandchars=@|B,fontsize=\small,frame=single,label=Example]
  
  @gapprompt|gap>B @gapinput|reps := IrreducibleRepresentations( a4 );; B
  @gapprompt|gap>B @gapinput|rep4 := reps[4]; B
  Pcgs([ (2,4,3), (1,3)(2,4), (1,2)(3,4) ]) -> 
  [ [ [ 0, 0, 1 ], [ 1, 0, 0 ], [ 0, 1, 0 ] ], 
    [ [ -1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, -1 ] ], 
    [ [ 1, 0, 0 ], [ 0, -1, 0 ], [ 0, 0, -1 ] ] ]
  @gapprompt|gap>B @gapinput|Ra4 := Groupoid( Image( rep4 ), Ga4!.objects );; B
  @gapprompt|gap>B @gapinput|ObjectList( Ra4 ) = [ -15 .. -11 ];B
  true
  @gapprompt|gap>B @gapinput|gens := GeneratorsOfGroupoid( Ga4 );B
  [ [(1,2,3) : -15 -> -15], [(2,3,4) : -15 -> -15], [() : -15 -> -14],
    [() : -15 -> -13], [() : -15 -> -12], [() : -15 -> -11] ]
  @gapprompt|gap>B @gapinput|images := List( gens, B
  @gapprompt|>B @gapinput|       g -> Arrow( Ra4, ImageElm(rep4,g![2]), g![3], g![4] ) ); B
  [ [[ [ 0, 0, -1 ], [ 1, 0, 0 ], [ 0, -1, 0 ] ] : -15 -> -15], 
    [[ [ 0, 1, 0 ], [ 0, 0, 1 ], [ 1, 0, 0 ] ] : -15 -> -15], 
    [[ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ] : -15 -> -14], 
    [[ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ] : -15 -> -13], 
    [[ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ] : -15 -> -12], 
    [[ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ] : -15 -> -11] ]
  @gapprompt|gap>B @gapinput|mor := GroupoidHomomorphismFromSinglePiece( Ga4, Ra4, gens, images );
B
  groupoid homomorphism : 
  [ [ [(1,2,3) : -15 -> -15], [(2,3,4) : -15 -> -15], [() : -15 -> -14], 
        [() : -15 -> -13], [() : -15 -> -12], [() : -15 -> -11] ], 
    [ [[ [ 0, 0, -1 ], [ 1, 0, 0 ], [ 0, -1, 0 ] ] : -15 -> -15], 
        [[ [ 0, 1, 0 ], [ 0, 0, 1 ], [ 1, 0, 0 ] ] : -15 -> -15], 
        [[ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ] : -15 -> -14], 
        [[ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ] : -15 -> -13], 
        [[ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ] : -15 -> -12], 
        [[ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ] : -15 -> -11] ] ]
  @gapprompt|gap>B @gapinput|IsMatrixGroupoid( Ra4 ); B
  true
  @gapprompt|gap>B @gapinput|a := Arrow( Ha4, (1,4,2), -12, -13 );B
  [(1,4,2) : -12 -> -13]
  @gapprompt|gap>B @gapinput|ImageElm( mor, a );B
  [[ [ 0, 0, 1 ], [ -1, 0, 0 ], [ 0, -1, 0 ] ] : -12 -> -13]
  @gapprompt|gap>B @gapinput|rmor := RestrictedMappingGroupoids( mor, Ha4 );B
  groupoid homomorphism : 
  [ [ [(1,2,3) : -14 -> -14], [(2,3,4) : -14 -> -14], [() : -14 -> -13], 
        [() : -14 -> -12] ], 
    [ [[ [ 0, 0, -1 ], [ 1, 0, 0 ], [ 0, -1, 0 ] ] : -14 -> -14], 
        [[ [ 0, 1, 0 ], [ 0, 0, 1 ], [ 1, 0, 0 ] ] : -14 -> -14], 
        [[ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ] : -14 -> -13], 
        [[ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ] : -14 -> -12] ] ]
  @gapprompt|gap>B @gapinput|ParentMappingGroupoids( rmor ) = mor;B
  true
  
\end{Verbatim}
 

 }

 
\section{\textcolor{Chapter }{Groupoid actions}}\logpage{[ 6, 3, 0 ]}
\hyperdef{L}{X7DB8E7EF7A51F1BE}{}
{
  Recall from sections \ref{sec-conj} and \texttt{GroupoidInnerAutomorphism} (\ref{GroupoidInnerAutomorphism}) the notion of \emph{conjugation} in a groupoid, and the associated inner automorphisms. 

 It was mentioned there that the map $\wedge : G \to \Aut(G),~ a \to \wedge a$, is \emph{not} a groupoid homomorphism. It is in fact a \emph{groupoid action} \index{groupoid action} which we now define. Let $\{p,q,r,u,v\}$ be distinct objects in $G$ and let: 

 $a_1 = (c_1 : p \to q),~~ a_2 = (c_2 : q \to r),~~ a_3 = (c_3 : q \to p),~~ a_4
= (c_4 : u \to v)$, 

 $b_1 = (d_1 : p \to p),~~ b_2 = (d_2 : p \to p),~~ b_3 = (d_3 : q \to q),~~ b_4
= (c_3c_1 : q \to q)$ be arrows in $G$. Then the following \emph{conjugation identities} must be satisfied: \index{conjugation identities} 
\begin{itemize}
\item  $\wedge(a_1a_2) ~=~ (\wedge a_1)*(\wedge a_2)*(\wedge a_1) ~=~ (\wedge
a_2)*(\wedge a_1)*(\wedge a_2)$, 
\item  $\wedge(b_1a_1) ~=~ (\wedge b_1)*(\wedge a_1)*(\wedge b_1)^{-1}$, 
\item  $\wedge(a_1b_3) ~=~ (\wedge b_3)^{-1}*(\wedge a_1)*(\wedge b_3)$, 
\item  $\wedge(b_1b_2) ~=~ (\wedge b_1)*(\wedge b_2)$, 
\item  $\wedge(a_1a_3) ~=~ (\wedge a_1)*(\wedge a_3)*(\wedge b_4)$, 
\item  $(\wedge a_1)*(\wedge a_4) ~=~ (\wedge a_4)*(\wedge a_1)$. 
\end{itemize}
 

 In the following example we check the first of these identities in one
particular case. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@c1 := Arrow( Ha4, (1,2)(3,4), -14, -13);;|
  !gapprompt@gap>| !gapinput@innc1 := GroupoidInnerAutomorphism( Ha4, c1 );|
  groupoid homomorphism : Ha4 -> Ha4
  [ [ [(1,2,3) : -14 -> -14], [(2,3,4) : -14 -> -14], [() : -14 -> -13], 
        [() : -14 -> -12] ], 
    [ [(1,4,2) : -13 -> -13], [(1,4,3) : -13 -> -13], [() : -13 -> -14], 
        [(1,2)(3,4) : -13 -> -12] ] ]
  !gapprompt@gap>| !gapinput@c2 := Arrow( Ha4, (1,4,2), -13, -12);;|
  !gapprompt@gap>| !gapinput@innc2 := GroupoidInnerAutomorphism( Ha4, c2 );|
  groupoid homomorphism : Ha4 -> Ha4
  [ [ [(1,2,3) : -14 -> -14], [(2,3,4) : -14 -> -14], [() : -14 -> -13], 
        [() : -14 -> -12] ], 
    [ [(1,2,3) : -14 -> -14], [(2,3,4) : -14 -> -14], [(1,4,2) : -14 -> -12], 
        [(1,2,4) : -14 -> -13] ] ]
  !gapprompt@gap>| !gapinput@c12 := c1 * c2;|
  [(2,4,3) : -14 -> -12]
  !gapprompt@gap>| !gapinput@innc12 := GroupoidInnerAutomorphism( Ha4, c12 );|
  groupoid homomorphism : Ha4 -> Ha4
  [ [ [(1,2,3) : -14 -> -14], [(2,3,4) : -14 -> -14], [() : -14 -> -13], 
        [() : -14 -> -12] ], 
    [ [(1,4,2) : -12 -> -12], [(2,3,4) : -12 -> -12], [(2,3,4) : -12 -> -13], 
        [(2,4,3) : -12 -> -14] ] ]
  !gapprompt@gap>| !gapinput@[ innc1 * innc2 * innc1 = innc12, innc2 * innc1 * innc2 = innc12 ];|
  [ true, true ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{GroupoidActionByConjugation}}
\logpage{[ 6, 3, 1 ]}\nobreak
\hyperdef{L}{X7C4DCB287B3DD0CD}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupoidActionByConjugation({\mdseries\slshape gpd})\index{GroupoidActionByConjugation@\texttt{GroupoidActionByConjugation}}
\label{GroupoidActionByConjugation}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGroupoidAction({\mdseries\slshape map})\index{IsGroupoidAction@\texttt{IsGroupoidAction}}
\label{IsGroupoidAction}
}\hfill{\scriptsize (Category)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ActionMap({\mdseries\slshape act})\index{ActionMap@\texttt{ActionMap}}
\label{ActionMap}
}\hfill{\scriptsize (attribute)}}\\


 The operation \texttt{GroupoidInnerAutomorphism}, which produces the conjugation action of $G$ on itself, does satisfy the conjugation identities and so provides a standard
example of an action. 

 An action is a record with fields \texttt{Source}, \texttt{Range} and \texttt{ActionMap}. 

 The examples repeat those in section \texttt{GroupoidInnerAutomorphism} (\ref{GroupoidInnerAutomorphism}): firstly with a groupoid acting on itself. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@act1 := GroupoidActionByConjugation( Ha4 );|
  <general mapping: Ha4 -> Aut(Ha4) >
  !gapprompt@gap>| !gapinput@IsGroupoidAction( act1 );|
  true
  !gapprompt@gap>| !gapinput@amap1 := ActionMap( act1 );;|
  !gapprompt@gap>| !gapinput@amap1( h4 ) = inn1;|
  true
  
\end{Verbatim}
 Secondly with an action on a single piece, normal subgroupoid. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@act2 := GroupoidActionByConjugation( Ha4, Nk4 );|
  <general mapping: Ha4 -> Aut(Nk4) >
  !gapprompt@gap>| !gapinput@IsGroupoidAction( act2 );|
  true
  !gapprompt@gap>| !gapinput@amap2 := ActionMap( act2 );;|
  !gapprompt@gap>| !gapinput@amap2( e4 ) = inn2;|
  true
  
\end{Verbatim}
 Thirly with an action on a homogeneous, discrete subgroupoid. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@act3 := GroupoidActionByConjugation( Ha4, Ma4 );|
  <general mapping: Ha4 -> Aut(Ma4) >
  !gapprompt@gap>| !gapinput@IsGroupoidAction( act3 );|
  true
  !gapprompt@gap>| !gapinput@amap3 := ActionMap( act3 );;|
  !gapprompt@gap>| !gapinput@amap3( e4 ) = inn3;|
  true
  
\end{Verbatim}
 }

 }

  
\chapter{\textcolor{Chapter }{Graphs of Groups and Groupoids}}\label{chap-ggraph}
\logpage{[ 7, 0, 0 ]}
\hyperdef{L}{X78063DC8847554B4}{}
{
  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}}\label{sec-dgph}
\logpage{[ 7, 1, 0 ]}
\hyperdef{L}{X7D554C5D7FDC3D02}{}
{
  

\subsection{\textcolor{Chapter }{FpWeightedDigraph}}
\logpage{[ 7, 1, 1 ]}\nobreak
\hyperdef{L}{X85BD6D2584D8A22F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FpWeightedDigraph({\mdseries\slshape verts, arcs})\index{FpWeightedDigraph@\texttt{FpWeightedDigraph}}
\label{FpWeightedDigraph}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsFpWeightedDigraph({\mdseries\slshape dig})\index{IsFpWeightedDigraph@\texttt{IsFpWeightedDigraph}}
\label{IsFpWeightedDigraph}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{InvolutoryArcs({\mdseries\slshape 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\texttt{\symbol{45}}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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@V1 := [ 5, 6 ];;|
  !gapprompt@gap>| !gapinput@fg1 := FreeGroup( "y" );;|
  !gapprompt@gap>| !gapinput@y := fg1.1;;|
  !gapprompt@gap>| !gapinput@A1 := [ [ y, 5, 6 ], [ y^-1, 6, 5 ] ];|
  !gapprompt@gap>| !gapinput@D1 := FpWeightedDigraph( fg1, V1, A1 );|
  weighted digraph with vertices: [ 5, 6 ]
  and arcs: [ [ y, 5, 6 ], [ y^-1, 6, 5 ] ]
  !gapprompt@gap>| !gapinput@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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@fg3 := FreeGroup( 3, "z" );;|
  !gapprompt@gap>| !gapinput@z1 := fg3.1;;  z2 := fg3.2;;  z3 := fg3.3;;|
  !gapprompt@gap>| !gapinput@ob3 := [ 7, 8, 9 ];;|
  !gapprompt@gap>| !gapinput@A3 := [[z1,7,8],[z2,8,9],[z3,9,7],[z1^-1,8,7],[z2^-1,9,8],[z3^-1,7,9]];;|
  !gapprompt@gap>| !gapinput@D3 := FpWeightedDigraph( fg3, ob3, 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> inob3 := InvolutoryArcs( D3 );
  [ 4, 5, 6, 1, 2, 3 ]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Graphs of Groups}}\label{sec-gphgps}
\logpage{[ 7, 2, 0 ]}
\hyperdef{L}{X7BAFCA3680E478AE}{}
{
  

\subsection{\textcolor{Chapter }{GraphOfGroups}}
\logpage{[ 7, 2, 1 ]}\nobreak
\hyperdef{L}{X8130246E854BC5D9}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GraphOfGroups({\mdseries\slshape dig, gps, isos})\index{GraphOfGroups@\texttt{GraphOfGroups}}
\label{GraphOfGroups}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DigraphOfGraphOfGroups({\mdseries\slshape gg})\index{DigraphOfGraphOfGroups@\texttt{DigraphOfGraphOfGroups}}
\label{DigraphOfGraphOfGroups}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupsOfGraphOfGroups({\mdseries\slshape gg})\index{GroupsOfGraphOfGroups@\texttt{GroupsOfGraphOfGroups}}
\label{GroupsOfGraphOfGroups}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsomorphismsOfGraphOfGroups({\mdseries\slshape gg})\index{IsomorphismsOfGraphOfGroups@\texttt{IsomorphismsOfGraphOfGroups}}
\label{IsomorphismsOfGraphOfGroups}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGraphOfGroups({\mdseries\slshape dig})\index{IsGraphOfGroups@\texttt{IsGraphOfGroups}}
\label{IsGraphOfGroups}
}\hfill{\scriptsize (Category)}}\\


 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 three attributes provide a means of calling the three 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 in Section \ref{sec-fpahnn}. 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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@## free vertex group at 5|
  !gapprompt@gap>| !gapinput@fa := FreeGroup( "a" );;|
  !gapprompt@gap>| !gapinput@a := fa.1;;|
  !gapprompt@gap>| !gapinput@SetName( fa, "fa" );|
  !gapprompt@gap>| !gapinput@hy := Subgroup( fa, [a^3] );;|
  !gapprompt@gap>| !gapinput@SetName( hy, "hy" );|
  !gapprompt@gap>| !gapinput@## free vertex group at 6|
  !gapprompt@gap>| !gapinput@fb := FreeGroup( "b" );;|
  !gapprompt@gap>| !gapinput@b := fb.1;;|
  !gapprompt@gap>| !gapinput@SetName( fb, "fb" );|
  !gapprompt@gap>| !gapinput@hybar := Subgroup( fb, [b^2] );;|
  !gapprompt@gap>| !gapinput@SetName( hybar, "hybar" );|
  !gapprompt@gap>| !gapinput@## isomorphisms between subgroups|
  !gapprompt@gap>| !gapinput@homy := GroupHomomorphismByImagesNC( hy, hybar, [a^3], [b^2] );;|
  !gapprompt@gap>| !gapinput@homybar := GroupHomomorphismByImagesNC( hybar, hy, [b^2], [a^3] );;|
  !gapprompt@gap>| !gapinput@## defining graph of groups G1|
  !gapprompt@gap>| !gapinput@G1 := GraphOfGroups( D1, [fa,fb], [homy,homybar] );|
  Graph of Groups: 2 vertices; 2 arcs; groups [ fa, fb ]
  !gapprompt@gap>| !gapinput@Display( G1 );|
  Graph of Groups with :-
      vertices: [ 5, 6 ]
          arcs: [ [ y, 5, 6 ], [ y^-1, 6, 5 ] ]
        groups: [ fa, fb ]
  isomorphisms: [ [ [ a^3 ], [ b^2 ] ], [ [ b^2 ], [ a^3 ] ] ]
  !gapprompt@gap>| !gapinput@IsGraphOfGroups( G1 );|
  true
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsGraphOfFpGroups}}
\logpage{[ 7, 2, 2 ]}\nobreak
\hyperdef{L}{X847464677F641527}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGraphOfFpGroups({\mdseries\slshape gg})\index{IsGraphOfFpGroups@\texttt{IsGraphOfFpGroups}}
\label{IsGraphOfFpGroups}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGraphOfPcGroups({\mdseries\slshape gg})\index{IsGraphOfPcGroups@\texttt{IsGraphOfPcGroups}}
\label{IsGraphOfPcGroups}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGraphOfPermGroups({\mdseries\slshape 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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@IsGraphOfFpGroups( G1 );|
  true
  !gapprompt@gap>| !gapinput@IsomorphismsOfGraphOfGroups( G1 );|
  [ [ a^3 ] -> [ b^2 ], [ b^2 ] -> [ a^3 ] ]
  
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{RightTransversalsOfGraphOfGroups}}
\logpage{[ 7, 2, 3 ]}\nobreak
\hyperdef{L}{X7B036C2B84E48BB1}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RightTransversalsOfGraphOfGroups({\mdseries\slshape gg})\index{RightTransversalsOfGraphOfGroups@\texttt{RightTransversalsOfGraphOfGroups}}
\label{RightTransversalsOfGraphOfGroups}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LeftTransversalsOfGraphOfGroups({\mdseries\slshape 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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@RTG1 := RightTransversalsOfGraphOfGroups( G1 );|
  [ [ <identity ...>, a, a^2 ], [ <identity ...>, b ] ]
  !gapprompt@gap>| !gapinput@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}}\label{sec-words}
\logpage{[ 7, 3, 0 ]}
\hyperdef{L}{X7BD9DCF87FB3E0AF}{}
{
  

\subsection{\textcolor{Chapter }{GraphOfGroupsWord}}
\logpage{[ 7, 3, 1 ]}\nobreak
\hyperdef{L}{X87937AE47C5B1018}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GraphOfGroupsWord({\mdseries\slshape gg, tv, list})\index{GraphOfGroupsWord@\texttt{GraphOfGroupsWord}}
\label{GraphOfGroupsWord}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGraphOfGroupsWord({\mdseries\slshape w})\index{IsGraphOfGroupsWord@\texttt{IsGraphOfGroupsWord}}
\label{IsGraphOfGroupsWord}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GraphOfGroupsOfWord({\mdseries\slshape w})\index{GraphOfGroupsOfWord@\texttt{GraphOfGroupsOfWord}}
\label{GraphOfGroupsOfWord}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WordOfGraphOfGroupsWord({\mdseries\slshape w})\index{WordOfGraphOfGroupsWord@\texttt{WordOfGraphOfGroupsWord}}
\label{WordOfGraphOfGroupsWord}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{TailOfGraphOfGroupsWord({\mdseries\slshape w})\index{TailOfGraphOfGroupsWord@\texttt{TailOfGraphOfGroupsWord}}
\label{TailOfGraphOfGroupsWord}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HeadOfGraphOfGroupsWord({\mdseries\slshape w})\index{HeadOfGraphOfGroupsWord@\texttt{HeadOfGraphOfGroupsWord}}
\label{HeadOfGraphOfGroupsWord}
}\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\texttt{\symbol{94}}\texttt{\symbol{45}}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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@L1 := [ a^7, 1, b^-6, 2, a^-11, 1, b^9, 2, a^7 ];;|
  !gapprompt@gap>| !gapinput@gw1 := GraphOfGroupsWord( G1, 5, L1 );|
  (5)a^7.y.b^-6.y^-1.a^-11.y.b^9.y^-1.a^7(5)
  !gapprompt@gap>| !gapinput@IsGraphOfGroupsWord( gw1 );|
  true
  !gapprompt@gap>| !gapinput@[ TailOfGraphOfGroupsWord(gw1), HeadOfGraphOfGroupsWord(gw1) ];|
  [ 5, 5 ]
  !gapprompt@gap>| !gapinput@GraphOfGroupsOfWord(gw1);|
  Graph of Groups: 2 vertices; 2 arcs; groups [ fa, fb ]
  !gapprompt@gap>| !gapinput@WordOfGraphOfGroupsWord( gw1 );|
  [ a^7, 1, b^-6, 2, a^-11, 1, b^9, 2, a^7 ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{ReducedGraphOfGroupsWord}}
\logpage{[ 7, 3, 2 ]}\nobreak
\hyperdef{L}{X78FA7C3F831AA6E4}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ReducedGraphOfGroupsWord({\mdseries\slshape w})\index{ReducedGraphOfGroupsWord@\texttt{ReducedGraphOfGroupsWord}}
\label{ReducedGraphOfGroupsWord}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsReducedGraphOfGroupsWord({\mdseries\slshape 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\texttt{\symbol{45}}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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@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}}\label{sec-fpahnn}
\logpage{[ 7, 4, 0 ]}
\hyperdef{L}{X7D99A7B37B36BAA8}{}
{
  

\subsection{\textcolor{Chapter }{FreeProductWithAmalgamation}}
\logpage{[ 7, 4, 1 ]}\nobreak
\hyperdef{L}{X795AB71F7E370119}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FreeProductWithAmalgamation({\mdseries\slshape gp1, gp2, iso})\index{FreeProductWithAmalgamation@\texttt{FreeProductWithAmalgamation}}
\label{FreeProductWithAmalgamation}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FreeProductWithAmalgamationInfo({\mdseries\slshape fpa})\index{FreeProductWithAmalgamationInfo@\texttt{FreeProductWithAmalgamationInfo}}
\label{FreeProductWithAmalgamationInfo}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsFreeProductWithAmalgamation({\mdseries\slshape fpa})\index{IsFreeProductWithAmalgamation@\texttt{IsFreeProductWithAmalgamation}}
\label{IsFreeProductWithAmalgamation}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GraphOfGroupsRewritingSystem({\mdseries\slshape fpa})\index{GraphOfGroupsRewritingSystem@\texttt{GraphOfGroupsRewritingSystem}}
\label{GraphOfGroupsRewritingSystem}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NormalFormGGRWS({\mdseries\slshape fpa, word})\index{NormalFormGGRWS@\texttt{NormalFormGGRWS}}
\label{NormalFormGGRWS}
}\hfill{\scriptsize (attribute)}}\\


 As we have seen with the trefoil group example in Section \ref{sec-gphgps}, 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\texttt{\symbol{45}}groups, the operation \texttt{FreeProductWithAmalgamation} constructs the required fp\texttt{\symbol{45}}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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@## set up the first group s3 and a subgroup c3=<a1>|
  !gapprompt@gap>| !gapinput@fg2 := FreeGroup( 2, "a" );;|
  !gapprompt@gap>| !gapinput@rel1 := [ fg2.1^3, fg2.2^2, (fg2.1*fg2.2)^2 ];;|
  !gapprompt@gap>| !gapinput@s3 := fg2/rel1;;|
  !gapprompt@gap>| !gapinput@gs3 := GeneratorsOfGroup(s3);;|
  !gapprompt@gap>| !gapinput@SetName( s3, "s3" );|
  !gapprompt@gap>| !gapinput@a1 := gs3[1];;  a2 := gs3[2];;|
  !gapprompt@gap>| !gapinput@H1 := Subgroup(s3,[a1]);;|
  !gapprompt@gap>| !gapinput@## then the second group a4 and subgroup c3=<b1>|
  !gapprompt@gap>| !gapinput@f2 := FreeGroup( 2, "b" );;|
  !gapprompt@gap>| !gapinput@rel2 := [ f2.1^3, f2.2^3, (f2.1*f2.2)^2 ];;|
  !gapprompt@gap>| !gapinput@a4 := f2/rel2;;|
  !gapprompt@gap>| !gapinput@ga4 := GeneratorsOfGroup(a4);;|
  !gapprompt@gap>| !gapinput@SetName( a4, "a4" );|
  !gapprompt@gap>| !gapinput@b1 := ga4[1];  b2 := ga4[2];;|
  !gapprompt@gap>| !gapinput@H2 := Subgroup(a4,[b1]);;|
  !gapprompt@gap>| !gapinput@## form the isomorphism and the fpa group|
  !gapprompt@gap>| !gapinput@iso := GroupHomomorphismByImages(H1,H2,[a1],[b1]);;|
  !gapprompt@gap>| !gapinput@inv := InverseGeneralMapping(iso);;|
  !gapprompt@gap>| !gapinput@fpa := FreeProductWithAmalgamation( s3, a4, iso );|
  <fp group on the generators [ f1, f2, f3, f4 ]>
  !gapprompt@gap>| !gapinput@RelatorsOfFpGroup( fpa );|
  [ f1^2, f2^3, (f2*f1)^2, f3^3, f4^3, (f4*f3)^2, f2*f3^-1 ]
  !gapprompt@gap>| !gapinput@gg1 := GraphOfGroupsRewritingSystem( fpa );;|
  !gapprompt@gap>| !gapinput@Display( gg1 );|
  Graph of Groups with :- 
      vertices: [ 5, 6 ]
          arcs: [ [ y, 5, 6 ], [ y^-1, 6, 5 ] ]
        groups: [ s3, a4 ]
  isomorphisms: [ [ [ a1 ], [ b1 ] ], [ [ b1 ], [ a1 ] ] ]
  !gapprompt@gap>| !gapinput@LeftTransversalsOfGraphOfGroups( gg1 );|
  [ [ <identity ...>, a2^-1 ], [ <identity ...>, b2^-1, b1^-1*b2^-1, b1*b2^-1 ] 
   ]
  !gapprompt@gap>| !gapinput@gfpa := GeneratorsOfGroup( fpa );;|
  !gapprompt@gap>| !gapinput@w2 := (gfpa[1]*gfpa[2]*gfpa[3]^gfpa[4])^3;|
  (f1*f2*f4^-1*f3*f4)^3
  !gapprompt@gap>| !gapinput@n2 := NormalFormGGRWS( fpa, w2 );|
  f2*f3*(f4^-1*f2)^2*f4^-1*f3
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{ReducedImageElm}}
\logpage{[ 7, 4, 2 ]}\nobreak
\hyperdef{L}{X86F5F9787E3644FD}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ReducedImageElm({\mdseries\slshape hom, eml})\index{ReducedImageElm@\texttt{ReducedImageElm}}
\label{ReducedImageElm}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsMappingToGroupWithGGRWS({\mdseries\slshape map})\index{IsMappingToGroupWithGGRWS@\texttt{IsMappingToGroupWithGGRWS}}
\label{IsMappingToGroupWithGGRWS}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Embedding({\mdseries\slshape fpa, num})\index{Embedding@\texttt{Embedding}!for fpa-groups}
\label{Embedding:for fpa-groups}
}\hfill{\scriptsize (method)}}\\


 All fpa\texttt{\symbol{45}}groups are provided with a record attribute, \texttt{FreeProductWithAmalgamationInfo(fpa)} which is a record storing the groups, subgroups and isomorphism involved in
their construction. This information record also contains the embeddings of
the two groups into the product. The operation \texttt{ReducedImageElm}, applied to a homomorphism $h$ of type \texttt{IsMappingToGroupWithGGRWS} and an element $x$ of the source, finds the usual \texttt{ImageElm(h,x)} and then reduces this to its normal form using the graph of groups rewriting
system. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@fpainfo;|
  rec( embeddings := [ [ a2, a1 ] -> [ f1, f2 ], [ b1, b2 ] -> [ f3, f4 ] ], 
    groups := [ s3, a4 ], isomorphism := [ a1 ] -> [ b1 ], 
    positions := [ [ 1, 2 ], [ 3, 4 ] ], 
    subgroups := [ Group([ a1 ]), Group([ b1 ]) ] )
  !gapprompt@gap>| !gapinput@emb2 := Embedding( fpa, 2 );|
  [ b1, b2 ] -> [ f3, f4 ]
  !gapprompt@gap>| !gapinput@ImageElm( emb2, b1^b2 );       |
  f4^-1*f3*f4
  !gapprompt@gap>| !gapinput@ReducedImageElm( emb2, b1^b2 );|
  f4*f3^-1
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{HnnExtension}}
\logpage{[ 7, 4, 3 ]}\nobreak
\hyperdef{L}{X7CB0F120804A8DED}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HnnExtension({\mdseries\slshape gp, iso})\index{HnnExtension@\texttt{HnnExtension}}
\label{HnnExtension}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HnnExtensionInfo({\mdseries\slshape gp, iso})\index{HnnExtensionInfo@\texttt{HnnExtensionInfo}}
\label{HnnExtensionInfo}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsHnnExtension({\mdseries\slshape hnn})\index{IsHnnExtension@\texttt{IsHnnExtension}}
\label{IsHnnExtension}
}\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\texttt{\symbol{45}}groups as well as to
fpa\texttt{\symbol{45}}groups. 

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

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@H3 := Subgroup(a4,[b2]);;|
  !gapprompt@gap>| !gapinput@i23 := GroupHomomorphismByImages( H2, H3, [b1], [b2] );;|
  !gapprompt@gap>| !gapinput@hnn := HnnExtension( a4, i23 );|
  <fp group on the generators [ fe1, fe2, fe3 ]> 
  !gapprompt@gap>| !gapinput@phnn := PresentationFpGroup( hnn );;|
  !gapprompt@gap>| !gapinput@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 ] 
  !gapprompt@gap>| !gapinput@gg2 := GraphOfGroupsRewritingSystem( hnn );|
  Graph of Groups: 1 vertices; 2 arcs; groups [ a4 ]
  !gapprompt@gap>| !gapinput@LeftTransversalsOfGraphOfGroups( gg2 );|
  [ [ <identity ...>, b2^-1, b1^-1*b2^-1, b1*b2^-1 ],
    [ <identity ...>, b1^-1, b1, b2^-1*b1 ] ]
  !gapprompt@gap>| !gapinput@gh := GeneratorsOfGroup( hnn );;|
  !gapprompt@gap>| !gapinput@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)^2*fe3*fe2
  !gapprompt@gap>| !gapinput@n3 := NormalFormGGRWS( hnn, w3 );|
  (fe2*fe1*fe3)^2
  
\end{Verbatim}
 As with fpa\texttt{\symbol{45}}groups, hnn\texttt{\symbol{45}}groups are
provided with a record attribute, \texttt{HnnExtensionInfo(hnn)}, storing the group, subgroups and isomorphism involved in their construction. 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@hnninfo := HnnExtensionInfo( hnn );|
  rec( embeddings := [ [ b1, b2 ] -> [ fe1, fe2 ] ], group := a4, 
    isomorphism := [ b1 ] -> [ b2 ], 
    subgroups := [ Group([ b1 ]), Group([ b2 ]) ] )
  !gapprompt@gap>| !gapinput@emb := Embedding( hnn, 1 );|
  [ b1, b2 ] -> [ fe1, fe2 ]
  !gapprompt@gap>| !gapinput@ImageElm( emb, b1^b2 );       |
  fe2^-1*fe1*fe2
  !gapprompt@gap>| !gapinput@ReducedImageElm( emb, b1^b2 );|
  fe2*fe1^-1
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{GraphsOfGroupoids and their Words}}\label{sec-gphgpds}
\logpage{[ 7, 5, 0 ]}
\hyperdef{L}{X78108FB4814AE887}{}
{
  

\subsection{\textcolor{Chapter }{GraphOfGroupoids}}
\logpage{[ 7, 5, 1 ]}\nobreak
\hyperdef{L}{X8739267678808E85}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GraphOfGroupoids({\mdseries\slshape dig, gpds, subgpds, isos})\index{GraphOfGroupoids@\texttt{GraphOfGroupoids}}
\label{GraphOfGroupoids}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGraphOfPermGroupoids({\mdseries\slshape gg})\index{IsGraphOfPermGroupoids@\texttt{IsGraphOfPermGroupoids}}
\label{IsGraphOfPermGroupoids}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGraphOfFpGroupoids({\mdseries\slshape gg})\index{IsGraphOfFpGroupoids@\texttt{IsGraphOfFpGroupoids}}
\label{IsGraphOfFpGroupoids}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GroupoidsOfGraphOfGroupoids({\mdseries\slshape gg})\index{GroupoidsOfGraphOfGroupoids@\texttt{GroupoidsOfGraphOfGroupoids}}
\label{GroupoidsOfGraphOfGroupoids}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DigraphOfGraphOfGroupoids({\mdseries\slshape gg})\index{DigraphOfGraphOfGroupoids@\texttt{DigraphOfGraphOfGroupoids}}
\label{DigraphOfGraphOfGroupoids}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SubgroupoidsOfGraphOfGroupoids({\mdseries\slshape gg})\index{SubgroupoidsOfGraphOfGroupoids@\texttt{SubgroupoidsOfGraphOfGroupoids}}
\label{SubgroupoidsOfGraphOfGroupoids}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsomorphismsOfGraphOfGroupoids({\mdseries\slshape gg})\index{IsomorphismsOfGraphOfGroupoids@\texttt{IsomorphismsOfGraphOfGroupoids}}
\label{IsomorphismsOfGraphOfGroupoids}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RightTransversalsOfGraphOfGroupoids({\mdseries\slshape gg})\index{RightTransversalsOfGraphOfGroupoids@\texttt{RightTransversalsOfGraphOfGroupoids}}
\label{RightTransversalsOfGraphOfGroupoids}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LeftTransversalsOfGraphOfGroupoids({\mdseries\slshape gg})\index{LeftTransversalsOfGraphOfGroupoids@\texttt{LeftTransversalsOfGraphOfGroupoids}}
\label{LeftTransversalsOfGraphOfGroupoids}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGraphOfGroupoids({\mdseries\slshape dig})\index{IsGraphOfGroupoids@\texttt{IsGraphOfGroupoids}}
\label{IsGraphOfGroupoids}
}\hfill{\scriptsize (Category)}}\\


 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 constituent 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\texttt{\symbol{45}}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}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Gfa := SinglePieceGroupoid( fa, [-2,-1] );;|
  !gapprompt@gap>| !gapinput@ofa := One( fa );;|
  !gapprompt@gap>| !gapinput@SetName( Gfa, "Gfa" );|
  !gapprompt@gap>| !gapinput@Uhy := Subgroupoid( Gfa, [ [ hy, [-2,-1] ] ] );;|
  !gapprompt@gap>| !gapinput@SetName( Uhy, "Uhy" );|
  !gapprompt@gap>| !gapinput@Gfb := SinglePieceGroupoid( fb, [-4,-3] );;|
  !gapprompt@gap>| !gapinput@ofb := One( fb );;|
  !gapprompt@gap>| !gapinput@SetName( Gfb, "Gfb" );|
  !gapprompt@gap>| !gapinput@Uhybar := Subgroupoid( Gfb, [ [ hybar, [-4,-3] ] ] );;|
  !gapprompt@gap>| !gapinput@SetName( Uhybar, "Uhybar" );|
  !gapprompt@gap>| !gapinput@gens := GeneratorsOfGroupoid( Uhy );; |
  !gapprompt@gap>| !gapinput@gensbar := GeneratorsOfGroupoid( Uhybar );;|
  !gapprompt@gap>| !gapinput@mory := GroupoidHomomorphismFromSinglePiece( |
  !gapprompt@>| !gapinput@               Uhy, Uhybar, gens, gensbar );|
  groupoid homomorphism : Uhy -> Uhybar
  [ [ [a^3 : -2 -> -2], [<identity ...> : -2 -> -1] ], 
    [ [b^2 : -4 -> -4], [<identity ...> : -4 -> -3] ] ]
  !gapprompt@gap>| !gapinput@morybar := InverseGeneralMapping( mory );|
  groupoid homomorphism : Uhybar -> Uhy
  [ [ [b^2 : -4 -> -4], [<identity ...> : -4 -> -3] ], 
    [ [a^3 : -2 -> -2], [<identity ...> : -2 -> -1] ] ]
  !gapprompt@gap>| !gapinput@gg3 := GraphOfGroupoids( D1, [Gfa,Gfb], [Uhy,Uhybar], [mory,morybar] );;|
  !gapprompt@gap>| !gapinput@Display( gg3 );|
  Graph of Groupoids with :- 
      vertices: [ 5, 6 ]
          arcs: [ [ y, 5, 6 ], [ y^-1, 6, 5 ] ]
     groupoids: 
  fp single piece groupoid: Gfa
    objects: [ -2, -1 ]
      group: fa = <[ a ]>
  fp single piece groupoid: Gfb
    objects: [ -4, -3 ]
      group: fb = <[ b ]>
  subgroupoids: single piece groupoid: Uhy
    objects: [ -2, -1 ]
      group: hy = <[ a^3 ]>
  single piece groupoid: Uhybar
    objects: [ -4, -3 ]
      group: hybar = <[ b^2 ]>
  isomorphisms: [ groupoid homomorphism : Uhy -> Uhybar
      [ [ [a^3 : -2 -> -2], [<identity ...> : -2 -> -1] ], 
        [ [b^2 : -4 -> -4], [<identity ...> : -4 -> -3] ] ], 
    groupoid homomorphism : Uhybar -> Uhy
      [ [ [b^2 : -4 -> -4], [<identity ...> : -4 -> -3] ], 
        [ [a^3 : -2 -> -2], [<identity ...> : -2 -> -1] ] ] ]
  !gapprompt@gap>| !gapinput@IsGraphOfGroupoids( gg3 );|
  true
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{GraphOfGroupoidsWord}}
\logpage{[ 7, 5, 2 ]}\nobreak
\hyperdef{L}{X7EC1A9067FC91255}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GraphOfGroupoidsWord({\mdseries\slshape gg, tv, list})\index{GraphOfGroupoidsWord@\texttt{GraphOfGroupoidsWord}}
\label{GraphOfGroupoidsWord}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsGraphOfGroupoidsWord({\mdseries\slshape w})\index{IsGraphOfGroupoidsWord@\texttt{IsGraphOfGroupoidsWord}}
\label{IsGraphOfGroupoidsWord}
}\hfill{\scriptsize (property)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GraphOfGroupoidsOfWord({\mdseries\slshape w})\index{GraphOfGroupoidsOfWord@\texttt{GraphOfGroupoidsOfWord}}
\label{GraphOfGroupoidsOfWord}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WordOfGraphOfGroupoidsWord({\mdseries\slshape w})\index{WordOfGraphOfGroupoidsWord@\texttt{WordOfGraphOfGroupoidsWord}}
\label{WordOfGraphOfGroupoidsWord}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ReducedGraphOfGroupoidsWord({\mdseries\slshape w})\index{ReducedGraphOfGroupoidsWord@\texttt{ReducedGraphOfGroupoidsWord}}
\label{ReducedGraphOfGroupoidsWord}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsReducedGraphOfGroupoidsWord({\mdseries\slshape 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. Analogous to the word $a^7b^{-6}a^{-11}b^9a^7$ in subsection \texttt{ReducedGraphOfGroupsWord} (\ref{ReducedGraphOfGroupsWord}) we shall consider 
\[ (a^7 : -1 \to -2)~(b^{-6} : -4 \to -4 )~(a^{-11} : -2 \to -1)~ (b^9 : -3 \to
-4)~(a^7 : -2 \to -1). \]
 Compare the normal form \texttt{nw3} below with the normal form \texttt{nw1} above. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@f1 := Arrow( Gfa, a^7, -1, -2);;|
  !gapprompt@gap>| !gapinput@f2 := Arrow( Gfb, b^-6, -4, -4 );;|
  !gapprompt@gap>| !gapinput@f3 := Arrow( Gfa, a^-11, -2, -1 );;|
  !gapprompt@gap>| !gapinput@f4 := Arrow( Gfb, b^9, -3, -4 );;|
  !gapprompt@gap>| !gapinput@f5 := Arrow( Gfa, a^7, -2, -2 );;|
  !gapprompt@gap>| !gapinput@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 -> -2] ]
  !gapprompt@gap>| !gapinput@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 -> -2](5)
  !gapprompt@gap>| !gapinput@nw3 := ReducedGraphOfGroupoidsWord( gw3 );|
  (5)[a^-1 : -1 -> -1].y.[b^-1 : -3 -> -3].y^-1.[a^10 : -1 -> -2](5)
  
\end{Verbatim}
 The reduction proceeds as follows. 
\begin{itemize}
\item  $ [a^7 : -1 \to -2] = [a^{-2} : -1 \to -1]*[a^9 : -1 \to -2] \stackrel{y}{\to}
[a^{-2} : -1 \to -1]*[b^6 : -3 \to -4] $ 
\item  $ [b^6 : -3 \to -4]*[b^{-6} : -4 \to -4] = [\mathrm{id} : -3 \to -4]
\stackrel{\bar{y}}{\to} [\mathrm{id} : -1 \to -2] $ 
\item  $ [a^{-2} : -1 \to -1]*[\mathrm{id} : -1 \to -2]*[a^{-11} : -2 \to -1] =
[a^{-13} : -1 \to -1] $ 
\item  $ [a^{-13} : -1 \to -1] = [a^{-1} : -1 \to -1]*[a^{-12} : -1 \to -1]
\stackrel{y}{\to} [a^{-1} : -1 \to -1]*[b^{-8} : -3 \to -3] $ 
\item  $ [b^{-8} : -3 \to -3]*[b^9 : -3 \to -4] = [b^{-1} : -3 \to -3]*[b^2 : -3 \to
-4] \stackrel{\bar{y}}{\to} [b^{-1} : -3 \to -3]*[a^3 : -1 \to -2] $ 
\item  $ [a^3 := -1 \to -2]*[a^7 : -2 \to -2] = [a^{10} : -1 \to -2] $ 
\end{itemize}
 So the resulting word is $~(a^{-1} : -1, -1)(b^{-1} : -3, -3)(a^{10} : -1, -2)$. Notice that all the arrows except the final one are loops. }

 }

  
\chapter{\textcolor{Chapter }{Double Groupoids}}\label{chap-double}
\logpage{[ 8, 0, 0 ]}
\hyperdef{L}{X83B7E8A287C9284A}{}
{
  A \emph{double groupoid} is a \emph{double category} in which all the category structures are groupoids. For the most general type
of double groupoid there is also an associated pre\texttt{\symbol{45}}crossed
module. In this package we consider only \emph{basic double groupoids}, which do not involve pre\texttt{\symbol{45}}crossed modules. The more
general case will be discussed in the \textsf{XMod} package. 

 In a double groupoid, as well as objects and arrows, we need a set of \emph{squares}. A square is bounded by four arrows, two horizontal and two vertical, and
there is a \emph{horizontal} groupoid structure and a \emph{vertical} groupoid structure on these squares. 

 Double groupoids can be considered where the vertical arrows come from one
groupoid, and the horizontal arrows from another. The double groupoids
constructed here are special in that all four arrows come from the same
groupoid. We call these \emph{edge\texttt{\symbol{45}}symmetric} double groupoids. 

 This addition to the package is very experimental, and will be extended as
time permits. 
\section{\textcolor{Chapter }{Single piece double groupoids}}\label{sec-sdgpd}
\logpage{[ 8, 1, 0 ]}
\hyperdef{L}{X780DA94780938851}{}
{
  

\subsection{\textcolor{Chapter }{SinglePieceBasicDoubleGroupoid}}
\logpage{[ 8, 1, 1 ]}\nobreak
\hyperdef{L}{X7F5D722C83CB9139}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SinglePieceBasicDoubleGroupoid({\mdseries\slshape gpd})\index{SinglePieceBasicDoubleGroupoid@\texttt{SinglePieceBasicDoubleGroupoid}}
\label{SinglePieceBasicDoubleGroupoid}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DoubleGroupoid({\mdseries\slshape args})\index{DoubleGroupoid@\texttt{DoubleGroupoid}}
\label{DoubleGroupoid}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsDoubleGroupoid({\mdseries\slshape mwo})\index{IsDoubleGroupoid@\texttt{IsDoubleGroupoid}}
\label{IsDoubleGroupoid}
}\hfill{\scriptsize (Category)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsBasicDoubleGroupoid({\mdseries\slshape dgpd})\index{IsBasicDoubleGroupoid@\texttt{IsBasicDoubleGroupoid}}
\label{IsBasicDoubleGroupoid}
}\hfill{\scriptsize (Category)}}\\


 Let $G$ be a connected groupoid with object set $\Omega$. The double groupoid $\Box(G)$ on $G$ is constructed by the operation \texttt{SinglePieceBasicDoubleGroupoid(G)}. 

 The global function \texttt{DoubleGroupoid} may be used instead of this operation, and will work with various other input
parameters. 

 }

 
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=Example]
  
  @gapprompt|gap>A @gapinput|DGd8 := SinglePieceBasicDoubleGroupoid( Gd8 );; A
  @gapprompt|gap>A @gapinput|DGd8!.groupoid;A
  Gd8
  @gapprompt|gap>A @gapinput|DGd8!.objects;A
  [ -9, -8, -7 ]
  @gapprompt|gap>A @gapinput|SetName( DGd8, "DGd8" );A
  @gapprompt|gap>A @gapinput|[ IsDoubleGroupoid( DGd8 ), IsBasicDoubleGroupoid( DGd8 ) ];A
  [ true, true ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{SquareOfArrows}}
\logpage{[ 8, 1, 2 ]}\nobreak
\hyperdef{L}{X823A3A7481B90EB7}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SquareOfArrows({\mdseries\slshape gpd, up, lt, rt, dn})\index{SquareOfArrows@\texttt{SquareOfArrows}}
\label{SquareOfArrows}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{UpArrow({\mdseries\slshape sq})\index{UpArrow@\texttt{UpArrow}}
\label{UpArrow}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LeftArrow({\mdseries\slshape sq})\index{LeftArrow@\texttt{LeftArrow}}
\label{LeftArrow}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RightArrow({\mdseries\slshape sq})\index{RightArrow@\texttt{RightArrow}}
\label{RightArrow}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DownArrow({\mdseries\slshape sq})\index{DownArrow@\texttt{DownArrow}}
\label{DownArrow}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{BoundaryOfSquare({\mdseries\slshape sq})\index{BoundaryOfSquare@\texttt{BoundaryOfSquare}}
\label{BoundaryOfSquare}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DoubleGroupoidOfSquare({\mdseries\slshape sq})\index{DoubleGroupoidOfSquare@\texttt{DoubleGroupoidOfSquare}}
\label{DoubleGroupoidOfSquare}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsDoubleGroupoidElement({\mdseries\slshape arrow})\index{IsDoubleGroupoidElement@\texttt{IsDoubleGroupoidElement}}
\label{IsDoubleGroupoidElement}
}\hfill{\scriptsize (Category)}}\\


 Let $\Box(G)$ be the set of \emph{squares} with objects from $\Omega$ at each corner; plus two vertical arrows and two horizontal arrows from Arr$(G)$. The following picture illustrates a square $s_1$: 
\[  \vcenter{\xymatrix @=4pc{ u_1 \ar[r]^{a_1} \ar[d]_{b_1} & v_1 \ar[d]^{c_1} \\
w_1 \ar[r]_{d_1} & x_1 }} \]
 We name the four arrows \texttt{UpArrow(s)}, \texttt{LeftArrow(s)}, \texttt{RightArrow(s)} and \texttt{DownArrow(s)}. 

 We think of the square $s_1$ being \emph{based} at the bottom, right\texttt{\symbol{45}}hand corner, $x_1$. 

 The \emph{boundary} of the square is the loop $(x_1, d_1^{-1}b_1^{-1}a_1c_1, x_1) = (x_1,\delta(s_1),x_1)$. The number of squares in a double groupoid is the product of the number of
objects with the size of the group all raised to the fourth power. When
viewing or printing a square, the boundary element is shown in the centre. 

 }

 
\begin{Verbatim}[commandchars=!@C,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>C !gapinput@[ Size( DGd8 ), (3*8)^4 ]; C
  [ 331776, 331776 ]
  !gapprompt@gap>C !gapinput@a1 := Arrow( Gd8, (5,7), -7, -8 );;C
  !gapprompt@gap>C !gapinput@b1 := Arrow( Gd8, (6,8), -7, -7 );;C
  !gapprompt@gap>C !gapinput@c1 := Arrow( Gd8, (5,6)(7,8), -8, -9 );;C
  !gapprompt@gap>C !gapinput@d1 := Arrow( Gd8, (5,6,7,8), -7, -9 );;C
  !gapprompt@gap>C !gapinput@bdy1 := d1^-1 * b1^-1 * a1 * c1;C
  [(6,8) : -9 -> -9]
  !gapprompt@gap>C !gapinput@sq1 := SquareOfArrows( DGd8, a1, b1, c1, d1 ); C
  [-7] ------- (5,7) ------> [-8]
    |                          |
  (6,8)        (6,8)        (5,6)(7,8)
    V                          V
  [-7] ----- (5,6,7,8) ----> [-9]
  !gapprompt@gap>C !gapinput@sq1 in DGd8;C
  true
  !gapprompt@gap>C !gapinput@UpArrow( sq1 );C
  [(5,7) : -7 -> -8]
  !gapprompt@gap>C !gapinput@LeftArrow( sq1 );C
  [(6,8) : -7 -> -7]
  !gapprompt@gap>C !gapinput@RightArrow( sq1 );C
  [(5,6)(7,8) : -8 -> -9]
  !gapprompt@gap>C !gapinput@DownArrow( sq1 );C
  [(5,6,7,8) : -7 -> -9]
  !gapprompt@gap>C !gapinput@BoundaryOfSquare( sq1 );C
  [(6,8) : -9 -> -9]
  !gapprompt@gap>C !gapinput@DoubleGroupoidOfSquare( sq1 );C
  DGd8
  !gapprompt@gap>C !gapinput@IsDoubleGroupoidElement( sq1 );C
  true
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsCommutingSquare}}
\logpage{[ 8, 1, 3 ]}\nobreak
\hyperdef{L}{X83DF8EEE7BA72AA3}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsCommutingSquare({\mdseries\slshape sq})\index{IsCommutingSquare@\texttt{IsCommutingSquare}}
\label{IsCommutingSquare}
}\hfill{\scriptsize (property)}}\\


 The square $s_1$ is \emph{commuting} if $a_1*c_1 = b_1*d_1$, so that its boundary is the identity. The set of commutative squares in $\Box(G)$ forms the \emph{commutative sub\texttt{\symbol{45}}double groupoid} of $\Box(G)$. 

 }

 
\begin{Verbatim}[commandchars=!@E,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>E !gapinput@a2 := Arrow( Gd8, (6,8), -8, -9 );;E
  !gapprompt@gap>E !gapinput@c2 := Arrow( Gd8, (5,7)(6,8), -9, -8);;E
  !gapprompt@gap>E !gapinput@d2 := Arrow( Gd8, (5,6,7,8), -9, -8 );; E
  !gapprompt@gap>E !gapinput@sq2 := SquareOfArrows( DGd8, a2, c1, c2, d2 );E
  [-8] -------- (6,8) -------> [-9]
    |                            |
  (5,6)(7,8)        ()        (5,7)(6,8)
    V                            V
  [-9] ------ (5,6,7,8) -----> [-8]
  !gapprompt@gap>E !gapinput@bdy2 := BoundaryOfSquare( sq2 );E
  [() : -8 -> -8]
  !gapprompt@gap>E !gapinput@[ IsCommutingSquare(sq1), IsCommutingSquare(sq2) ]; E
  [ false, true ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{TransposedSquare}}
\logpage{[ 8, 1, 4 ]}\nobreak
\hyperdef{L}{X7F99A468819D7759}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{TransposedSquare({\mdseries\slshape sq})\index{TransposedSquare@\texttt{TransposedSquare}}
\label{TransposedSquare}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsClosedUnderTransposition({\mdseries\slshape sq})\index{IsClosedUnderTransposition@\texttt{IsClosedUnderTransposition}}
\label{IsClosedUnderTransposition}
}\hfill{\scriptsize (property)}}\\


 The transpose of the square $s_1$, as with matrix transposition, is obtained by interchanging $a_1$ with $b_1$ and $c_1$ with $d_1$. Its boundary is the inverse of the boundary of $s_1$. 

 }

 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@tsq1 := TransposedSquare( sq1 );A
  [-7] ------- (6,8) ------> [-7]
    |                         |
  (5,7)        (6,8)        (5,6,7,8)
    V                         V
  [-8] ---- (5,6)(7,8) ---> [-9]
  !gapprompt@gap>A !gapinput@IsClosedUnderTransposition( sq1 );  A
  false
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{HorizontalProduct}}
\logpage{[ 8, 1, 5 ]}\nobreak
\hyperdef{L}{X7D3737FA7E9E3ECA}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HorizontalProduct({\mdseries\slshape sq1, sq2})\index{HorizontalProduct@\texttt{HorizontalProduct}}
\label{HorizontalProduct}
}\hfill{\scriptsize (operation)}}\\


 When \texttt{RightArrow}$(s_1)$ = \texttt{LeftArrow}$(s_2)$ we may compose $s_1$ and $s_2$ \emph{horizontally} to form the square $s_1 (\rightarrow) s_2$ = \texttt{HorizontalProduct}$(s_1,s_2)$ as illustrated here: 
\[  \vcenter{\xymatrix @=4pc{ u_1 \ar[r]^{a_1} \ar[d]_{b_1} & v_1 \ar[r]^{a_2}
\ar[d]^{c_1} & v_2 \ar[d]^{c_2} \ar@{}[dr]|= & u_1 \ar[r]^{a_1a_2}
\ar[d]_{b_1} & v_2 \ar[d]^{c_2} \\ w_1 \ar[r]_{d_1} & x_1 \ar[r]_{d_2} & x_2 &
w_1 \ar[r]_{d_1d_2} & x_2 }} \]
 Notice that the boundary of the composite satisfies the identity: 
\[ \delta(s_1 (\rightarrow) s_2) ~=~ (d_1d_2)^{-1}b_1^{-1}(a_1a_2)c_2 ~=~
d_2^{-1}(d_1^{-1}b_1^{-1}a_1c_1)d_2(d_2^{-1}c_1^{-1}a_2c_2) ~=~ (\delta
s_1)^{d_2} (\delta s_2). \]
 

 (This operation was called \texttt{LeftRightProduct} in versions up to 1.76.) 

 }

 
\begin{Verbatim}[commandchars=!@C,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>C !gapinput@LeftArrow( sq2 ) = RightArrow( sq1 ); C
  true
  !gapprompt@gap>C !gapinput@sq12 := HorizontalProduct( sq1, sq2 );C
  [-7] ----- (5,7)(6,8) ----> [-9]
    |                          |
  (6,8)        (5,7)        (5,7)(6,8)
    V                          V
  [-7] ----- (5,7)(6,8) ----> [-8]
  !gapprompt@gap>C !gapinput@bdy12 := BoundaryOfSquare( sq12 );C
  [(5,7) : -8 -> -8]
  !gapprompt@gap>C !gapinput@(bdy1^d2) * bdy2 = bdy12;C
  true
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{VerticalProduct}}
\logpage{[ 8, 1, 6 ]}\nobreak
\hyperdef{L}{X873F01287A2DC41F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{VerticalProduct({\mdseries\slshape sq1, sq3})\index{VerticalProduct@\texttt{VerticalProduct}}
\label{VerticalProduct}
}\hfill{\scriptsize (operation)}}\\


 When \texttt{DownArrow}$(s_1)$ = \texttt{UpArrow}$(s_3)$ we may compose $s_1$ and $s_3$ \emph{vertically} to form $s_1 (\downarrow) s_3$ = \texttt{VerticalProduct}$(s_1,s_3)$ illustrated by: 
\[  \vcenter{\xymatrix @=2pc{ u_1 \ar[rr]^{a_1} \ar[dd]_{b_1} && v_1 \ar[dd]^{c_1}
& & && \\ && & & u_1 \ar[rr]^{a_1} \ar[dd]_{b_1b_3} && v_1 \ar[dd]^{c_1c_3} \\
w_1 \ar[rr]_{d_1} \ar[dd]_{b_3} && x_1 \ar[dd]^{c_3} &=& && \\ && & & w_3
\ar[rr]_{d_3} && x_3 \\ w_3 \ar[rr]_{d_3} && x_3 }} \]
 This time the boundary condition satisfies the identity: 
\[ \delta(s_1 (\downarrow) s_3) ~=~ d_3^{-1}(b_1b_3)^{-1}a_1(c_1c_3) ~=~
(d_3^{-1}b_3^{-1}d_1c_3)c_3^{-1}(d_1^{-1}b_1^{-1}a_1c_1)c_3 ~=~ (\delta
s_3)(\delta s_1)^{c_3}. \]
 

 (This operation was called \texttt{UpDownProduct} in versions up to 1.76.) 

 }

 
\begin{Verbatim}[commandchars=!@C,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>C !gapinput@b3 := Arrow( Gd8, (5,7), -7, -9 );;C
  !gapprompt@gap>C !gapinput@c3 := Arrow( Gd8, (6,8), -9, -8);;C
  !gapprompt@gap>C !gapinput@d3 := Arrow( Gd8, (5,8)(6,7), -9, -8 );; C
  !gapprompt@gap>C !gapinput@sq3 := SquareOfArrows( DGd8, d1, b3, c3, d3 );C
  [-7] ---- (5,6,7,8) ---> [-9]
    |                        |
  (5,7)       (6,8)       (6,8)
    V                        V
  [-9] ---- (5,8)(6,7) ---> [-8]
  !gapprompt@gap>C !gapinput@bdy3 := BoundaryOfSquare( sq3 );C
  [(6,8) : -8 -> -8]
  !gapprompt@gap>C !gapinput@UpArrow( sq3 ) = DownArrow( sq1 ); C
  true
  !gapprompt@gap>C !gapinput@sq13 := VerticalProduct( sq1, sq3 );C
  [-7] -------- (5,7) -------> [-8]
    |                           |
  (5,7)(6,8)        ()        (5,8,7,6)
    V                           V
  [-9] ----- (5,8)(6,7) ----> [-8]
  
  
\end{Verbatim}
 

 Vertical and horizontal compositions commute, so we may construct products
such as: 
\[  \vcenter{\xymatrix @=2pc{ u_1 \ar[rr]^{a_1} \ar[dd]_{b_1} && v_1 \ar[rr]^{a_2}
\ar[dd]|{c_1} && v_2 \ar[dd]^{c_2} & & &&& \\ && && & & u_1 \ar[rrr]^{a_1a_2}
\ar[dd]_{b_1b_3} &&& v_2 \ar[dd]^{c_2c_4} \\ w_1 \ar[rr]|{d_1} \ar[dd]_{b_3}
&& x_1 \ar[rr]|{d_2} \ar[dd]|{c_3} && x_2 \ar[dd]^{c_4} &=& &&& \\ && && & &
w_3 \ar[rrr]_{d_3d_4} &&& x_4 \\ w_3 \ar[rr]_{d_3} && x_3 \ar[rr]_{d_4} && x_4
}} \]
 In our example, after adding $c_4$ and $d_4$, it is routine to check that the two ways of computing the product of four
squares give the same answer. 
\[  \vcenter{\xymatrix @=2pc{ -7 \ar[rr]^{(5,7)} \ar[dd]_{(6,8)} && -8
\ar[rr]^{(6,8)} \ar[dd]|{(5,6)(7,8)} && -9 \ar[dd]^{(5,7)(6,8)} & & &&& \\ &&
&& & & -7 \ar[rrr]^{(5,7)(6,8)} \ar[dd]^{(5,7)(6,8)} &&& -9
\ar[dd]_{(5,8,7,6)} \\ -7 \ar[rr]|{(5,6,7,8)} \ar[dd]_{(5,7)} && -9
\ar[rr]|{(5,6,7,8)} \ar[dd]|{(6,8)} && -8 \ar[dd]^{(5,6,7,8)} &=& &&& \\ && &&
& & -9 \ar[rrr]_{(5,7)(6,8)} &&& -7 \\ -9 \ar[rr]_{(5,8)(6,7)} && -8
\ar[rr]_{(5,6)(7,8)} && -7 }} \]
 
\begin{Verbatim}[commandchars=!@B,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>B !gapinput@c4 := Arrow( Gd8, (5,6,7,8), -8, -7);;B
  !gapprompt@gap>B !gapinput@d4 := Arrow( Gd8, (5,6)(7,8), -8, -7 );; B
  !gapprompt@gap>B !gapinput@sq4 := SquareOfArrows( DGd8, d2, c3, c4, d4 );B
  [-9] ------- (5,6,7,8) ------> [-8]
    |                             |
  (6,8)        (5,6,7,8)        (5,6,7,8)
    V                             V
  [-8] ------ (5,6)(7,8) -----> [-7]
  !gapprompt@gap>B !gapinput@UpArrow( sq4 ) = DownArrow( sq2 );B
  true
  !gapprompt@gap>B !gapinput@LeftArrow( sq4 ) = RightArrow( sq3 ); B
  true
  
  !gapprompt@gap>B !gapinput@sq34 := HorizontalProduct( sq3, sq4 );B
  [-7] ------- (5,7)(6,8) ------> [-8]
    |                              |
  (5,7)        (5,8)(6,7)        (5,6,7,8)
    V                              V
  [-9] ------- (5,7)(6,8) ------> [-7]
  
  !gapprompt@gap>B !gapinput@sq1234 := VerticalProduct( sq12, sq34 );B
  [-7] --------- (5,7)(6,8) --------> [-9]
    |                                  |
  (5,7)(6,8)        (5,6,7,8)        (5,8,7,6)
    V                                  V
  [-9] --------- (5,7)(6,8) --------> [-7]
  
  !gapprompt@gap>B !gapinput@sq24 := VerticalProduct( sq2, sq4 ); B
  [-8] ----------- (6,8) ----------> [-9]
    |                                 |
  (5,8,7,6)        (5,6,7,8)        (5,8,7,6)
    V                                 V
  [-8] -------- (5,6)(7,8) -------> [-7]
  
  !gapprompt@gap>B !gapinput@sq1324 := HorizontalProduct( sq13, sq24 );;B
  !gapprompt@gap>B !gapinput@sq1324 = sq1234;B
  true
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{HorizontalIdentities}}
\logpage{[ 8, 1, 7 ]}\nobreak
\hyperdef{L}{X79E6E4E97A23C257}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HorizontalIdentities({\mdseries\slshape sq})\index{HorizontalIdentities@\texttt{HorizontalIdentities}}
\label{HorizontalIdentities}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{VerticalIdentities({\mdseries\slshape sq})\index{VerticalIdentities@\texttt{VerticalIdentities}}
\label{VerticalIdentities}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HorizontalInverses({\mdseries\slshape sq})\index{HorizontalInverses@\texttt{HorizontalInverses}}
\label{HorizontalInverses}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{VerticalInverses({\mdseries\slshape sq})\index{VerticalInverses@\texttt{VerticalInverses}}
\label{VerticalInverses}
}\hfill{\scriptsize (operation)}}\\


 There is no single identity for the operations \texttt{HorizontalProduct} and \texttt{VerticalProduct} but there are, for each square, a \emph{left identity}, a \emph{right identity}, an \emph{up identity} and a \emph{down identity}. The composite of the three squares shown below is equal to the central
square $s$, and the other two squares are the left identity $1_L(s)$ and the right identity $1_R(s)$ for $s$. 
\[  \vcenter{\xymatrix @=4pc{ u \ar[r]^{1} \ar[d]_{b} & u \ar[r]^{a} \ar[d]^{b} &
v \ar[r]^{1} \ar[d]_{c} & v \ar[d]^{c} \\ w \ar[r]_{1} & w \ar[r]_{d} & x
\ar[r]_{1} & x }} \]
 

 }

 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@hid := HorizontalIdentities( sq24 );;A
  !gapprompt@gap>A !gapinput@hid[1]; Print("\n"); hid[2];                    A
  [-8] --------- () --------> [-8]
    |                          |
  (5,8,7,6)        ()        (5,8,7,6)
    V                          V
  [-8] --------- () --------> [-8]
  
  [-9] --------- () --------> [-9]
    |                          |
  (5,8,7,6)        ()        (5,8,7,6)
    V                          V
  [-7] --------- () --------> [-7]
  !gapprompt@gap>A !gapinput@HorizontalProduct( hid[1], sq24 ) = sq24;A
  true
  !gapprompt@gap>A !gapinput@HorizontalProduct( sq24, hid[2] ) = sq24;      A
  true
  
\end{Verbatim}
 Similarly, here are the up identity $1_U(s)$ and the down identity $1_D(s)$ of $s$: 
\[  \vcenter{\xymatrix @=4pc{ u \ar[r]^{a} \ar[d]_{1} & v \ar[d]^{1} & w
\ar[r]^{d} \ar[d]_{1} & x \ar[d]^{1} \\ u \ar[r]_{a} & v & w \ar[r]_{d} & x }} \]
 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@vid := VerticalIdentities( sq24 );;  A
  !gapprompt@gap>A !gapinput@vid[1]; Print("\n"); vid[2];                    A
  [-8] ---- (6,8) ---> [-9]
    |                   |
  ()         ()         ()
    V                   V
  [-8] ---- (6,8) ---> [-9]
  
  [-8] ---- (5,6)(7,8) ---> [-7]
    |                        |
  ()            ()            ()
    V                        V
  [-8] ---- (5,6)(7,8) ---> [-7]
  !gapprompt@gap>A !gapinput@VerticalProduct( vid[1], sq24 ) = sq24;A
  true
  !gapprompt@gap>A !gapinput@VerticalProduct( sq24, vid[2] ) = sq24;A
  true
  
\end{Verbatim}
 Confusingly, $s$ has a \emph{horizontal inverse} $s^{-1}_{H}$ whose product with $s$ is the left identity or right identity: 
\[ s (\rightarrow) s^{-1}_{H} ~=~ 1_L(s), \qquad s^{-1}_{H} (\rightarrow) s ~=~
1_R(s). \]
 The boundary of $s^{-1}_{H}$ is $dc^{-1}a^{-1}b = (\delta(s)^{-1})^{d^{-1}}$. Here are the two products: 
\[  \vcenter{\xymatrix @=4pc{ u \ar[r]^{a} \ar[d]_{b} & v \ar[r]^{a^{-1}}
\ar[d]^{c} & u \ar[d]^{b} & v \ar[r]^{a^{-1}} \ar[d]_{c} & u \ar[r]^{a}
\ar[d]^{b} & v \ar[d]^{c} \\ w \ar[r]_{d} & x \ar[r]_{d^{-1}} & w & x
\ar[r]_{d^{-1}} & w \ar[r]_{d} & x }} \]
 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@hinv := HorizontalInverse( sq24 ); A
  [-9] ----------- (6,8) ----------> [-8]
    |                                 |
  (5,8,7,6)        (5,6,7,8)        (5,8,7,6)
    V                                 V
  [-7] -------- (5,6)(7,8) -------> [-8]
  !gapprompt@gap>A !gapinput@HorizontalProduct( hinv, sq24 ) = hid[2];A
  true
  !gapprompt@gap>A !gapinput@HorizontalProduct( sq24, hinv ) = hid[1];      A
  true
  
\end{Verbatim}
 Similarly, $s$ has a \emph{vertical inverse} $s^{-1}_{V}$ whose product with $s$ is an up or down identity: $s (\downarrow) s^{-1}_{V} = 1_U(s)$ and $s^{-1}_{V} (\downarrow) s = 1_D(s)$. The boundary is $a^{-1}bdc^{-1} = (\delta(s)^{-1})^{c^{-1}}$. 
\[  \vcenter{\xymatrix @=4pc{ w \ar[r]^{d} \ar[d]_{b^{-1}} & x \ar[d]^{c^{-1}} \\
u \ar[r]_{a} & v }} \]
 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@vinv := VerticalInverse( sq24 );A
  [-8] -------- (5,6)(7,8) -------> [-7]
    |                                 |
  (5,6,7,8)        (5,8,7,6)        (5,6,7,8)
    V                                 V
  [-8] ----------- (6,8) ----------> [-9]
  !gapprompt@gap>A !gapinput@VerticalProduct( vinv, sq24 ) = vid[2];A
  true
  !gapprompt@gap>A !gapinput@VerticalProduct( sq24, vinv ) = vid[1];   A
  true
  
\end{Verbatim}
 
\subsection{\textcolor{Chapter }{Horizontal and vertical groupoids in $\Box(G)$}}\label{sec-horiz-vert}
\logpage{[ 8, 1, 8 ]}
\hyperdef{L}{X7B8DEF5A7B5AEC46}{}
{
  Now $\Box(G)$ is the maximal double groupoid determined by $G$, but in general many substructures may be formed. The \emph{horizontal groupoid} \index{horizontal groupoid@} structure $\Box_{H}(G)$ on $\Box(G)$ has the vertical arrows as objects, and considers the usual square $s$ 
\[  \vcenter{\xymatrix @=4pc{ u \ar[r]^{a} \ar[d]_{b} & v \ar[d]^{c} \\ w
\ar[r]_{d} & x }} \]
 as an arrow from $b$ to $c$. So the arrows in $\Box_{H}(G)$ are effectively pairs of horizontal arrows $[a,d]$. The vertex groups are isomorphic to $G \times G$; the identity arrow at $b$ is $1_L(s)$; and the inverse arrow of $s$ is $s^{-1}_{H}$. 

 Similarly the \emph{vertical groupoid} \index{vertical groupoid@} structure $\Box_{V}(G)$ on $\Box(G)$ has the horizontal arrows as objects and pairs of vertical arrows as arrows.
The identity arrow at $a$ is $1_U(s)$, and the inverse arrow of $s$ is $s^{-1}_{V}$. 

 These groupoid structures have not been implemented in this package. }

 }

 
\section{\textcolor{Chapter }{Double groupoids with more than one piece}}\label{sec-double-pieces}
\logpage{[ 8, 2, 0 ]}
\hyperdef{L}{X7F319AA17ED13024}{}
{
  As with groupoids, double groupoids may comprise a union of single piece
double groupoids with disjoint object sets. 

\subsection{\textcolor{Chapter }{UnionOfPieces (for double groupoids)}}
\logpage{[ 8, 2, 1 ]}\nobreak
\label{sec-union-dgpds}
\hyperdef{L}{X8589EFAE7935BEA6}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{UnionOfPieces({\mdseries\slshape pieces})\index{UnionOfPieces@\texttt{UnionOfPieces}!for double groupoids}
\label{UnionOfPieces:for double groupoids}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Pieces({\mdseries\slshape dgpd})\index{Pieces@\texttt{Pieces}!for double groupoids}
\label{Pieces:for double groupoids}
}\hfill{\scriptsize (attribute)}}\\


 The operation \texttt{UnionOfPieces} and the attribute \texttt{Pieces}, introduced in section \ref{sec-pieces}, are also used for double groupoids. The pieces are sorted by the least
object in their object lists. The \texttt{ObjectList} is the sorted concatenation of the objects in the pieces. 

 The example shows that, as well as taking the union of two double groupoids,
the same object may be constructed directly from the underlying groupoids. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@DGc6 := SinglePieceBasicDoubleGroupoid( Gc6 );; |
  !gapprompt@gap>| !gapinput@DGa4 := SinglePieceBasicDoubleGroupoid( Ga4 );; |
  !gapprompt@gap>| !gapinput@DGc6s4 := DoubleGroupoid( [ DGc6, DGa4 ] );|
  double groupoid having 2 pieces :-
  1: single piece double groupoid with:
   groupoid = Ga4
      group = a4
    objects = [ -15 .. -11 ]
  2: single piece double groupoid with:
   groupoid = Gc6
      group = c6
    objects = [ -10 ]
  
  !gapprompt@gap>| !gapinput@DGa4c6 := DoubleGroupoid( [ Ga4, Gc6 ] );;|
  !gapprompt@gap>| !gapinput@Pieces( DGa4c6 );|
  [ single piece double groupoid with:
       groupoid = Ga4
          group = a4
        objects = [ -15 .. -11 ], single piece double groupoid with:
       groupoid = Gc6
          group = c6
        objects = [ -10 ] ]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Generators of a double groupoid}}\label{sec-double-gens}
\logpage{[ 8, 3, 0 ]}
\hyperdef{L}{X78E24657817C4D30}{}
{
  Before considering the general case we investigate two special cases: 
\begin{itemize}
\item  a basic double groupoid with identity group; 
\item  a basic double groupoid with a single object. 
\end{itemize}
 

\subsection{\textcolor{Chapter }{DoubleGroupoidWithTrivialGroup}}
\logpage{[ 8, 3, 1 ]}\nobreak
\hyperdef{L}{X80009143808725D5}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DoubleGroupoidWithTrivialGroup({\mdseries\slshape obs})\index{DoubleGroupoidWithTrivialGroup@\texttt{DoubleGroupoidWithTrivialGroup}}
\label{DoubleGroupoidWithTrivialGroup}
}\hfill{\scriptsize (operation)}}\\


 When $|\Omega|=n$ the double groupoid with trivial permutation group on these $n$ objects contains $n^4$ squares of the form: 
\[  \vcenter{\xymatrix @=4pc{ u \ar[r]^{()} \ar[d]_{()} & v \ar[d]^{()} \\ w
\ar[r]_{()} & x }} \]
 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@DGtriv := DoubleGroupoidWithTrivialGroup( [-19..-17] );|
  single piece double groupoid with:
   groupoid = single piece groupoid: < Group( [ () ] ), [ -19 .. -17 ] >
      group = Group( [ () ] )
    objects = [ -19 .. -17 ]
  
  !gapprompt@gap>| !gapinput@Size(DGtriv);                                          |
  81
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{DoubleGroupoidWithSingleObject}}
\logpage{[ 8, 3, 2 ]}\nobreak
\hyperdef{L}{X7D135AFB83995A32}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DoubleGroupoidWithSingleObject({\mdseries\slshape gp, obj})\index{DoubleGroupoidWithSingleObject@\texttt{DoubleGroupoidWithSingleObject}}
\label{DoubleGroupoidWithSingleObject}
}\hfill{\scriptsize (operation)}}\\


 Given a group $G$ we can form the corresponding groupoid with a single object, and from that a
double groupoid on that object. The number of squares is $|G|^4$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@DGc4 := DoubleGroupoidWithSingleObject( Group((1,2,3,4)), 0 );|
  single piece double groupoid with:
   groupoid = single piece groupoid: < Group( [ (1,2,3,4) ] ), [ 0 ] >
      group = Group( [ (1,2,3,4) ] )
    objects = [ 0 ]
  
  !gapprompt@gap>| !gapinput@Size( DGc4 );                                                 |
  256
  
\end{Verbatim}
 
\subsection{\textcolor{Chapter }{What is the double groupoid generated by a set of squares?}}\label{sec-generating}
\logpage{[ 8, 3, 3 ]}
\hyperdef{L}{X85A6C1A685357E66}{}
{
  This is a very experimental section. Let us consider the following list of
three squares $[s_U(a,u,v),~ 1_U(v,u),~ s_U(a,u,u)]$. What is generated by the single square $s_U(a,u,v)$? 
\[  \vcenter{\xymatrix @=4pc{ u \ar[r]^{a} \ar[d]_{1} & v \ar[d]^{1} & v
\ar[r]^{1} \ar[d]_{1} & u \ar[d]_{1} & u \ar[r]^{a} \ar[d]_{1} & u \ar[d]_{1}
\\ u \ar[r]_{1} & v & v \ar[r]_{1} & u & u \ar[r]_{1} & u }} \]
 The first square does not compose with itself, so cannot generate anything.
When constructing a group from generators there is never any need to include
an identity \texttt{\symbol{45}} that is always assumed to be included.
Perhaps, when constructing a double groupoid, it should be assumed that the \texttt{DoubleGroupoidWithTrivialGroup} on the given objects should be automatically included? In that case the square $1_U(v,u)$ is available and can compose on the right to give $s_U(a,u,u)$. This then composes with itself to produce squares $s_U(a^i,u,u)$. Then, composing with identities, we obtain \texttt{SinglePieceBasicDoubleGroupoid(G)} where $G$ is the groupoid with group $\langle a \rangle$ and objects $[u,v]$. More work on this area is required! }

 }

 
\section{\textcolor{Chapter }{Starting with two groupoids}}\label{sec-double-product}
\logpage{[ 8, 4, 0 ]}
\hyperdef{L}{X80E0318F78D2AD28}{}
{
  In the literature on double groupoids the construction often starts with two
groupoids $G_1, G_2$, and squares have horizontal arrows chosen from $G_1$ and vertical arrows chosen from $G_2$. When that is the case, the boundary of a square is not defined, since arrows
from $G_1$ do not compose with those from $G_2$. This situation may be modelled here by constructing the direct product
groupoid $G = G_1 \times G_2$ and forming a double groupoid on $G$ in which squares have the form: 
\[  \vcenter{\xymatrix @=4pc{ [u_1,u_2] \ar[r]^{[a,1]} \ar[d]_{[1,b]} & [v_1,v_2]
\ar[d]^{[1,c]} \\ [w_1,w_2] \ar[r]_{[d,1]} & [x_1,x_2] }} \]
 

 
\begin{Verbatim}[commandchars=!@C,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>C !gapinput@Gd8c6 := DirectProduct( Gd8, Gc6 );C
  single piece groupoid: < Group( [ (1,2,3,4), (1,3), (5,6,7)(8,9) ] ), 
  [ [ -9, -10 ], [ -8, -10 ], [ -7, -10 ] ] >
  !gapprompt@gap>C !gapinput@SetName( Gd8c6, "Gd8c6" );C
  !gapprompt@gap>C !gapinput@DGd8c6 := SinglePieceBasicDoubleGroupoid( Gd8c6 );C
  single piece double groupoid with:
   groupoid = Gd8c6
      group = Group( [ (1,2,3,4), (1,3), (5,6,7)(8,9) ] )
    objects = [ [ -9, -10 ], [ -8, -10 ], [ -7, -10 ] ]
  
  !gapprompt@gap>C !gapinput@emb1 := Embedding( Gd8c6, 1 );;C
  !gapprompt@gap>C !gapinput@emb2 := Embedding( Gd8c6, 2 );;C
  !gapprompt@gap>C !gapinput@a5 := Arrow( Gd8, (5,7), -9, -7 );;C
  !gapprompt@gap>C !gapinput@a6 := ImageElm( emb1, a5 );C
  [(1,3) : [ -9, -10 ] -> [ -7, -10 ]]
  !gapprompt@gap>C !gapinput@d5 := Arrow( Gd8, (6,8), -9, -8 );;C
  !gapprompt@gap>C !gapinput@d6 := ImageElm( emb1, d5 );C
  [(2,4) : [ -9, -10 ] -> [ -8, -10 ]]
  !gapprompt@gap>C !gapinput@b5 := Arrow( Gc6, (11,12,13), -10, -10 );;C
  !gapprompt@gap>C !gapinput@b6 := ImageElm( emb2, b5 );C
  [(5,6,7) : [ -9, -10 ] -> [ -9, -10 ]]
  !gapprompt@gap>C !gapinput@c6 := Arrow( Gd8c6, (8,9), [-7,-10], [-8,-10] );;C
  !gapprompt@gap>C !gapinput@sq := SquareOfArrows( DGd8c6, a6, b6, c6, d6 );C
  [[ -9, -10 ]] ----- (1,3) ----> [[ -7, -10 ]]
    |                                        |
  (5,6,7)        (1,3)(2,4)(5,7,6)(8,9)        (8,9)
    V                                        V
  [[ -9, -10 ]] ----- (2,4) ----> [[ -8, -10 ]]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Double groupoid homomorphisms}}\label{sec-dgpd-hom}
\logpage{[ 8, 5, 0 ]}
\hyperdef{L}{X83F6AFC185148621}{}
{
  

\subsection{\textcolor{Chapter }{DoubleGroupoidHomomorphism}}
\logpage{[ 8, 5, 1 ]}\nobreak
\hyperdef{L}{X87752436787B199D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DoubleGroupoidHomomorphism({\mdseries\slshape src, rng, hom})\index{DoubleGroupoidHomomorphism@\texttt{DoubleGroupoidHomomorphism}}
\label{DoubleGroupoidHomomorphism}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsDoubleGroupoidHomomorphism({\mdseries\slshape mwohom})\index{IsDoubleGroupoidHomomorphism@\texttt{IsDoubleGroupoidHomomorphism}}
\label{IsDoubleGroupoidHomomorphism}
}\hfill{\scriptsize (Category)}}\\


 A homomorphism of double groupoids is determined by a homomorphism \texttt{mor} between the underlying groupoids since \texttt{mor} determines the images of the four arrows in every square. 

 In the example we take the endomorphism \texttt{md8} of \texttt{Gd8}, constructed in section \ref{subsec-prop-homs}, to produce an endomorphism of \texttt{DGd8}. }

 
\begin{Verbatim}[commandchars=!@A,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>A !gapinput@ad8 := GroupHomomorphismByImages( d8, d8,A
  !gapprompt@>A !gapinput@              [ (5,6,7,8), (5,7) ], [ (5,8,7,6), (6,8) ] );;A
  !gapprompt@gap>A !gapinput@md8 := GroupoidHomomorphism( Gd8, Gd8, ad8, A
  !gapprompt@>A !gapinput@              [-7,-9,-8], [(),(5,7),(6,8)] );;A
  !gapprompt@gap>A !gapinput@endDGd8 := DoubleGroupoidHomomorphism( DGd8, DGd8, md8 );;A
  !gapprompt@gap>A !gapinput@Display( endDGd8 );            A
  double groupoid homomorphism: [ DGd8 ] -> [ DGd8 ]
  with underlying groupoid homomorphism:
  homomorphism to single piece groupoid: Gd8 -> Gd8
  root group homomorphism:
  (5,6,7,8) -> (5,8,7,6)
  (5,7) -> (6,8)
  object map: [ -9, -8, -7 ] -> [ -7, -9, -8 ]
  ray images: [ (), (5,7), (6,8) ]
  !gapprompt@gap>A !gapinput@IsDoubleGroupoidHomomorphism( endDGd8 );A
  true
  !gapprompt@gap>A !gapinput@sq1;A
  [-7] ------- (5,7) ------> [-8]
    |                          |
  (6,8)        (6,8)        (5,6)(7,8)
    V                          V
  [-7] ----- (5,6,7,8) ----> [-9]
  !gapprompt@gap>A !gapinput@ImageElm( endDGd8, sq1 );A
  [-8] ------- (5,7) ------> [-9]
    |                         |
  (5,7)        (5,7)        (5,8,7,6)
    V                         V
  [-8] ---- (5,8)(6,7) ---> [-7]
  
\end{Verbatim}
 }

 }

  
\chapter{\textcolor{Chapter }{Technical Notes}}\label{chap-tecnotes}
\logpage{[ 9, 0, 0 ]}
\hyperdef{L}{X7F2BA6DC7AD84FBC}{}
{
  This short chapter is included for the benefit of anyone wishing to implement
some other variety of many\texttt{\symbol{45}}object structures, for example \emph{ringoids}, which are rings with many objects; \emph{Lie groupoids}, which are Lie groups with many objects; and so on. 
\section{\textcolor{Chapter }{Many object structures}}\label{sec-tec-mwo}
\logpage{[ 9, 1, 0 ]}
\hyperdef{L}{X7C5B725A7AED3C8D}{}
{
  Structures with many objects, and their elements, are defined in a manner
similar to the single object case. For elements we have: 
\begin{itemize}
\item  \texttt{DeclareCategory( "IsMultiplicativeElementWithObjects", IsMultiplicativeElement
); } 
\item  \texttt{DeclareCategory( "IsMultiplicativeElementWithObjectsAndOnes",
IsMultiplicativeElementWithObjects ); } 
\item  \texttt{DeclareCategory( "IsMultiplicativeElementWithObjectsAndInverses",
IsMultiplicativeElementWithObjectsAndOnes ); } 
\item  \texttt{DeclareCategory( "IsGroupoidElement", } 

 \texttt{IsMultiplicativeElementWithObjectsAndInverses ); } 
\end{itemize}
 as well as various category collections. For the various structures we have: 
\begin{itemize}
\item  \texttt{DeclareCategory( "IsDomainWithObjects", IsDomain ); } 
\item  \texttt{DeclareCategory( "IsMagmaWithObjects", IsDomainWithObjects and
IsMultiplicativeElementWithObjectsCollection );} 
\item  \texttt{DeclareCategory( "IsSemigroupWithObjects", IsMagmaWithObjects and
IsAssociative ); } 
\item  \texttt{DeclareCategory( "IsMonoidWithObjects", IsSemigroupWithObjects and
IsMultiplicativeElementWithObjectsAndOnesCollection ); } 

 \texttt{IsMultiplicativeElementWithObjectsAndInversesCollection ); } 
\item  \texttt{DeclareCategory( "IsGroupoid", IsMonoidWithObjects and
IsGroupoidElementCollection ); } 
\end{itemize}
 Among the groupoids constructed earlier are the single piece \texttt{Gd8} and the five component union \texttt{U5}: 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@CategoriesOfObject( Gd8 );|
  [ "IsListOrCollection", "IsCollection", "IsExtLElement", 
    "CategoryCollections(IsExtLElement)", "IsExtRElement", 
    "CategoryCollections(IsExtRElement)", 
    "CategoryCollections(IsMultiplicativeElement)", "IsGeneralizedDomain", 
    "IsMagma", "IsDomainWithObjects", 
    "CategoryCollections(IsMultiplicativeElementWithObjects)", 
    "CategoryCollections(IsMultiplicativeElementWithObjectsAndOnes)", 
    "CategoryCollections(IsMultiplicativeElementWithObjectsAndInverses)\
  ", "CategoryCollections(IsGroupoidElement)", "IsMagmaWithObjects", 
    "IsMagmaWithObjectsAndOnes", "IsMagmaWithObjectsAndInverses", 
    "IsGroupoid" ]
  !gapprompt@gap>| !gapinput@FamilyObj( Gd8 );     ## these numbers vary from one run to another|
  NewFamily( "GroupoidFamily", [ 2722 ], [ 53, 54, 79, 80, 81, 82, 92, 93, 116, 
    117, 119, 120, 123, 205, 501, 2690, 2703, 2707, 2711, 2715, 2718, 2720, 
    2721, 2722 ] )
  !gapprompt@gap>| !gapinput@KnownAttributesOfObject( Gd8 ); |
  [ "Name", "Size", "ObjectList", "GeneratorsOfMagmaWithObjects", 
    "GeneratorsOfGroupoid" ]
  !gapprompt@gap>| !gapinput@KnownTruePropertiesOfObject( Gd8 ); |
  [ "IsNonTrivial", "IsFinite", "IsDuplicateFree", "IsAssociative", 
    "IsSinglePieceDomain", "IsDirectProductWithCompleteDigraphDomain" ]
  !gapprompt@gap>| !gapinput@RepresentationsOfObject( Gd8 );|
  [ "IsComponentObjectRep", "IsAttributeStoringRep", "IsMWOSinglePieceRep" ]
  !gapprompt@gap>| !gapinput@RepresentationsOfObject( U5 ); |
  [ "IsComponentObjectRep", "IsAttributeStoringRep", "IsPiecesRep" ]
  
\end{Verbatim}
 Similarly, for arrows, we have: 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@[ a78, e2 ];|
  [ [m2 : -7 -> -8], [(1,3) : -8 -> -7] ]
  !gapprompt@gap>| !gapinput@CategoriesOfObject(a78);|
  [ "IsExtLElement", "IsExtRElement", "IsMultiplicativeElement", 
    "IsMultiplicativeElementWithObjects" ]
  !gapprompt@gap>| !gapinput@FamilyObj( a78 );     ## again these numbers vary|
  NewFamily( "MultiplicativeElementWithObjectsFamily", [ 2702 ], 
  [ 79, 80, 81, 82, 116, 119, 122, 2702 ] )
  !gapprompt@gap>| !gapinput@CategoriesOfObject(e2); |
  [ "IsExtLElement", "IsExtRElement", "IsMultiplicativeElement", 
    "IsMultiplicativeElementWithObjects", 
    "IsMultiplicativeElementWithObjectsAndOnes", 
    "IsMultiplicativeElementWithObjectsAndInverses", 
    "IsGroupoidElement" ]
  !gapprompt@gap>| !gapinput@FamilyObj( e2 );        |
  NewFamily( "GroupoidElementFamily", [ 2714 ], 
  [ 79, 80, 81, 82, 116, 119, 122, 2702, 2706, 2710, 2714 ] )
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Many object homomorphisms}}\label{sec-tec-mwohom}
\logpage{[ 9, 2, 0 ]}
\hyperdef{L}{X7A4760E887C9C968}{}
{
  Homomorphisms of structures with many objects have a similar heirarchy. A few
examples: 
\begin{itemize}
\item  \texttt{DeclareCategory( "IsGeneralMappingWithObjects", IsGeneralMapping ); } 
\item  \texttt{DeclareSynonymAttr( "IsMagmaWithObjectsGeneralMapping",
IsGeneralMappingWithObjects and RespectsMultiplication ); } 
\item  \texttt{DeclareSynonymAttr( "IsMagmaWithObjectsHomomorphism",
IsMagmaWithObjectsGeneralMapping and IsMapping ); } 
\item  \texttt{DeclareCategory("IsGroupoidHomomorphism",IsMagmaWithObjectsHomomorphism); } 
\end{itemize}
 

 Two forms of representation are used: for mappings to a single piece; and for
unions of such mappings: 
\begin{itemize}
\item  \texttt{DeclareRepresentation( "IsMappingToSinglePieceRep",
IsMagmaWithObjectsHomomorphism and IsAttributeStoringRep and IsGeneralMapping,
[ "Source", "Range", "SinglePieceMappingData" ] ); } 
\item  \texttt{DeclareRepresentation( "IsMappingWithObjectsRep",
IsMagmaWithObjectsHomomorphism and IsAttributeStoringRep and IsGeneralMapping,
[ "Source", "Range", "PiecesOfMapping" ] ); } 
\end{itemize}
 

 In previous chapters, \texttt{hom1} was an endofunction on \texttt{M78}; \texttt{homd8} was a homomorphism from \texttt{Gd8} to \texttt{Gs3}; and \texttt{aut3} was an automorphism of \texttt{Ga4}. All homomorphisms have family \texttt{GeneralMappingWithObjectsFamily}. Perhaps it would be better to have separate families for each structure? 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@FamilyObj(hom1);|
  NewFamily( "GeneralMappingWithObjectsFamily", [ 2726 ], 
  [ 79, 80, 81, 82, 116, 119, 122, 126, 130, 149, 412, 2726 ] )
  !gapprompt@gap>| !gapinput@KnownAttributesOfObject( hom1 );|
  [ "Range", "Source", "SinglePieceMappingData" ]
  !gapprompt@gap>| !gapinput@KnownTruePropertiesOfObject( hom1 );|
  [ "CanEasilyCompareElements", "CanEasilySortElements", "IsTotal", 
    "IsSingleValued", "RespectsMultiplication", "IsGeneralMappingToSinglePiece",
    "IsGeneralMappingFromSinglePiece", "IsInjectiveOnObjects", 
    "IsSurjectiveOnObjects" ]
  !gapprompt@gap>| !gapinput@CategoriesOfObject( homd8 );|
  [ "IsExtLElement", "IsExtRElement", "IsMultiplicativeElement", 
    "IsMultiplicativeElementWithOne", "IsMultiplicativeElementWithInverse", 
    "IsAssociativeElement", "IsGeneralMapping", "IsGeneralMappingWithObjects", 
    "IsGroupoidHomomorphism" ]
  !gapprompt@gap>| !gapinput@KnownAttributesOfObject( homd8 );|
  [ "Range", "Source", "SinglePieceMappingData", "ImagesOfObjects", "ImageElementsOfRays", 
    "ObjectTransformationOfGroupoidHomomorphism", "RootGroupHomomorphism" ]
  !gapprompt@gap>| !gapinput@KnownAttributesOfObject( aut3 );|
  [ "Order", "Range", "Source", "SinglePieceMappingData", "ImagesOfObjects", 
    "ImageElementsOfRays", "ObjectTransformationOfGroupoidHomomorphism", 
    "RootGroupHomomorphism" ]
  
\end{Verbatim}
 }

 }

  
\chapter{\textcolor{Chapter }{Development History}}\label{chap-history}
\logpage{[ 10, 0, 0 ]}
\hyperdef{L}{X810C43BC7F63C4B4}{}
{
  
\section{\textcolor{Chapter }{Versions of the Package}}\label{sec-versions}
\logpage{[ 10, 1, 0 ]}
\hyperdef{L}{X8192EA4C7B7CC5CD}{}
{
  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. Version
1.03, of October 2007, fixed some file protections, and introduced the test
file \texttt{gpd{\textunderscore}manual.tst}. 

 Version 1.05, of November 2008, was released when the website at Bangor
changed. 

 Since then, the package has been rewritten again, introducing magmas with
objects and their mappings. Functions to implement constructions contained in \cite{AlWe} have been added, but this is ongoing work. 

 Versions 1.09 to 1.15 were prepared for the anticipated release of \textsf{GAP} 4.5 in June 2012. 

 \textsf{Gpd} became an accepted \textsf{GAP} package in May 2015. 

 In April 2017 the package was renamed again, as \textsf{groupoids}. 

 In August 2017 the implementation of groupoid homomorphisms was completely
revised with the emphasis now on a mapping from a set of generating arrows to
their images. 

 In September 2017 various functions were revised so that, at last, the
operation \texttt{DiscreteNormalPreXModWithObjects} in \textsf{XMod} works again. This constructs a crossed module of groupoids with a connected
range and a homogeneous, discrete source. 

 In recent versions there have been a number of changes of function name, such
as \texttt{IsDigraph} becoming \texttt{IsGroupoidDigraph}. This is in order to avoid conflicts with the \textsf{Digraphs} package. 

 In version 1.62 of October 2018 there were significant changes to the
operations constructing free products with amalgamation and HNN extensions.
There was a plan to move this material to a new package \textsf{Rewriting}, but that has not happened. 

 Version 1.71 of August 2022 contains a complete revision of right, left and
double cosets of groupoids. (The initial declaration of LeftCoset was moved to
the \textsf{Utils} package.) 

 Version 1.73 of February 2023 contained a first attempt at an implementation
of double groupoids, as described in Chapter \ref{chap-double}. This was then extensively revised in version 1.77 of July 2025. This
experimental material is liable to be changed and extended. A more general
version of double groupoids has been introduced in the \textsf{XMod} package. }

 
\section{\textcolor{Chapter }{What needs to be done next?}}\label{sec-whatnext}
\logpage{[ 10, 2, 0 ]}
\hyperdef{L}{X82148FB77CC3CCC0}{}
{
  
\begin{itemize}
\item  more work on automorphism groups of groupoids; 
\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  convert \texttt{GraphOfGroupsRewritingSystem} to the category \texttt{IsRewritingSystem}; 
\item  in \textsf{XMod}, continue to work on crossed modules over groupoids; 
\end{itemize}
 }

 }

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

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

\addcontentsline{toc}{chapter}{References}

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

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


\printindex

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