  
  [1m[4m[31m8. Utility functions[0m
  
  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 [1mGAP[0m library,
  
  --    more suitable for inclusion in the main library than in this package.
  
  
  [1m[4m[31m8.1 Inclusion and Restriction Mappings[0m
  
  [1m[4m[31m8.1-1 InclusionMappingGroups[0m
  
  [1m[34m> InclusionMappingGroups( [0m[22m[34mG, H[0m[1m[34m ) __________________________________[0moperation
  [1m[34m> RestrictionMappingGroups( [0m[22m[34mhom, src, rng[0m[1m[34m ) _______________________[0moperation
  [1m[34m> MappingToOne( [0m[22m[34mG, H[0m[1m[34m ) ____________________________________________[0moperation
  
  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
  [22m[32mincd8[0m is the inclusion of [22m[32md8[0m in [22m[32md16[0m used in Section [1m3.4[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> Print( incd8, "\n" );[0m
    [22m[35m[ (11,13,15,17)(12,14,16,18), (11,18)(12,17)(13,16)(14,15) ] ->[0m
    [22m[35m[ (11,13,15,17)(12,14,16,18), (11,18)(12,17)(13,16)(14,15) ][0m
    [22m[35mgap> imd8 := Image( incd8 );;[0m
    [22m[35mgap> resd8 := RestrictionMappingGroups( incd8, c4, imd8 );;[0m
    [22m[35mgap> Source( res8 );  Range( res8 );[0m
    [22m[35mc4[0m
    [22m[35mGroup([ (11,13,15,17)(12,14,16,18), (11,18)(12,17)(13,16)(14,15) ])[0m
    [22m[35mgap> MappingToOne( c4, imd8 );[0m
    [22m[35m[ (11,13,15,17)(12,14,16,18) ] -> [ () ][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  
  [1m[4m[31m8.2 Endomorphism Classes and Automorphisms[0m
  
  [1m[4m[31m8.2-1 EndomorphismClasses[0m
  
  [1m[34m> EndomorphismClasses( [0m[22m[34mgrp, case[0m[1m[34m ) _________________________________[0mfunction
  [1m[34m> EndoClassNaturalHom( [0m[22m[34mclass[0m[1m[34m ) ____________________________________[0mattribute
  [1m[34m> EndoClassIsomorphism( [0m[22m[34mclass[0m[1m[34m ) ___________________________________[0mattribute
  [1m[34m> EndoClassConjugators( [0m[22m[34mclass[0m[1m[34m ) ___________________________________[0mattribute
  [1m[34m> AutoGroup( [0m[22m[34mclass[0m[1m[34m ) ______________________________________________[0mattribute
  
  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  [22m[32mEndomorphismClasses(  <grp>,  <case> )[0m 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 [22m[32mN[0m intersects [22m[32mH[0m trivially.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> end8 := EndomorphismClasses( d8, 1 );;[0m
    [22m[35mgap> Length( end8 );[0m
    [22m[35m13[0m
    [22m[35mgap> e4 := end8[4];[0m
    [22m[35m<enumerator>[0m
    [22m[35mgap> EndoClassNaturalHom( e4 );[0m
    [22m[35mGroupHomomorphismByImages( d8, Group( [ f1 ] ),[0m
    [22m[35m[ (11,13,15,17)(12,14,16,18), (12,18)(13,17)(14,16) ], [ f1, f1 ] )[0m
    [22m[35mgap> EndoClassIsomorphism( e4 );[0m
    [22m[35mPcgs([ f1 ]) -> [ (11,13)(14,18)(15,17) ][0m
    [22m[35mgap> EndoClassConjugators( e4 );[0m
    [22m[35m[ (), (12,18)(13,17)(14,16) ][0m
    [22m[35mgap> AutoGroup( e4 );[0m
    [22m[35mGroup( [ Pcgs([ f1 ]) -> [ f1 ] ] )[0m
    [22m[35mgap> L := List( end8, e -> Length(EndoClassConjugators(e)) * Size(AutoGroup(e)) );[0m
    [22m[35m[ 8, 1, 2, 2, 1, 2, 2, 1, 2, 2, 6, 6, 1 ][0m
    [22m[35mgap> Sum( L );[0m
    [22m[35m36[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m8.2-2 InnerAutomorphismByNormalSubgroup[0m
  
  [1m[34m> InnerAutomorphismByNormalSubgroup( [0m[22m[34mG, N[0m[1m[34m ) _______________________[0moperation
  [1m[34m> IsGroupOfAutomorphisms( [0m[22m[34mA[0m[1m[34m ) ______________________________________[0mproperty
  
  Inner  automorphisms of a group [22m[32mG[0m by the elements of a normal subgroup [22m[32mN[0m are
  calculated with the first of these functions, usually with [22m[32mG[0m = [22m[32mN[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> autd8 := AutomorphismGroup( d8 );;[0m
    [22m[35mgap> innd8 := InnerAutomorphismsByNormalSubgroup( d8, d8 );;[0m
    [22m[35mgap> GeneratorsOfGroup( innd8 );[0m
    [22m[35m[ InnerAutomorphism( d8, (11,13,15,17)(12,14,16,18) ),[0m
    [22m[35m  InnerAutomorphism( d8, (12,18)(13,17)(14,16) ) ][0m
    [22m[35mgap> IsGroupOfAutomorphisms( innd8 );[0m
    [22m[35mtrue [0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  
  [1m[4m[31m8.3 Abelian Modules[0m
  
  [1m[4m[31m8.3-1 AbelianModuleObject[0m
  
  [1m[34m> AbelianModuleObject( [0m[22m[34mgrp, act[0m[1m[34m ) _________________________________[0moperation
  [1m[34m> IsAbelianModule( [0m[22m[34mobj[0m[1m[34m ) ___________________________________________[0mproperty
  [1m[34m> AbelianModuleGroup( [0m[22m[34mobj[0m[1m[34m ) _______________________________________[0mattribute
  [1m[34m> AbelianModuleAction( [0m[22m[34mobj[0m[1m[34m ) ______________________________________[0mattribute
  
  An  abelian  module  is an abelian group together with a group action. These
  are used by the crossed module constructor [22m[32mXModByAbelianModule[0m.
  
  The    resulting    [22m[32mXabmod[0m    is    isomorphic    to    the    output   from
  [22m[32mXModByAutomorphismGroup( k4 );[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> x := (6,7)(8,9);;  y := (6,8)(7,9);;  z := (6,9)(7,8);;[0m
    [22m[35mgap> k4 := Group( x, y );  SetName( k4, "k4" );[0m
    [22m[35mgap> s3 := Group( (1,2), (2,3) );;  SetName( s3, "s3" );[0m
    [22m[35mgap> alpha := GroupHomomorphismByImages( k4, k4, [x,y], [y,x] );[0m
    [22m[35mgap> beta := GroupHomomorphismByImages( k4, k4, [x,y], [x,z] );[0m
    [22m[35mgap> aut := Group( alpha, beta );[0m
    [22m[35mgap> act := GroupHomomorphismByImages( s3, aut, [(1,2),(2,3)], [alpha,beta] );[0m
    [22m[35mgap> abmod := AbelianModuleObject( k4, act );[0m
    [22m[35m&lt;enumerator&rt;[0m
    [22m[35mgap> Xabmod := XModByAbelianModule( abmod );[0m
    [22m[35m[k4->s3][0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
  
  [1m[4m[31m8.4 Distinct and Common Representatives[0m
  
  [1m[4m[31m8.4-1 DistinctRepresentatives[0m
  
  [1m[34m> DistinctRepresentatives( [0m[22m[34mlist[0m[1m[34m ) _________________________________[0moperation
  [1m[34m> CommonRepresentatives( [0m[22m[34mlist[0m[1m[34m ) ___________________________________[0moperation
  [1m[34m> CommonTransversal( [0m[22m[34mgrp, subgrp[0m[1m[34m ) ________________________________[0moperation
  [1m[34m> IsCommonTransversal( [0m[22m[34mgrp, subgrp, list[0m[1m[34m ) ________________________[0moperation
  
  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 [22m[32mCommonRepresentatives[0m
  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.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35m[0m
    [22m[35mgap> J := [ [1,2,3], [3,4], [3,4], [1,2,4] ];;[0m
    [22m[35mgap> DistinctRepresentatives( J );[0m
    [22m[35m[ 1, 3, 4, 2 ][0m
    [22m[35mgap> K := [ [3,4], [1,2], [2,3], [2,3,4] ];;[0m
    [22m[35mgap> CommonRepresentatives( J, K );[0m
    [22m[35m[ [ 3, 3, 3, 1 ], [ 1, 3, 4, 2 ] ][0m
    [22m[35mgap> CommonTransversal( d16, c4 );[0m
    [22m[35m[ (), (12,18)(13,17)(14,16), (11,12,13,14,15,16,17,18),[0m
    [22m[35m  (11,12)(13,18)(14,17)(15,16) ][0m
    [22m[35mgap> IsCommonTransversal( d16, c4, [ (), c, d, c*d ] );[0m
    [22m[35mtrue[0m
    [22m[35m[0m
  [22m[35m------------------------------------------------------------------[0m
  
