<!-- ------------------------------------------------------------------- -->
<!--                                                                     -->
<!--  util.xml              XMod documentation            Chris Wensley  -->
<!--                                                        & Murat Alp  -->
<!--  Copyright (C) 2001-2016, Chris Wensley et al,                      --> 
<!--  School of Computer Science, Bangor University, U.K.                --> 
<!--                                                                     -->
<!-- ------------------------------------------------------------------- -->

<?xml version="1.0" encoding="UTF-8"?>

<Chapter Label="chap-util">
<Heading>Utility functions</Heading>

By a utility function we mean a &GAP; function which is

<List>
<Item>
needed by other functions in this package,
</Item>
<Item>
not (as far as we know) provided by the standard &GAP; library,
</Item>
<Item>
more suitable for inclusion in the main library than in this package.
</Item>
</List>

Sections on <E>Printing Lists</E> and 
<E>Distinct and Common Representatives</E> 
were moved to the <Package>Utils</Package> package with version 2.56. 


<Section><Heading>Inclusion and Restriction Mappings</Heading>

<Index>inclusion mapping</Index>
<Index>restriction mapping</Index>

These functions have been moved to the <Package>gpd</Package> package, 
but are still documented here. 
<ManSection>
   <Oper Name="InclusionMappingGroups"
         Arg="G H" />
   <Oper Name="MappingToOne"
         Arg="G H" />
<Description>
This set of utilities concerns mappings.
The map <C>incd8</C> is the inclusion of <C>d8</C> in <C>d16</C> 
used in Section <Ref Sect="sect-oper-mor" />. 
<C>MappingToOne(G,H)</C> maps the whole of <M>G</M> to the identity element 
in <M>H</M>. 
</Description>
</ManSection>
<P/>
<Example>
<![CDATA[
gap> Print( incd8, "\n" );
[ (11,13,15,17)(12,14,16,18), (11,18)(12,17)(13,16)(14,15) ] ->
[ (11,13,15,17)(12,14,16,18), (11,18)(12,17)(13,16)(14,15) ]
gap> imd8 := Image( incd8 );;
gap> MappingToOne( c4, imd8 );
[ (11,13,15,17)(12,14,16,18) ] -> [ () ]
]]>
</Example>

<ManSection>
   <Oper Name="InnerAutomorphismsByNormalSubgroup"
         Arg="G N" />
   <Prop Name="IsGroupOfAutomorphisms"
         Arg="A" />
<Description>
Inner automorphisms of a group <C>G</C> 
by the elements of a normal subgroup <C>N</C>
are calculated with the first of these functions, 
usually with <C>G</C> = <C>N</C>.
</Description>
</ManSection>
<P/>
<Example>
<![CDATA[
gap> autd8 := AutomorphismGroup( d8 );;
gap> innd8 := InnerAutomorphismsByNormalSubgroup( d8, d8 );;
gap> GeneratorsOfGroup( innd8 );
[ ^(1,2,3,4), ^(1,3) ]
gap> IsGroupOfAutomorphisms( innd8 );
true
]]>
</Example>
</Section>


<Section><Heading>Abelian Modules</Heading>
<Index>abelian module</Index>

<ManSection>
   <Oper Name="AbelianModuleObject"
         Arg="grp act" />
   <Prop Name="IsAbelianModule"
         Arg="obj" />
   <Attr Name="AbelianModuleGroup"
         Arg="obj" />
   <Attr Name="AbelianModuleAction"
         Arg="obj" />
<Description>
An abelian module is an abelian group together with a group action.
These are used by the crossed module constructor 
<Ref Oper="XModByAbelianModule"/>.
<P/>
The resulting <C>Xabmod</C> is isomorphic to the output from 
<C>XModByAutomorphismGroup( k4 );</C>.
</Description>
</ManSection>
<P/>
<Example>
<![CDATA[
gap> x := (6,7)(8,9);;  y := (6,8)(7,9);;  z := (6,9)(7,8);;
gap> k4a := Group( x, y );;  SetName( k4a, "k4a" );
gap> gens3a := [ (1,2), (2,3) ];;
gap> s3a := Group( gens3a );;  SetName( s3a, "s3a" );
gap> alpha := GroupHomomorphismByImages( k4a, k4a, [x,y], [y,x] );;
gap> beta := GroupHomomorphismByImages( k4a, k4a, [x,y], [x,z] );;
gap> auta := Group( alpha, beta );;
gap> acta := GroupHomomorphismByImages( s3a, auta, gens3a, [alpha,beta] );;
gap> abmod := AbelianModuleObject( k4a, acta );;
gap> Xabmod := XModByAbelianModule( abmod );
[k4a->s3a]
gap> Display( Xabmod );

Crossed module [k4a->s3a] :- 
: Source group k4a has generators:
  [ (6,7)(8,9), (6,8)(7,9) ]
: Range group s3a has generators:
  [ (1,2), (2,3) ]
: Boundary homomorphism maps source generators to:
  [ (), () ]
: Action homomorphism maps range generators to automorphisms:
  (1,2) --> { source gens --> [ (6,8)(7,9), (6,7)(8,9) ] }
  (2,3) --> { source gens --> [ (6,7)(8,9), (6,9)(7,8) ] }
  These 2 automorphisms generate the group of automorphisms.

]]>
</Example>
</Section>


</Chapter>
