8 Utility functions
  
  By a utility function we mean a {\GAP} function which is
  
  --    needed by other functions in this package,
  
  --    not (as far as we know) provided by the standard GAP library,
  
  --    more suitable for inclusion in the main library than in this package.
  
  
  8.1 Inclusion and Restriction Mappings
  
  These  two  functions  have  been  moved  to  the gpd package, but are still
  documented here.
  
  8.1-1 InclusionMappingGroups
  
  > InclusionMappingGroups( G, H ) __________________________________operation
  > RestrictionMappingGroups( hom, src, rng ) _______________________operation
  > MappingToOne( G, H ) ____________________________________________operation
  
  The  first  set  of  utilities  concerns inclusion and restriction mappings.
  Restriction  may  apply to both the source and the range of the map. The map
  incd8 is the inclusion of d8 in d16 used in Section 3.4.
  
  ---------------------------  Example  ----------------------------
    
    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> resd8 := RestrictionMappingGroups( incd8, c4, imd8 );;
    gap> Source( res8 );  Range( res8 );
    c4
    Group([ (11,13,15,17)(12,14,16,18), (11,18)(12,17)(13,16)(14,15) ])
    gap> MappingToOne( c4, imd8 );
    [ (11,13,15,17)(12,14,16,18) ] -> [ () ]
    
  ------------------------------------------------------------------
  
  
  8.2 Endomorphism Classes and Automorphisms
  
  8.2-1 EndomorphismClasses
  
  > EndomorphismClasses( grp, case ) _________________________________function
  > EndoClassNaturalHom( class ) ____________________________________attribute
  > EndoClassIsomorphism( class ) ___________________________________attribute
  > EndoClassConjugators( class ) ___________________________________attribute
  > AutoGroup( class ) ______________________________________________attribute
  
  The  monoid  of endomorphisms of a group is used when calculating the monoid
  of   derivations   of   a  crossed  module  and  when  determining  all  the
  cat1-structures on a group.
  
  An endomorphism epsilon of R with image H' is determined by
  
  --    a  normal subgroup N of R and a permutation representation theta : R/N
        ->  Q  of  the  quotient,  giving a projection theta circ nu : R -> Q,
        where nu : R -> R/N is the natural homomorphism;
  
  --    an automorphism alpha of Q;
  
  --    a subgroup H' in a conjugacy class [H] of subgroups of R isomorphic to
        Q  having  representative  H,  an  isomorphism  phi  : Q cong H, and a
        conjugating element c in R such that H^c = H'.
  
  Then epsilon takes values
  
  
       \epsilon r ~=~ (\phi\alpha\theta\nu\,r)^c~.
  
  
  Endomorphisms are placed in the same class if they have the same choice of N
  and [H], and so the number of endomorphisms is
  
  
       |{\rm End}(R)| ~=~ \sum_{{\rm classes}} |{\rm Aut}(Q)|.|[H]|~.
  
  
  The  function  EndomorphismClasses(  <grp>,  <case> ) may be called in three
  ways:
  
  --    case 1 includes automorphisms and the zero map,
  
  --    case 2 excludes automorphisms and the zero map,
  
  --    case 3 is when N intersects H trivially.
  
  ---------------------------  Example  ----------------------------
    
    gap> end8 := EndomorphismClasses( d8, 1 );;
    gap> Length( end8 );
    13
    gap> e4 := end8[4];
    <enumerator>
    gap> EndoClassNaturalHom( e4 );
    GroupHomomorphismByImages( d8, Group( [ f1 ] ),
    [ (11,13,15,17)(12,14,16,18), (12,18)(13,17)(14,16) ], [ f1, f1 ] )
    gap> EndoClassIsomorphism( e4 );
    Pcgs([ f1 ]) -> [ (11,13)(14,18)(15,17) ]
    gap> EndoClassConjugators( e4 );
    [ (), (12,18)(13,17)(14,16) ]
    gap> AutoGroup( e4 );
    Group( [ Pcgs([ f1 ]) -> [ f1 ] ] )
    gap> L := List( end8, e -> Length(EndoClassConjugators(e)) * Size(AutoGroup(e)) );
    [ 8, 1, 2, 2, 1, 2, 2, 1, 2, 2, 6, 6, 1 ]
    gap> Sum( L );
    36
    
  ------------------------------------------------------------------
  
  8.2-2 InnerAutomorphismByNormalSubgroup
  
  > InnerAutomorphismByNormalSubgroup( G, N ) _______________________operation
  > IsGroupOfAutomorphisms( A ) ______________________________________property
  
  Inner  automorphisms of a group G by the elements of a normal subgroup N are
  calculated with the first of these functions, usually with G = N.
  
  ---------------------------  Example  ----------------------------
    
    gap> autd8 := AutomorphismGroup( d8 );;
    gap> innd8 := InnerAutomorphismsByNormalSubgroup( d8, d8 );;
    gap> GeneratorsOfGroup( innd8 );
    [ InnerAutomorphism( d8, (11,13,15,17)(12,14,16,18) ),
      InnerAutomorphism( d8, (12,18)(13,17)(14,16) ) ]
    gap> IsGroupOfAutomorphisms( innd8 );
    true 
    
  ------------------------------------------------------------------
  
  
  8.3 Abelian Modules
  
  8.3-1 AbelianModuleObject
  
  > AbelianModuleObject( grp, act ) _________________________________operation
  > IsAbelianModule( obj ) ___________________________________________property
  > AbelianModuleGroup( obj ) _______________________________________attribute
  > AbelianModuleAction( obj ) ______________________________________attribute
  
  An  abelian  module  is an abelian group together with a group action. These
  are used by the crossed module constructor XModByAbelianModule.
  
  The    resulting    Xabmod    is    isomorphic    to    the    output   from
  XModByAutomorphismGroup( k4 );.
  
  ---------------------------  Example  ----------------------------
    
    gap> x := (6,7)(8,9);;  y := (6,8)(7,9);;  z := (6,9)(7,8);;
    gap> k4 := Group( x, y );  SetName( k4, "k4" );
    gap> s3 := Group( (1,2), (2,3) );;  SetName( s3, "s3" );
    gap> alpha := GroupHomomorphismByImages( k4, k4, [x,y], [y,x] );
    gap> beta := GroupHomomorphismByImages( k4, k4, [x,y], [x,z] );
    gap> aut := Group( alpha, beta );
    gap> act := GroupHomomorphismByImages( s3, aut, [(1,2),(2,3)], [alpha,beta] );
    gap> abmod := AbelianModuleObject( k4, act );
    &lt;enumerator&rt;
    gap> Xabmod := XModByAbelianModule( abmod );
    [k4->s3]
    
  ------------------------------------------------------------------
  
  
  8.4 Distinct and Common Representatives
  
  8.4-1 DistinctRepresentatives
  
  > DistinctRepresentatives( list ) _________________________________operation
  > CommonRepresentatives( list ) ___________________________________operation
  > CommonTransversal( grp, subgrp ) ________________________________operation
  > IsCommonTransversal( grp, subgrp, list ) ________________________operation
  
  The  final  set  of  utilities  deal  with lists of subsets of [1 ... n] and
  construct  systems  of  distinct  and  common  representatives using simple,
  non-recursive, combinatorial algorithms.
  
  When  L  is  a  set  of  n  subsets  of  [1 ... n] and the Hall condition is
  satisfied  (the  union  of  any k subsets has at least k elements), a set of
  distinct representatives exists.
  
  When  J,K  are  both  lists  of  n  sets, the function CommonRepresentatives
  returns  two  lists:  the  set  of representatives, and a permutation of the
  subsets  of  the  second  list.  It  may  also  be  used to provide a common
  transversal  for sets of left and right cosets of a subgroup H of a group G,
  although a greedy algorithm is usually quicker.
  
  ---------------------------  Example  ----------------------------
    
    gap> J := [ [1,2,3], [3,4], [3,4], [1,2,4] ];;
    gap> DistinctRepresentatives( J );
    [ 1, 3, 4, 2 ]
    gap> K := [ [3,4], [1,2], [2,3], [2,3,4] ];;
    gap> CommonRepresentatives( J, K );
    [ [ 3, 3, 3, 1 ], [ 1, 3, 4, 2 ] ]
    gap> CommonTransversal( d16, c4 );
    [ (), (12,18)(13,17)(14,16), (11,12,13,14,15,16,17,18),
      (11,12)(13,18)(14,17)(15,16) ]
    gap> IsCommonTransversal( d16, c4, [ (), c, d, c*d ] );
    true
    
  ------------------------------------------------------------------