<!-- ------------------------------------------------------------------- -->
<!--                                                                     -->
<!--  gpdmor.xml             Gpd documentation            Chris Wensley  -->
<!--                                                       & Emma Moore  -->
<!--                                                                     -->
<!--  $Id: gpdmor.xml,v 1.01 2006/05/17 gap Exp $                        -->
<!--                                                                     -->
<!-- ------------------------------------------------------------------- -->

<?xml version="1.0" encoding="ISO-8859-1"?>
  <!-- $Id: gpd.xml,v 1.01  Exp $ -->

<Chapter Label="chap-gpdmor">
<Heading>Morphisms of Groupoids</Heading>

A <E>morphism</E> <M>m</M> from a groupoid <M>G</M> to a groupoid <M>H</M>
consists of a map from the objects of <M>G</M> to those of <M>H</M>
together with a map from the elements of <M>G</M> to those of <M>H</M>
which is compatible with tail and head and which preserves multiplication: 
<Display>
m(g1 : o1 \to o2)*m(g2 : o2 \to o3) ~=~ m(g1*g2 : o1 \to o3).
</Display>
<P/>
Note that when a morphism is not injective on objects, 
the image of the source need not be a subgroupoid of the range.
The simplest example of this is given by mapping the two-object 
groupoid with trivial group to the free group <M>\langle a \rangle</M> 
on one generator, when the image is <M>[1,a,a^{-1}]</M>.


<Section><Heading>Morphisms to a connected groupoid</Heading>

<ManSection>
   <Func Name="MorphismOfConnectedGroupoids"
         Arg="G, H, imobs, hom" />
   <Attr Name="Source"
         Arg="mor" />
   <Attr Name="Range"
         Arg="mor" />
   <Attr Name="ComponentImages"
         Arg="mor" />
