  
  [1X8. Utility functions[0X
  
  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 [5XGAP[0X library,
  
  --    more suitable for inclusion in the main library than in this package.
  
  
  [1X8.1 Inclusion and Restriction Mappings[0X
  
  [1X8.1-1 InclusionMappingGroups[0X
  
  [2X> InclusionMappingGroups( [0X[3XG, H[0X[2X ) __________________________________[0Xoperation
  [2X> RestrictionMappingGroups( [0X[3Xhom, src, rng[0X[2X ) _______________________[0Xoperation
  [2X> MappingToOne( [0X[3XG, H[0X[2X ) ____________________________________________[0Xoperation
  
  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
  [10Xincd8[0X is the inclusion of [10Xd8[0X in [10Xd16[0X used in Section [14X3.4[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> Print( incd8, "\n" );[0X
    [4X[ (11,13,15,17)(12,14,16,18), (11,18)(12,17)(13,16)(14,15) ] ->[0X
    [4X[ (11,13,15,17)(12,14,16,18), (11,18)(12,17)(13,16)(14,15) ][0X
    [4Xgap> imd8 := Image( incd8 );;[0X
    [4Xgap> resd8 := RestrictionMappingGroups( incd8, c4, imd8 );;[0X
    [4Xgap> Source( res8 );  Range( res8 );[0X
    [4Xc4[0X
    [4XGroup([ (11,13,15,17)(12,14,16,18), (11,18)(12,17)(13,16)(14,15) ])[0X
    [4Xgap> MappingToOne( c4, imd8 );[0X
    [4X[ (11,13,15,17)(12,14,16,18) ] -> [ () ][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X8.2 Endomorphism Classes and Automorphisms[0X
  
  [1X8.2-1 EndomorphismClasses[0X
  
  [2X> EndomorphismClasses( [0X[3Xgrp, case[0X[2X ) _________________________________[0Xfunction
  [2X> EndoClassNaturalHom( [0X[3Xclass[0X[2X ) ____________________________________[0Xattribute
  [2X> EndoClassIsomorphism( [0X[3Xclass[0X[2X ) ___________________________________[0Xattribute
  [2X> EndoClassConjugators( [0X[3Xclass[0X[2X ) ___________________________________[0Xattribute
  [2X> AutoGroup( [0X[3Xclass[0X[2X ) ______________________________________________[0Xattribute
  
  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  [10XEndomorphismClasses(  <grp>,  <case> )[0X 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 [10XN[0X intersects [10XH[0X trivially.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> end8 := EndomorphismClasses( d8, 1 );;[0X
    [4Xgap> Length( end8 );[0X
    [4X13[0X
    [4Xgap> e4 := end8[4];[0X
    [4X<enumerator>[0X
    [4Xgap> EndoClassNaturalHom( e4 );[0X
    [4XGroupHomomorphismByImages( d8, Group( [ f1 ] ),[0X
    [4X[ (11,13,15,17)(12,14,16,18), (12,18)(13,17)(14,16) ], [ f1, f1 ] )[0X
    [4Xgap> EndoClassIsomorphism( e4 );[0X
    [4XPcgs([ f1 ]) -> [ (11,13)(14,18)(15,17) ][0X
    [4Xgap> EndoClassConjugators( e4 );[0X
    [4X[ (), (12,18)(13,17)(14,16) ][0X
    [4Xgap> AutoGroup( e4 );[0X
    [4XGroup( [ Pcgs([ f1 ]) -> [ f1 ] ] )[0X
    [4Xgap> L := List( end8, e -> Length(EndoClassConjugators(e)) * Size(AutoGroup(e)) );[0X
    [4X[ 8, 1, 2, 2, 1, 2, 2, 1, 2, 2, 6, 6, 1 ][0X
    [4Xgap> Sum( L );[0X
    [4X36[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  [1X8.2-2 InnerAutomorphismByNormalSubgroup[0X
  
  [2X> InnerAutomorphismByNormalSubgroup( [0X[3XG, N[0X[2X ) _______________________[0Xoperation
  [2X> IsGroupOfAutomorphisms( [0X[3XA[0X[2X ) ______________________________________[0Xproperty
  
  Inner  automorphisms of a group [10XG[0X by the elements of a normal subgroup [10XN[0X are
  calculated with the first of these functions, usually with [10XG[0X = [10XN[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> autd8 := AutomorphismGroup( d8 );;[0X
    [4Xgap> innd8 := InnerAutomorphismsByNormalSubgroup( d8, d8 );;[0X
    [4Xgap> GeneratorsOfGroup( innd8 );[0X
    [4X[ InnerAutomorphism( d8, (11,13,15,17)(12,14,16,18) ),[0X
    [4X  InnerAutomorphism( d8, (12,18)(13,17)(14,16) ) ][0X
    [4Xgap> IsGroupOfAutomorphisms( innd8 );[0X
    [4Xtrue [0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X8.3 Abelian Modules[0X
  
  [1X8.3-1 AbelianModuleObject[0X
  
  [2X> AbelianModuleObject( [0X[3Xgrp, act[0X[2X ) _________________________________[0Xoperation
  [2X> IsAbelianModule( [0X[3Xobj[0X[2X ) ___________________________________________[0Xproperty
  [2X> AbelianModuleGroup( [0X[3Xobj[0X[2X ) _______________________________________[0Xattribute
  [2X> AbelianModuleAction( [0X[3Xobj[0X[2X ) ______________________________________[0Xattribute
  
  An  abelian  module  is an abelian group together with a group action. These
  are used by the crossed module constructor [10XXModByAbelianModule[0X.
  
  The    resulting    [10XXabmod[0X    is    isomorphic    to    the    output   from
  [10XXModByAutomorphismGroup( k4 );[0X.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> x := (6,7)(8,9);;  y := (6,8)(7,9);;  z := (6,9)(7,8);;[0X
    [4Xgap> k4 := Group( x, y );  SetName( k4, "k4" );[0X
    [4Xgap> s3 := Group( (1,2), (2,3) );;  SetName( s3, "s3" );[0X
    [4Xgap> alpha := GroupHomomorphismByImages( k4, k4, [x,y], [y,x] );[0X
    [4Xgap> beta := GroupHomomorphismByImages( k4, k4, [x,y], [x,z] );[0X
    [4Xgap> aut := Group( alpha, beta );[0X
    [4Xgap> act := GroupHomomorphismByImages( s3, aut, [(1,2),(2,3)], [alpha,beta] );[0X
    [4Xgap> abmod := AbelianModuleObject( k4, act );[0X
    [4X&lt;enumerator&rt;[0X
    [4Xgap> Xabmod := XModByAbelianModule( abmod );[0X
    [4X[k4->s3][0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X8.4 Distinct and Common Representatives[0X
  
  [1X8.4-1 DistinctRepresentatives[0X
  
  [2X> DistinctRepresentatives( [0X[3Xlist[0X[2X ) _________________________________[0Xoperation
  [2X> CommonRepresentatives( [0X[3Xlist[0X[2X ) ___________________________________[0Xoperation
  [2X> CommonTransversal( [0X[3Xgrp, subgrp[0X[2X ) ________________________________[0Xoperation
  [2X> IsCommonTransversal( [0X[3Xgrp, subgrp, list[0X[2X ) ________________________[0Xoperation
  
  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 [10XCommonRepresentatives[0X
  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.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> J := [ [1,2,3], [3,4], [3,4], [1,2,4] ];;[0X
    [4Xgap> DistinctRepresentatives( J );[0X
    [4X[ 1, 3, 4, 2 ][0X
    [4Xgap> K := [ [3,4], [1,2], [2,3], [2,3,4] ];;[0X
    [4Xgap> CommonRepresentatives( J, K );[0X
    [4X[ [ 3, 3, 3, 1 ], [ 1, 3, 4, 2 ] ][0X
    [4Xgap> CommonTransversal( d16, c4 );[0X
    [4X[ (), (12,18)(13,17)(14,16), (11,12,13,14,15,16,17,18),[0X
    [4X  (11,12)(13,18)(14,17)(15,16) ][0X
    [4Xgap> IsCommonTransversal( d16, c4, [ (), c, d, c*d ] );[0X
    [4Xtrue[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
