  
  [1X2. Groupoids[0X
  
  A   [13Xgroupoid[0X  is  a  (mathematical)  category  in  which  every  element  is
  invertible. It consists of a set of components, each of which is a connected
  groupoid.
  
  A  [13Xconnected  groupoid[0X  is  determined by a set of [13Xobjects[0X [10Xobs[0X and an [13Xobject
  group[0X  [10Xgrp[0X. Connected groupoids are represented as [10XIsConnectedGroupoidRep[0X, a
  record  with  components  [10Xobjects[0X  and  [10Xgroup[0X.  The  objects  of a connected
  groupoid  are  generally chosen to be consecutive negative integers, but any
  suitable  ordered set is acceptable, and `consecutive' is not a requirement.
  The  object  groups  will  usually  be  taken  to be permutation groups, but
  pc-groups and fp-groups are also supported.
  
  A [13Xgroup[0X is a connected groupoid with one object.
  
  A  [13Xgroupoid[0X  is  a  set  of  one  or more connected groupoids, its connected
  [13Xcomponents[0X,   and   is   represented   as   [10XIsGroupoidRep[0X,   with  attribute
  [10XComponentsOfGroupoid[0X.
  
  For  the  definitions of the standard properties of groupoids we refer to R.
  Brown's   book  ``Topology''  [Bro88],  recently  revised  and  reissued  as
  ``Topology and Groupoids'' [Bro06].
  
  
  [1X2.1 Groupoids: their elements and attributes[0X
  
  [1X2.1-1 ConnectedGroupoid[0X
  
  [2X> ConnectedGroupoid( [0X[3Xobs, grp[0X[2X ) ___________________________________[0Xoperation
  [2X> GroupAsGroupoid( [0X[3Xobj, grp[0X[2X ) _____________________________________[0Xoperation
  [2X> GroupoidByUnion( [0X[3Xcomps[0X[2X ) ________________________________________[0Xoperation
  [2X> Groupoid( [0X[3Xargs[0X[2X ) _________________________________________________[0Xfunction
  
  There  are  a  variety  of  constructors  for  groupoids,  with  one  or two
  parameters.  The global function [10XGroupoid[0X will normally find the appropriate
  one to call, the options being:
  
  --    a list of objects, the object group;
  
  --    a single object, a group being converted to a groupoid;
  
  --    a list of groupoids which have already been constructed.
  
  Methods for [10XViewObj[0X, [10XPrintObj[0X and [10XDisplay[0X 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.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> d8 := Group( (1,2,3,4), (1,3) );;[0X
    [4Xgap> SetName( d8, "d8" );[0X
    [4Xgap> Gd8 := ConnectedGroupoid( [-9,-8,-7], d8 );[0X
    [4XPerm Connected Groupoid:[0X
    [4X< [ -9, -8, -7 ], d8 >[0X
    [4Xgap> c6 := Group( (5,6,7)(8,9) );;[0X
    [4Xgap> SetName( c6, "c6" );[0X
    [4Xgap> Gc6 := GroupAsGroupoid( -6, c6 );[0X
    [4XPerm Connected Groupoid:[0X
    [4X< [ -6 ], c6 >[0X
    [4Xgap> Gd8c6 := GroupoidByUnion( [ Gd8, Gc6 ] );;[0X
    [4Xgap> Display( Gd8c6 );[0X
    [4XPerm Groupoid with 2 components:[0X
    [4X< objects: [ -9, -8, -7 ][0X
    [4X    group: d8 = <[ (1,2,3,4), (1,3) ]> >[0X
    [4X< objects: [ -6 ][0X
    [4X    group: c6 = <[ (5,6,7)(8,9) ]> >[0X
    [4Xgap> SetName( Gd8, "Gd8" );  SetName( Gc6, "Gc6" );  SetName( Gd8c6, "Gd8+Gc6" );[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X2.1-2 ComponentsOfGroupoid[0X
  
  [2X> ComponentsOfGroupoid( [0X[3Xgpd[0X[2X ) _____________________________________[0Xattribute
  [2X> ObjectsOfGroupoid( [0X[3Xgpd[0X[2X ) ________________________________________[0Xattribute
  
  When  a groupoid consists of two or more components, we require their object
  lists to be disjoint. The components are sorted by the first object in their
  object  lists,  which  must  be  disjoint.  The  list [10XObjectsOfGroupoid[0X of a
  groupoid is the sorted concatenation of the objects in the components.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> ComponentsOfGroupoid( Gd8c6 );[0X
    [4X[ Gd8, Gc6 ][0X
    [4Xgap> ObjectsOfGroupoid( Gd8c6 );[0X
    [4X[ -9, -8, -7, -6 ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X2.1-3 IsPermGroupoid[0X
  
  [2X> IsPermGroupoid( [0X[3Xgpd[0X[2X ) ____________________________________________[0Xproperty
  [2X> IsPcGroupoid( [0X[3Xgpd[0X[2X ) ______________________________________________[0Xproperty
  [2X> IsFpGroupoid( [0X[3Xgpd[0X[2X ) ______________________________________________[0Xproperty
  
  A  groupoid is a permutation groupoid if all its components have permutation
  groups.  Most of the examples in this chapter are permutation groupoids, but
  in principle any type of group known to [5XGAP[0X may be used.
  
  In the following example [10XGf2[0X is an fp-groupoid, while [10XGq8[0X is a pc-groupoid.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> f2 := FreeGroup( 2 );;[0X
    [4Xgap> SetName( f2, "f2" );[0X
    [4Xgap> Gf2 := Groupoid( -22, f2 );;[0X
    [4Xgap> q8 := SmallGroup( 8, 4 );;[0X
    [4Xgap> Gq8 := Groupoid( [ -28, -27 ], q8 );;[0X
    [4Xgap> SetName( q8, "q8" );  SetName( Gq8, "Gq8" );[0X
    [4Xgap> Gf2q8 := Groupoid( [ Gf2, Gq8 ] );;[0X
    [4Xgap> [ IsFpGroupoid( Gf2 ), IsPcGroupoid( Gq8 ), IsPcGroupoid( Gf2q8 ) ];[0X
    [4X[ true, true, false ][0X
    [4Xgap> G4 := Groupoid( [ Gd8c6, Gf2, Gq8 ] );;[0X
    [4Xgap> Display( G4 );[0X
    [4XGroupoid with 4 components:[0X
    [4X< objects: [ -28, -27 ][0X
    [4X    group: q8 = <[ f1, f2, f3 ]> >[0X
    [4X< objects: [ -22 ][0X
    [4X    group: f2 = <[ f1, f2 ]> >[0X
    [4X< objects: [ -9, -8, -7 ][0X
    [4X    group: d8 = <[ (1,2,3,4), (1,3) ]> >[0X
    [4X< objects: [ -6 ][0X
    [4X    group: c6 = <[ (5,6,7)(8,9) ]> >[0X
    [4Xgap> G4 = Groupoid( [ Gq8, Gf2, Gd8c6 ] );[0X
    [4Xtrue[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X2.1-4 GroupoidElement[0X
  
  [2X> GroupoidElement( [0X[3Xgpd, elt, tail, head[0X[2X ) _________________________[0Xoperation
  [2X> IsElementOfGroupoid( [0X[3Xelt[0X[2X ) _______________________________________[0Xproperty
  [2X> GroupElement( [0X[3Xelt[0X[2X ) _____________________________________________[0Xattribute
  [2X> Tail( [0X[3Xelt[0X[2X ) _____________________________________________________[0Xattribute
  [2X> Head( [0X[3Xelt[0X[2X ) _____________________________________________________[0Xattribute
  [2X> Size( [0X[3Xgpd[0X[2X ) _____________________________________________________[0Xattribute
  
  A   [13Xgroupoid   element[0X  [10Xe[0X  is  a  triple  consisting  of  a  group  element,
  [10XGroupElement(e)[0X  or  [10Xe![1][0X;  the tail (source) object, [10XTail(e)[0X or [10Xe![2][0X; and
  the head (target) object, [10XHead(e)[0X or [10Xe![3][0X.
  
  The  [10XSize[0X of a groupoid is the number of its elements which, for a connected
  groupoid,  is  the  product  of the size of the group with the square of the
  number of objects.
  
  Groupoid elements have a [13Xpartial composition[0X: two elements may be multiplied
  when  the head of the first coincides with the tail of the second. Conjugate
  a^b is defined when a is a loop at the tail of b.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> e1 := GroupoidElement( Gd8, (1,2)(3,4), -9, -8 );[0X
    [4X[(1,2)(3,4) : -9 -> -8][0X
    [4Xgap> e2 := GroupoidElement( Gd8, (1,3), -8, -7 );;[0X
    [4Xgap> Print( [ GroupElement( e2 ), Tail( e2 ), Head( e2 ) ], "\n" );[0X
    [4X[ (1,3), -8, -7 ][0X
    [4Xgap> prod := e1*e2;[0X
    [4X[(1,2,3,4) : -9 -> -7][0X
    [4Xgap> e3 := GroupoidElement( Gd8, (1,3)(2,4), -7, -9 );;[0X
    [4Xgap> cycle := prod*e3;[0X
    [4X[(1,4,3,2) : -9 -> -9][0X
    [4Xgap> cycle^2;[0X
    [4X[(1,3)(2,4) : -9 -> -9][0X
    [4Xgap> Order( cycle );[0X
    [4X4[0X
    [4Xgap> cycle^e1;[0X
    [4X[(1,2,3,4) : -8 -> -8][0X
    [4Xgap> [ Size( Gd8 ), Size( Gc6 ), Size( Gd8c6 ), Size( Gf2q8 ) ];[0X
    [4X[ 72, 6, 78, infinity ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X2.1-5 IsConnectedGroupoid[0X
  
  [2X> IsConnectedGroupoid( [0X[3Xgpd[0X[2X ) _______________________________________[0Xproperty
  [2X> IsDiscreteGroupoid( [0X[3Xgpd[0X[2X ) ________________________________________[0Xproperty
  
  The  forgetful  functor, which forgets the composition of elements, maps the
  category  of  groupoids  and their morphisms to the category of digraphs and
  their  morphisms.  Applying  this functor to a particular groupoid gives the
  [13Xunderlying  digraph[0X  of  the  groupoid.  A  groupoid  is  [13Xconnected[0X  if  its
  underlying digraph is connected (and so complete). A groupoid is [13Xdiscrete[0X if
  it  is a union of groups, so that all the arcs in its underlying digraph are
  loops. It is sometimes convenient to call a groupoid element a [13Xloop[0X when its
  tail and head are the same object.
  
  
  [1X2.2 Subgroupoids[0X
  
  [1X2.2-1 SubgroupoidByComponents[0X
  
  [2X> SubgroupoidByComponents( [0X[3Xgpd, obhoms[0X[2X ) __________________________[0Xoperation
  [2X> Subgroupoid( [0X[3Xargs[0X[2X ) ______________________________________________[0Xfunction
  [2X> FullSubgroupoid( [0X[3Xgpd, obs[0X[2X ) _____________________________________[0Xoperation
  [2X> MaximalDiscreteSubgroupoid( [0X[3Xgpd[0X[2X ) _______________________________[0Xattribute
  [2X> DiscreteSubgroupoid( [0X[3Xgpd, obs, sgps[0X[2X ) ___________________________[0Xoperation
  [2X> FullIdentitySubgroupoid( [0X[3Xgpd[0X[2X ) __________________________________[0Xattribute
  [2X> DiscreteIdentitySubgroupoid( [0X[3Xgpd[0X[2X ) ______________________________[0Xattribute
  
  A  [13Xsubgroupoid[0X [10Xsgpd[0X of [10Xgpd[0X has as objects a subset of the objects of [10Xgpd[0X. It
  is  [13Xwide[0X if all the objects are included. It is [13Xfull[0X if, for any two objects
  in [10Xsgpd[0X, the [10XHomset[0X is the same as in [10Xgpd[0X. The elements of [10Xsgpd[0X are a subset
  of  those  of [10Xgpd[0X, closed under multiplication and with tail and head in the
  chosen object set.
  
  There  are  a  variety  of constructors for a subgroupoid of a groupoid. The
  operation  [10XSubgroupoidByComponents[0X  is  the most general. Its two parameters
  are  a  groupoid and a list of connected components, where each component is
  specified  as a list [10X[obs,sgp][0X, [10Xobs[0X is a subset of the objects in one of the
  components of [10Xgpd[0X, and [10Xsgp[0X is a subgroup of the group in that component.
  
  The  [10XFullSubgroupoid[0X  of  a  groupoid  [10Xgpd[0X  on  a  subset [10Xobs[0X of its objects
  contains all the elements of [10Xgpd[0X with tail and head in [10Xobs[0X.
  
  A   subgroupoid   is   [13Xdiscrete[0X   if   it   is   a   union  of  groups.  The
  [10XMaximalDiscreteSubgroupoid[0X of [10Xgpd[0X is the union of all the single-object full
  subgroupoids of [10Xgpd[0X.
  
  An [13Xidentity subgroupoid[0X has trivial object groups, but need not be discrete.
  A connected identity groupoid is sometimes called a [13Xtree groupoid[0X.
  
  The global function [10XSubgroupoid[0X should call the appropriate operation.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> c4d := Subgroup( d8, [ (1,2,3,4) ] );;[0X
    [4Xgap> k4d := Subgroup( d8, [ (1,2)(3,4), (1,3)(2,4) ] );;[0X
    [4Xgap> SetName( c4d, "c4d" );  SetName( k4d, "k4d" );[0X
    [4Xgap> Ud8 := Subgroupoid( Gd8, [ [[-9, k4d]], [[-8,-7], c4d] ] );;[0X
    [4Xgap> SetName( Ud8, "Ud8" );[0X
    [4Xgap> Display( Ud8 );[0X
    [4XPerm Groupoid with 2 components:[0X
    [4X< objects: [ -9 ][0X
    [4X    group: k4d = <[ (1,2)(3,4), (1,3)(2,4) ]> >[0X
    [4X< objects: [ -8, -7 ][0X
    [4X    group: c4d = <[ (1,2,3,4) ]> >[0X
    [4Xgap> FullSubgroupoid( Gd8c6, [-7,-6] );[0X
    [4XPerm Groupoid with components:[0X
    [4X< [ -7 ], d8 >[0X
    [4X< [ -6 ], c6 >[0X
    [4Xgap> DiscreteSubgroupoid( Gd8c6, [-9,-8], [ c4d, k4d ] );[0X
    [4XPerm Groupoid with components:[0X
    [4X< [ -9 ], c4d >[0X
    [4X< [ -8 ], k4d >[0X
    [4Xgap> FullIdentitySubgroupoid( Ud8 );[0X
    [4XPerm Groupoid with components:[0X
    [4X< [ -9 ], id(k4d) >[0X
    [4X< [ -8, -7 ], id(c4d) >[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X2.3 Stars, Costars and Homsets[0X
  
  [1X2.3-1 ObjectStar[0X
  
  [2X> ObjectStar( [0X[3Xgpd, obj[0X[2X ) __________________________________________[0Xoperation
  [2X> ObjectCostar( [0X[3Xgpd, obj[0X[2X ) ________________________________________[0Xoperation
  [2X> Homset( [0X[3Xgpd, tail, head[0X[2X ) _______________________________________[0Xoperation
  
  The  [13Xstar[0X  at  [10Xobj[0X  is  the set of groupoid elements which have [10Xobj[0X as tail,
  while  the  [13Xcostar[0X is the set of elements which have [10Xobj[0X as head. The [13Xhomset[0X
  from  [10Xobj1[0X  to [10Xobj2[0X is the set of elements with the specified tail and head,
  and  so  is  bijective  with  the elements of the group. Thus every star and
  every costar is a union of homsets.
  
  In  order  not  to  create  unneccessary long lists, these operations return
  objects  of  type  [10XIsHomsetCosetsRep[0X  for which an [10XIterator[0X is provided. (An
  [10XEnumerator[0X is not yet implemented.)
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> star9 := ObjectStar( Gd8, -9 );[0X
    [4X<star at [ -9 ] with group d8>[0X
    [4Xgap> for e in star9 do[0X
    [4X>      if ( Order( e![1] ) = 4 ) then Print( e, "\n" ); fi;[0X
    [4X>    od;[0X
    [4X[(1,4,3,2) : -9 -> -9][0X
    [4X[(1,4,3,2) : -9 -> -8][0X
    [4X[(1,4,3,2) : -9 -> -7][0X
    [4X[(1,2,3,4) : -9 -> -9][0X
    [4X[(1,2,3,4) : -9 -> -8][0X
    [4X[(1,2,3,4) : -9 -> -7][0X
    [4Xgap> costar6 := ObjectCostar( Gc6, -6 );[0X
    [4X<costar at [ -6 ] with group c6>[0X
    [4Xgap> hset78 := Homset( Ud8, -7, -8 );[0X
    [4X<homset -7 -> -8 with group c4d>[0X
    [4Xgap> for e in hset78 do  Print( e, "\n" );  od;[0X
    [4X[() : -7 -> -8][0X
    [4X[(1,3)(2,4) : -7 -> -8][0X
    [4X[(1,4,3,2) : -7 -> -8][0X
    [4X[(1,2,3,4) : -7 -> -8][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X2.3-2 IdentityElement[0X
  
  [2X> IdentityElement( [0X[3Xgpd, obj[0X[2X ) _____________________________________[0Xoperation
  
  The  identity  groupoid element [10X1\_{o}[0X of [10Xgpd[0X at object [10Xo[0X is [10X[e,o,o][0X where [10Xe[0X
  is the identity group element in the object group. It is a left identity for
  the star and a right identity for the costar at that object.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> i7 := IdentityElement( Gd8, -7 );;[0X
    [4Xgap> i8 := IdentityElement( Gd8, -8 );;[0X
    [4Xgap> L := [ i7, i8 ];;[0X
    [4Xgap> for e in hset78 do  Add( L, i7*e*i8 = e );  od;[0X
    [4Xgap> L;[0X
    [4X[ [() : -7 -> -7], [() : -8 -> -8], true, true, true, true ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X2.4 Left, right and double cosets[0X
  
  [1X2.4-1 RightCoset[0X
  
  [2X> RightCoset( [0X[3XG, U, elt[0X[2X ) _________________________________________[0Xoperation
  [2X> RightCosetRepresentatives( [0X[3XG, U[0X[2X ) _______________________________[0Xoperation
  [2X> RightCosetsNC( [0X[3XG, U[0X[2X ) ___________________________________________[0Xoperation
  [2X> LeftCoset( [0X[3XG, U, elt[0X[2X ) __________________________________________[0Xoperation
  [2X> LeftCosetRepresentatives( [0X[3XG, U[0X[2X ) ________________________________[0Xoperation
  [2X> LeftCosetRepresentativesFromObject( [0X[3XG, U, obj[0X[2X ) _________________[0Xoperation
  [2X> LeftCosetsNC( [0X[3XG, U[0X[2X ) ____________________________________________[0Xoperation
  [2X> DoubleCoset( [0X[3XG, U, elt, V[0X[2X ) _____________________________________[0Xoperation
  [2X> DoubleCosetRepresentatives( [0X[3XG, U, V[0X[2X ) ___________________________[0Xoperation
  [2X> DoubleCosetsNC( [0X[3XG, U, V[0X[2X ) _______________________________________[0Xoperation
  
  If  [10XU[0X  is  a  wide  subgroupoid  of  G,  the  [13Xright cosets[0X of U in G are the
  equivalence classes of the relation on the elements of G where g1 is related
  to  g2  if  and  only  if g2 = u*g1 for some element u of U. The right coset
  containing  g is written Ug. These right cosets refine the costars of G and,
  in  particular,  U1_o  is the costar of U at o, so that (unlike groups) U is
  itself a coset only when G has a single object.
  
  The  [13Xright  coset  representatives[0X  for  U  in  G form a list containing one
  groupoid  element  for each coset where, in a particular component of U, the
  group  element chosen is the right coset representative of the group of U in
  the group of G.
  
  Similarly, the [13Xleft cosets[0X gU refine the stars of G, while [13Xdouble cosets[0X are
  unions    of    left   cosets   and   of   right   cosets.   The   operation
  [10XLeftCosetRepresentativesFromObject(  G,  U,  obj )[0X is used in Chapter 4, and
  returns only those representatives which have tail at [10Xobj[0X.
  
  As  with stars and homsets, these cosets are implemented with representation
  [10XIsHomsetCosetsRep[0X  and provided with an iterator. Note that, when U has more
  than one component, cosets may have differing lengths.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> re2 := RightCoset( Gd8, Ud8, e2 );[0X
    [4XRightCoset(c4d,[(1,3) : -8 -> -7])[0X
    [4Xgap> for x in re2 do Print( x, "\n" ); od;[0X
    [4X[(1,3) : -8 -> -8][0X
    [4X[(1,3) : -7 -> -8][0X
    [4X[(2,4) : -8 -> -8][0X
    [4X[(2,4) : -7 -> -8][0X
    [4X[(1,4)(2,3) : -8 -> -8][0X
    [4X[(1,4)(2,3) : -7 -> -8][0X
    [4X[(1,2)(3,4) : -8 -> -8][0X
    [4X[(1,2)(3,4) : -7 -> -8][0X
    [4Xgap> rcrd8 := RightCosetRepresentatives( Gd8, Ud8 );[0X
    [4X[ [() : -9 -> -9], [() : -9 -> -8], [() : -9 -> -7], [(2,4) : -9 -> -9],[0X
    [4X  [(2,4) : -9 -> -8], [(2,4) : -9 -> -7], [() : -8 -> -9], [() : -8 -> -8],[0X
    [4X  [() : -8 -> -7], [(2,4) : -8 -> -9], [(2,4) : -8 -> -8], [(2,4) : -8 -> -7][0X
    [4X ][0X
    [4Xgap> lcr7 := LeftCosetRepresentativesFromObject( Gd8, Ud8, -7 );[0X
    [4X[ [() : -7 -> -9], [(2,4) : -7 -> -9], [() : -7 -> -8], [(2,4) : -7 -> -8] ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  More  examples  of  these  operations  may  be  found  in  the  example file
  [11Xgpd/examples/gpd.g[0X.
  