<Description>
As usual, there are a variety of morphism constructors.
The basic construction is a morphism <M>G \to H</M> with <M>H</M> connected, 
which is implemented as <C>IsMorphismToConnectedGroupoidRep</C> 
with attributes <C>Source</C>, <C>Range</C> and <C>ComponentImages</C>.
If <M>G</M> is also connected, we may apply 
<C>MorphismOfConnectedGroupoids</C>, requiring:
<List>
<Item>
a list <C>imobs</C> of the images of the objects of <M>G</M>;
</Item>
<Item>
a homomorphism <C>hom</C> from the group of <M>G</M> to the group of <M>H</M>.
</Item>
</List>
<P/>
</Description>
</ManSection>
<Example>
<![CDATA[
gap> d12 := Group( (15,16,17,18,19,20, (15,20)(16,19)(17,18) );;
gap> Gd12 := ConnectedGroupoid( [-37,-36,-35,-34], d12 );;
gap> SetName( d12, "d12" );  SetName( Gd12, "Gd12" );
gap> s3d := Subgroup( d12, [ (15,17,19)(16,18,20), (15,20)(16,19)(17,18) ] );
gap> Gs3d := SubgroupoidByComponents( Gd12, [ [[-36,-35,-34], s3d] ] );;
gap> SetName( s3d, "s3d" );  SetName( Gs3d, "Gs3d" );
gap> gend8 := GeneratorsOfGroup( d8 );;
gap> imhd8 := [ ( ), (15,20)(16,19)(17,18) ];;
gap> hd8 := GroupHomomorphismByImages( d8, s3d, gend8, imhd8 );
gap> md8 := MorphismOfConnectedGroupoids( Gd8, Gs3d, [-34,-35,-36], hd8 );
Groupoid morphism : Gd8 -> Gs3d 
gap> IsBijectiveOnObjects( md8 );
true
gap> Display( md8 );
Morphism to connected groupoid:
[ Gd8 ] -> [ Gs3d ]
  object map = [ [ -9, -8, -7 ], [ -34, -35, -36 ] ]
homomorphism = [ [ (1,2,3,4), (1,3) ], [ (), (15,20)(16,19)(17,18) ] ]
]]>
</Example>

<ManSection>
   <Func Name="MorphismToConnectedGroupoid"
         Arg="G, H, obhoms" />
   <Func Name="GroupoidMorphismWithCommonRange"
         Arg="G, H, mors" />
   <Func Name="GroupoidMorphism"
         Arg="args" />
<Description>
When <M>G</M> is not connected the appropriate operation is 
<C>MorphismToConnectedGroupoid( G, H, obhoms )</C>, 
where the third parameter is a list <C>ComponentImages( mor )</C> 
of <C>[imobs,hom]</C> pairs.
<P/>
The operation <C>GroupoidMorphismWithCommonRange</C> 
combines into a single morphism two or more morphisms, 
in the list <C>mors</C>, 
with range <M>H</M> and source a subgroupoid of <M>G</M>. 
<P/>
The global function <C>GroupoidMorphism</C> will normally find the 
appropriate operation to call.
<P/>
</Description>
</ManSection>
<Example>
<![CDATA[
gap> hc6 := GroupHomomorphismByImages( c6, s3d, [(5,6,7)(8,9)], [(15,19)(16,18)] );;
gap> mc6 := GroupoidMorphism( Gc6, Gs3d, [ -36 ], hc6 );;
gap> md8c6 := MorphismToConnectedGroupoid( Gd8c6, Gs3d, 
              [ [[-34,-35,-36], hd8], [[-36], hc6] ] );
Groupoid morphism : Gd8+Gc6 -> Gs3d
gap> Display( md8c6 );
Morphism to connected groupoid with components:
[ Gd8 ] -> [ Gs3d ]
  object map = [ [ -9, -8, -7 ], [ -34, -35, -36 ] ]
homomorphism = [ [ (1,2,3,4), (1,3) ], [ (), (15,20)(16,19)(17,18) ] ]
[ Gc6 ] -> [ Gs3d ]
  object map = [ [ -6 ], [ -36 ] ]
homomorphism = [ [ (5,6,7)(8,9) ], [ (15,19)(16,18) ] ]
gap> 
gap> gens3d := GeneratorsOfGroup( s3d );;
gap> imas3d := [ (15,17,19)(16,18,20), (15,16)(17,20)(18,19) ];;
gap> as3d := GroupHomomorphismByImages( s3d, s3d, gens3d, imas3d );;
gap> aGs3d := MorphismOfConnectedGroupoids( Gs3d, Gs3d, [-35,-34,-36], as3d );;
gap> IsGroupoidAutomorphism( aGs3d );
true
gap> Order( aGs3d );
3
gap> Gs3dd8 := GroupoidByUnion( [ Gd8, Gs3d ] );;
gap> SetName( Gs3dd8, "Gs3d+Gd8" );;
gap> common := GroupoidMorphismWithCommonRange( Gs3dd8, Gs3d, [ aGs3d, md8 ] );;
gap> Display( common );
Morphism to connected groupoid with components:
[ Gs3d ] -> [ Gs3d ]
  object map = [ [ -36, -35, -34 ], [ -35, -34, -36 ] ]
homomorphism = [ [ (15,17,19)(16,18,20), (15,20)(16,19)(17,18) ],
  [ (15,17,19)(16,18,20), (15,16)(17,20)(18,19) ] ]
[ Gd8 ] -> [ Gs3d ]
  object map = [ [ -9, -8, -7 ], [ -34, -35, -36 ] ]
homomorphism = [ [ (1,2,3,4), (1,3) ], [ (), (15,20)(16,19)(17,18) ] ]
]]>
</Example>

<ManSection>
   <Oper Name="IsomorphismNewObjects"
         Arg="gpd, obs" />
   <Attr Name="IdentityMapping"
         Arg="gpd" />
<Description>
The function <C>IsomorphismNewObjects</C> provides an isomorphism to 
an isomorphic groupoid with a new set of objects.
The function <C>IdentityMapping</C>, already provided for groups, 
is also implemented for groupoids.
<P/>
</Description>
</ManSection>
<Example>
<![CDATA[
gap> idGd8 := IdentityMapping( Gd8 );
Groupoid morphism: [ Gd8 ] -> [ Gd8 ]
gap> copys3d := IsomorphismNewObjects( Gs3d, [-24,-25,-26] );;
gap> Hs3d := Range( copys3d );;
gap> SetName( Hs3, "Hs3" );
gap> Display( copys3d );
Morphism to connected groupoid:
[ Gs3d ] -> [ Hs3d ]
  object map = [ [ -36, -35, -34 ], [ -32, -31, -30 ] ]
homomorphism = [ [ (15,17,19)(16,18,20), (15,20)(16,19)(17,18) ],
  [ (15,17,19)(16,18,20), (15,20)(16,19)(17,18) ] ]
]]>
</Example>

<ManSection>
   <Oper Name="InclusionMappingGroupoids"
         Arg="G, U" />
   <Oper Name="RestrictionMappingGroupoids"
         Arg="hom, src, rng" />
<Description>
We have added functions <C>InclusionMappingGroupoids</C> and 
<C>RestrictionMappingGroupoids</C>, corresponding to 
<C>InclusionMappingGroups</C> and <C>RestrictionMappingGroups</C> for groups.
At present <C>RestrictionMappingGroups</C> is only implemented for the case 
where the source and range of the morphism are connected.
<P/>
</Description>
</ManSection>
<Example>
<![CDATA[
gap> SetName( ComponentsOfGroupoid(Ud8)[1], "Ud8a" );
gap> SetName( ComponentsOfGroupoid(Ud8)[2], "Ud8b" );
gap> inc := InclusionMappingGroupoids( Gd8, Ud8 );;
gap> Display( inc );
Morphism to connected groupoid with components:
[ Ud8a ] -> [ Gd8 ]
  object map = [ [ -9 ], [ -9 ] ]
homomorphism = [ [ (1,2)(3,4), (1,3)(2,4) ], [ (1,2)(3,4), (1,3)(2,4) ] ]
[ Ud8b ] -> [ Gd8 ]
  object map = [ [ -8, -7 ], [ -8, -7 ] ]
homomorphism = [ [ (1,2,3,4) ], [ (1,2,3,4) ] ]
gap> res := RestrictionMappingGroupoids( md8, Ud8, Gs3d );
gap> Display( res );
Morphism to connected groupoid with components:
[ Ud8a ] -> [ Gs3d ]
  object map = [ [ -9 ], [ -34 ] ]
homomorphism = [ [ (1,2)(3,4), (1,3)(2,4) ], [ (15,20)(16,19)(17,18), () ] ]
[ Ud8b ] -> [ Gs3d ]
  object map = [ [ -8, -7 ], [ -35, -36 ] ]
homomorphism = [ [ (1,2,3,4) ], [ () ] ]
]]>
</Example>
</Section> 


<Section><Heading>General Morphisms and composites</Heading>

<ManSection>
   <Oper Name="GroupoidMorphismByComponents"
         Arg="G, H, mors" />
   <Func Name="GroupoidMorphismByUnion"
         Arg="mors" />
<Description>
When <M>H</M> is not connected, a groupoid morphism from <M>G</M> to <M>H</M> 
is a union of a list <C>mors</C> of morphisms of connected groupoids.
<P/>
There are two ways of combining <C>m1 : G1->H1</C> and <C>m2 : G2->H2</C> 
into a single morphism.
The operation <C>GroupoidMorphismByUnion( [m1,m2] );</C> 
constucts the groupoid unions <C>G12,H12</C> of <C>G1</C> with <C>G2</C> 
and <C>H1</C> with <C>H2</C>, and then a morphism <C>m12 : G12->H12</C>. 
If <C>G12,H12</C> have already been constructed, the operation 
<C>GroupoidMorphismByComponents( G12, H12, [m1,m2] );</C> 
may be more appropriate.
<P/>
</Description>
</ManSection>
<Example>
<![CDATA[
gap> imad8 := [ (1,2,3,4), (2,4) ];;
gap> ad8 := GroupHomomorphismByImages( d8, d8, [(1,2,3,4),(1,3)], imad8 );;
gap> aGd8 := MorphismOfConnectedGroupoids( Gd8, Gd8, [-8,-7,-9], ad8 );;
gap> mor1 := GroupoidMorphismByUnion( [ aGd8, mc6 ] );;
gap> mor2 := GroupoidMorphismByComponents( Gd8c6, Gs3dd8, [ aGd8, mc6 ] );;
gap> Display( mor2 );
Groupoid Morphism: Gd8+Gc6 -> Gs3d+Gd8 with components :
[ Gc6 ] -> [ Gs3d ]
  object map = [ [ -6 ], [ -36 ] ]
homomorphism = [ [ (5,6,7)(8,9) ], [ (15,19)(16,18) ] ]
[ Gd8 ] -> [ Gd8 ]
  object map = [ [ -9, -8, -7 ], [ -8, -7, -9 ] ]
homomorphism = [ [ (1,2,3,4), (1,3) ], [ (1,2,3,4), (2,4) ] ]
gap> mor1 = mor2;
true
]]>
</Example>

<ManSection>
   <Prop Name="IsGroupoidMorphism"
         Arg="mor" />
   <Prop Name="IsInjectiveOnObjects"
         Arg="mor" />
   <Prop Name="IsSurjectiveOnObjects"
         Arg="mor" />
   <Prop Name="IsBijectiveOnObjects"
         Arg="mor" />
   <Prop Name="IsGroupoidAutomorphism"
         Arg="mor" />
<Description>
Here are some of the basic properties of groupoid morphisms. 
<P/>
</Description>
</ManSection>
<Example>
<![CDATA[
gap> IsGroupoidMorphism( res );
true
gap> IsInjectiveOnObjects( res );
true
gap> IsInjective( res );
false
gap> IsSurjectiveOnObjects( inc );
true
gap> IsSurjective( inc );
false
gap> IsGroupoidAutomorphism( aGd8 );
true
gap> eGd8 := MorphismOfConnectedGroupoids( Gd8, Gd8, [-7,-7,-9], ad8 );;
gap> IsGroupoidEndomorphism( eGd8 );
true
]]>
</Example>

<ManSection>
   <Attr Name="ImagesOfObjects"
         Arg="mor" />
   <Attr Name="ImagesSource"
         Arg="mor" />
   <Oper Name="ImageElm"
         Arg="mor, elt" />
<Description>
Here are some of examples of operations that return images. 
These are not yet fully implemented: for example, <C>ImageElm</C> and
<C>ImagesSource</C> require the range of <C>mor</C> to be connected.
<P/>
</Description>
</ManSection>
<Example>
<![CDATA[
gap> ImagesOfObjects( md8 );
[ [ -34, -35, -36, -36 ] ]
gap> ImagesSource(md8);
Perm Connected Groupoid:
< [ -36, -35, -34 ], Group( [ (), (15,20)(16,19)(17,18) ] ) >
gap> e1;
[(1,2)(3,4) : -9 -> -8]
gap> ImageElm( md8c6, e1 );
[(15,20)(16,19)(17,18) : -34 -> -35]
]]>
</Example>

<ManSection>
   <Oper Name="Product"
         Arg="mors" />
<Description>
<Index>*,\^{} for groupoid morphisms</Index>
Morphisms <M>m_1, m_2</M> can be composed if the image of <M>m_1</M> 
is contained in the domain of <M>m_2</M>.
Currently composition is only defined for morphisms of connected groupoids.
<P/>
</Description>
</ManSection>
<Example>
<![CDATA[
gap> Hk4d := SubgroupoidByComponents( Gd8, [ [[-9,-8,-7], k4d] ] );;
gap> genq8 := GeneratorsOfGroup(q8);;
gap> hq8 := GroupHomomorphismByImages( q8,k4d,genq8,[(1,2)(3,4),(1,3)(2,4),()]);;
gap> mq8 := GroupoidMorphism( Gq8, Hk4d, [-7,-9], hq8 );;
gap> iHk4d := InclusionMappingGroupoids( Gd8, Hk4d );;
gap> mor3 := mq8*iHk4d;;
gap> Display( mor3 );
Morphism to connected groupoid:
[ Gq8 ] -> [ Gd8 ]
  object map = [ [ -28, -27 ], [ -7, -9 ] ]
homomorphism = [ Pcgs([ f1, f2, f3 ]), [ (1,2)(3,4), (1,3)(2,4), () ] ]
gap> mor4 := mor1*aGd8;;
gap> Display( mor4 );
Morphism to connected groupoid:
[ Gq8 ] -> [ Gd8 ]
  object map = [ [ -28, -27 ], [ -9, -8 ] ]
homomorphism = [ Pcgs([ f1, f2, f3 ]), [ (1,4)(2,3), (1,3)(2,4), () ] ]
]]>
</Example>

<ManSection>
   <Attr Name="InverseMorphism"
         Arg="mor" />
   <Attr Name="Order"
         Arg="mor" />
<Description>
The <E>inverse</E> of a morphism <M>m</M> is defined when <M>m</M> 
is bijective on objects and on elements. 
The operation <C>InverseMorphism</C> is a synonym for 
<C>InverseGeneralMapping</C>.
The <E>order</E> of an automorphism is the smallest power 
which returns the identity morphism of <M>G</M>.
<P/>
</Description>
</ManSection>
<P/>
<Example>
<![CDATA[
gap> genq8 := GeneratorsOfGroup( q8 );;
gap> imq8 := [ q8.2, q8.1*q8.2, q8.3 ];
[ f2, f1*f2, f3 ]
gap> autq8 := GroupHomomorphismByImages( q8, q8, genq8, imq8 );;
gap> autGq8 := GroupoidMorphism( Gq8, Gq8, [-27,-28], autq8 );;
gap> Display( InverseMorphism( autGq8 ) );
Morphism to connected groupoid:
[ Gq8 ] -> [ Gq8 ]
  object map = [ [ -28, -27 ], [ -27, -28 ] ]
homomorphism = [ [ f2, f1*f2, f3 ], [ f1, f2, f3 ] ]
gap> Order( autGq8 );
6
]]>
</Example>
</Section>

<!-- More examples of these operations may be found in the example file -->
<!-- <F>gpd/examples/gpdmor.g</F>.                                      -->

</Chapter>
