2 Tutorial for the AtlasRep Package
  
  This  chapter  gives  an overview of the basic functionality provided by the
  AtlasRep package. The main concepts and interface functions are presented in
  the first three sections, and Section 2.4 shows a few small examples.
  
  Let us first fix the setup for the examples shown in the package manual.
  
  1   First  of  all,  we  load  the  AtlasRep package. Some of the examples
        require  also  the  GAP  packages  CTblLib and TomLib, so we load also
        these packages.
  
          Example  
          gap> LoadPackage( "AtlasRep", false );
          true
          gap> LoadPackage( "CTblLib", false );
          true
          gap> LoadPackage( "TomLib", false );
          true
        
  
  2   Depending on the terminal capabilities, the output of DisplayAtlasInfo
        (3.5-1)  may  contain non-ASCII characters, which are not supported by
        the  LaTeX and HTML versions of GAPDoc documents. The examples in this
        manual  are used for tests of the package's functionality, thus we set
        the  user preference DisplayFunction (see Section 4.2-11) to the value
        "Print"   in   order  to  produce  output  consisting  only  of  ASCII
        characters, which is assumed to work in any terminal.
  
          Example  
          gap> origpref:= UserPreference( "AtlasRep", "DisplayFunction" );;
          gap> SetUserPreference( "AtlasRep", "DisplayFunction", "Print" );
        
  
  3   The  GAP  output  for  the  examples  may  look  differently  if  data
        extensions  have  been  loaded. In order to ignore these extensions in
        the examples, we unload them.
  
          Example  
          gap> priv:= Difference(
          >     List( AtlasOfGroupRepresentationsInfo.notified, x -> x.ID ),
          >     [ "core", "internal" ] );;
          gap> Perform( priv, AtlasOfGroupRepresentationsForgetData );
        
  
  4   If  the  info  level  of InfoAtlasRep (7.1-1) is larger than zero then
        additional  output  appears  on  the  screen.  In  order to avoid this
        output, we set the level to zero.
  
          Example  
          gap> globallevel:= InfoLevel( InfoAtlasRep );;
          gap> SetInfoLevel( InfoAtlasRep, 0 );
        
  
  
  2.1 Accessing a Specific Group in AtlasRep
  
  An  important  database  to  which  the AtlasRep package gives access is the
  ATLAS  of  Group  Representations [WWT+]. It contains generators and related
  data  for  several  groups,  mainly  for  extensions  of  simple groups (see
  Section 2.1-1) and for their maximal subgroups (see Section 2.1-2).
  
  In  general,  these data are not part of the package. They are downloaded as
  soon as they are needed for the first time, see Section 4.2-1.
  
  
  2.1-1 Accessing a Group in AtlasRep via its Name
  
  Each  group  that occurs in this database is specified by a name, which is a
  string  similar to the name used in the ATLAS of Finite Groups [CCN+85]. For
  those groups whose character tables are contained in the GAP Character Table
  Library [Bre22],   the   names  are  equal  to  the  Identifier  (Reference:
  Identifier  for character tables) values of these character tables. Examples
  of  such  names  are "M24" for the Mathieu group M_24, "2.A6" for the double
  cover  of  the alternating group A_6, and "2.A6.2_1" for the double cover of
  the  symmetric  group  S_6.  The names that actually occur are listed in the
  first  column  of  the  overview  table  that  is  printed  by  the function
  DisplayAtlasInfo  (3.5-1),  called  without  arguments, see below. The other
  columns of the table describe the data that are available in the database.
  
  For  example,  DisplayAtlasInfo  (3.5-1)  may  print  the  following  lines.
  Omissions are indicated with ....
  
    Example  
    gap> DisplayAtlasInfo();
    group                    |  # | maxes | cl | cyc | out | fnd | chk | prs
    -------------------------+----+-------+----+-----+-----+-----+-----+----
    ...
    2.A5                     | 26 |     3 |    |     |     |     |  +  |  + 
    2.A5.2                   | 11 |     4 |    |     |     |     |  +  |  + 
    2.A6                     | 18 |     5 |    |     |     |     |     |    
    2.A6.2_1                 |  3 |     6 |    |     |     |     |     |    
    2.A7                     | 24 |     2 |    |     |     |     |     |    
    2.A7.2                   |  7 |       |    |     |     |     |     |    
    ...
    M22                      | 58 |     8 |  + |  +  |     |  +  |  +  |  + 
    M22.2                    | 46 |     7 |  + |  +  |     |  +  |  +  |  + 
    M23                      | 66 |     7 |  + |  +  |     |  +  |  +  |  + 
    M24                      | 62 |     9 |  + |  +  |     |  +  |  +  |  + 
    McL                      | 46 |    12 |  + |  +  |     |  +  |  +  |  + 
    McL.2                    | 27 |    10 |    |  +  |     |  +  |  +  |  + 
    O7(3)                    | 28 |       |    |     |     |     |     |    
    O7(3).2                  |  3 |       |    |     |     |     |     |    
    ...
    Suz                      | 30 |    17 |    |  +  |   2 |  +  |  +  |    
    ...
  
  
  Called  with  a  group  name  as  the only argument, the function AtlasGroup
  (3.5-8)  returns  a  group  isomorphic  to the group with the given name, or
  fail.  If  permutation  generators  are  available  in  the  database then a
  permutation  group  (of  smallest available degree) is returned, otherwise a
  matrix group.
  
    Example  
    gap> g:= AtlasGroup( "M24" );
    Group([ (1,4)(2,7)(3,17)(5,13)(6,9)(8,15)(10,19)(11,18)(12,21)(14,16)
      (20,24)(22,23), (1,4,6)(2,21,14)(3,9,15)(5,18,10)(13,17,16)
      (19,24,23) ])
    gap> IsPermGroup( g );  NrMovedPoints( g );  Size( g );
    true
    24
    244823040
    gap> AtlasGroup( "J5" );
    fail
  
  
  
  2.1-2 Accessing a Maximal Subgroup of a Group in AtlasRep
  
  Many  maximal  subgroups  of  extensions of simple groups can be constructed
  using the function AtlasSubgroup (3.5-9). Given the name of the extension of
  the simple group and the number of the conjugacy class of maximal subgroups,
  this function returns a representative from this class.
  
    Example  
    gap> g:= AtlasSubgroup( "M24", 1 );
    Group([ (2,10)(3,12)(4,14)(6,9)(8,16)(15,18)(20,22)(21,24), (1,7,2,9)
      (3,22,10,23)(4,19,8,12)(5,14)(6,18)(13,16,17,24) ])
    gap> IsPermGroup( g );  NrMovedPoints( g );  Size( g );
    true
    23
    10200960
    gap> AtlasSubgroup( "M24", 100 );
    fail
  
  
  The  classes  of  maximal subgroups are ordered w. r. t. decreasing subgroup
  order. So the first class contains maximal subgroups of smallest index.
  
  Note  that groups obtained by AtlasSubgroup (3.5-9) may be not very suitable
  for  computations  in  the  sense that much nicer representations exist. For
  example,  the  sporadic simple O'Nan group O'N contains a maximal subgroup S
  isomorphic with the Janko group J_1; the smallest permutation representation
  of  O'N has degree 122760, and restricting this representation to S yields a
  representation   of  J_1  of  that  degree.  However,  J_1  has  a  faithful
  permutation  representation  of degree 266, which admits much more efficient
  computations.  If  you  are  just interested in J_1 and not in its embedding
  into  O'N  then one possibility to get a nicer faithful representation is to
  call            SmallerDegreePermutationRepresentation           (Reference:
  SmallerDegreePermutationRepresentation). In the abovementioned example, this
  works  quite  well;  note  that  in  general, we cannot expect that we get a
  representation of smallest degree in this way.
  
    Example  
    gap> s:= AtlasSubgroup( "ON", 3 );
    <permutation group of size 175560 with 2 generators>
    gap> NrMovedPoints( s );  Size( s );
    122760
    175560
    gap> hom:= SmallerDegreePermutationRepresentation( s );;
    gap> NrMovedPoints( Image( hom ) );
    1540
  
  
  In this particular case, one could of course also ask directly for the group
  J_1.
  
    Example  
    gap> j1:= AtlasGroup( "J1" );
    <permutation group of size 175560 with 2 generators>
    gap> NrMovedPoints( j1 );
    266
  
  
  If  you  have a group G, say, and you are really interested in the embedding
  of  a  maximal  subgroup  of  G  into  G  then an easy way to get compatible
  generators  is  to  create  G  with  AtlasGroup  (3.5-8)  and  then  to call
  AtlasSubgroup (3.5-9) with first argument the group G.
  
    Example  
    gap> g:= AtlasGroup( "ON" );
    <permutation group of size 460815505920 with 2 generators>
    gap> s:= AtlasSubgroup( g, 3 );
    <permutation group of size 175560 with 2 generators>
    gap> IsSubset( g, s );
    true
    gap> IsSubset( g, j1 );
    false
  
  
  
  2.2 Accessing Specific Generators in AtlasRep
  
  The  function  DisplayAtlasInfo (3.5-1), called with an admissible name of a
  group as the only argument, lists the ATLAS data available for this group.
  
    Example  
    gap> DisplayAtlasInfo( "A5" );
    Representations for G = A5:    (all refer to std. generators 1)
    ---------------------------
     1: G <= Sym(5)                  3-trans., on cosets of A4 (1st max.)
     2: G <= Sym(6)                  2-trans., on cosets of D10 (2nd max.)
     3: G <= Sym(10)                 rank 3, on cosets of S3 (3rd max.)
     4: G <= GL(4a,2)                character 4a
     5: G <= GL(4b,2)                character 2ab
     6: G <= GL(4,3)                 character 4a
     7: G <= GL(6,3)                 character 3ab
     8: G <= GL(2a,4)                character 2a
     9: G <= GL(2b,4)                character 2b
    10: G <= GL(3,5)                 character 3a
    11: G <= GL(5,5)                 character 5a
    12: G <= GL(3a,9)                character 3a
    13: G <= GL(3b,9)                character 3b
    14: G <= GL(4,Z)                 character 4a
    15: G <= GL(5,Z)                 character 5a
    16: G <= GL(6,Z)                 character 3ab
    17: G <= GL(3a,Field([Sqrt(5)])) character 3a
    18: G <= GL(3b,Field([Sqrt(5)])) character 3b
    
    Programs for G = A5:    (all refer to std. generators 1)
    --------------------
    - class repres.*      
    - presentation        
    - maxes (all 3):
      1:  A4              
      2:  D10             
      3:  S3              
    - std. gen. checker:
      (check)             
      (pres)              
  
  
  In order to fetch one of the listed permutation groups or matrix groups, you
  can  call  AtlasGroup  (3.5-8)  with  second  argument the function Position
  (Reference: Position) and third argument the position in the list.
  
    Example  
    gap> AtlasGroup( "A5", Position, 1 );
    Group([ (1,2)(3,4), (1,3,5) ])
  
  
  Note  that  this approach may yield a different group after a data extension
  has been loaded.
  
  Alternatively, you can describe the desired group by conditions, such as the
  degree  in  the  case of a permutation group, and the dimension and the base
  ring in the case of a matrix group.
  
    Example  
    gap> AtlasGroup( "A5", NrMovedPoints, 10 );
    Group([ (2,4)(3,5)(6,8)(7,10), (1,2,3)(4,6,7)(5,8,9) ])
    gap> AtlasGroup( "A5", Dimension, 4, Ring, GF(2) );
    <matrix group of size 60 with 2 generators>
  
  
  The  same  holds for the restriction to maximal subgroups: Use AtlasSubgroup
  (3.5-9)   with  the  same  arguments  as  AtlasGroup  (3.5-8),  except  that
  additionally  the number of the class of maximal subgroups is entered as the
  last  argument.  Note  that  the  conditions  refer to the group, not to the
  subgroup;  it  may  happen that the subgroup moves fewer points than the big
  group.
  
    Example  
    gap> AtlasSubgroup( "A5", Dimension, 4, Ring, GF(2), 1 );
    <matrix group of size 12 with 2 generators>
    gap> g:= AtlasSubgroup( "A5", NrMovedPoints, 10, 3 );
    Group([ (2,4)(3,5)(6,8)(7,10), (1,4)(3,8)(5,7)(6,10) ])
    gap> Size( g );  NrMovedPoints( g );
    6
    9
  
  
  
  2.3 Basic Concepts used in AtlasRep
  
  
  2.3-1 Groups, Generators, and Representations
  
  Up  to  now,  we  have  talked only about groups and subgroups. The AtlasRep
  package  provides  access  to group generators, and in fact these generators
  have  the  property  that  mapping  one  set of generators to another set of
  generators  for  the same group defines an isomorphism. These generators are
  called standard generators, see Section 3.3.
  
  So  instead  of thinking about several generating sets of a group G, say, we
  can  think about one abstract group G, with one fixed set of generators, and
  mapping  these  generators  to  any  set  of generators provided by AtlasRep
  defines  a  representation of G. This viewpoint had motivated the name ATLAS
  of Group Representations for the core part of the database.
  
  If you are interested in the generators provided by the database rather than
  in    the    groups    they    generate,    you   can   use   the   function
  OneAtlasGeneratingSetInfo  (3.5-6)  instead  of AtlasGroup (3.5-8), with the
  same  arguments.  This will yield a record that describes the representation
  in  question.  Calling the function AtlasGenerators (3.5-3) with this record
  will  then  yield  a  record with the additional component generators, which
  holds the list of generators.
  
    Example  
    gap> info:= OneAtlasGeneratingSetInfo( "A5", NrMovedPoints, 10 );
    rec( charactername := "1a+4a+5a", constituents := [ 1, 4, 5 ], 
      contents := "core", groupname := "A5", id := "", 
      identifier := [ "A5", [ "A5G1-p10B0.m1", "A5G1-p10B0.m2" ], 1, 10 ],
      isPrimitive := true, maxnr := 3, p := 10, rankAction := 3, 
      repname := "A5G1-p10B0", repnr := 3, size := 60, stabilizer := "S3",
      standardization := 1, transitivity := 1, type := "perm" )
    gap> info2:= AtlasGenerators( info );
    rec( charactername := "1a+4a+5a", constituents := [ 1, 4, 5 ], 
      contents := "core", 
      generators := [ (2,4)(3,5)(6,8)(7,10), (1,2,3)(4,6,7)(5,8,9) ], 
      groupname := "A5", id := "", 
      identifier := [ "A5", [ "A5G1-p10B0.m1", "A5G1-p10B0.m2" ], 1, 10 ],
      isPrimitive := true, maxnr := 3, p := 10, rankAction := 3, 
      repname := "A5G1-p10B0", repnr := 3, size := 60, stabilizer := "S3",
      standardization := 1, transitivity := 1, type := "perm" )
    gap> info2.generators;
    [ (2,4)(3,5)(6,8)(7,10), (1,2,3)(4,6,7)(5,8,9) ]
  
  
  The  record  info  appears  as the value of the attribute AtlasRepInfoRecord
  (3.5-10) in groups that are returned by AtlasGroup (3.5-8).
  
    Example  
    gap> g:= AtlasGroup( "A5", NrMovedPoints, 10 );;
    gap> AtlasRepInfoRecord( g );
    rec( charactername := "1a+4a+5a", constituents := [ 1, 4, 5 ], 
      contents := "core", groupname := "A5", id := "", 
      identifier := [ "A5", [ "A5G1-p10B0.m1", "A5G1-p10B0.m2" ], 1, 10 ],
      isPrimitive := true, maxnr := 3, p := 10, rankAction := 3, 
      repname := "A5G1-p10B0", repnr := 3, size := 60, stabilizer := "S3",
      standardization := 1, transitivity := 1, type := "perm" )
  
  
  
  2.3-2 Straight Line Programs
  
  For  computing  certain  group  elements  from  standard generators, such as
  generators  of  a  subgroup or class representatives, AtlasRep uses straight
  line  programs,  see  'Reference:  Straight Line Programs'. Essentially this
  means  to  evaluate  words in the generators, which is similar to MappedWord
  (Reference: MappedWord) but can be more efficient.
  
  It can be useful to deal with these straight line programs, see AtlasProgram
  (3.5-4).  For  example, an automorphism α, say, of the group G, if available
  in  AtlasRep, is given by a straight line program that defines the images of
  standard generators of G. This way, one can for example compute the image of
  a  subgroup U of G under α by first applying the straight line program for α
  to standard generators of G, and then applying the straight line program for
  the restriction from G to U.
  
    Example  
    gap> prginfo:= AtlasProgramInfo( "A5", "maxes", 1 );
    rec( groupname := "A5", identifier := [ "A5", "A5G1-max1W1", 1 ], 
      size := 12, standardization := 1, subgroupname := "A4", 
      version := "1" )
    gap> prg:= AtlasProgram( prginfo.identifier );
    rec( groupname := "A5", identifier := [ "A5", "A5G1-max1W1", 1 ], 
      program := <straight line program>, size := 12, 
      standardization := 1, subgroupname := "A4", version := "1" )
    gap> Display( prg.program );
    # input:
    r:= [ g1, g2 ];
    # program:
    r[3]:= r[1]*r[2];
    r[4]:= r[2]*r[1];
    r[5]:= r[3]*r[3];
    r[1]:= r[5]*r[4];
    # return values:
    [ r[1], r[2] ]
    gap> ResultOfStraightLineProgram( prg.program, info2.generators );
    [ (1,10)(2,3)(4,9)(7,8), (1,2,3)(4,6,7)(5,8,9) ]
  
  
  
  2.4 Examples of Using the AtlasRep Package
  
  
  2.4-1 Example: Class Representatives
  
  First  we show the computation of class representatives of the Mathieu group
  M_11,  in  a 2-modular matrix representation. We start with the ordinary and
  Brauer character tables of this group.
  
    Example  
    gap> tbl:= CharacterTable( "M11" );;
    gap> modtbl:= tbl mod 2;;
    gap> CharacterDegrees( modtbl );
    [ [ 1, 1 ], [ 10, 1 ], [ 16, 2 ], [ 44, 1 ] ]
  
  
  The  output of CharacterDegrees (Reference: CharacterDegrees) means that the
  2-modular irreducibles of M_11 have degrees 1, 10, 16, 16, and 44.
  
  Using  DisplayAtlasInfo  (3.5-1), we find out that matrix generators for the
  irreducible 10-dimensional representation are available in the database.
  
    Example  
    gap> DisplayAtlasInfo( "M11", Characteristic, 2 );
    Representations for G = M11:    (all refer to std. generators 1)
    ----------------------------
     6: G <= GL(10,2)  character 10a
     7: G <= GL(32,2)  character 16ab
     8: G <= GL(44,2)  character 44a
    16: G <= GL(16a,4) character 16a
    17: G <= GL(16b,4) character 16b
  
  
  So  we  decide to work with this representation. We fetch the generators and
  compute the list of class representatives of M_11 in the representation. The
  ordering of class representatives is the same as that in the character table
  of  the ATLAS of Finite Groups ([CCN+85]), which coincides with the ordering
  of columns in the GAP table we have fetched above.
  
    Example  
    gap> info:= OneAtlasGeneratingSetInfo( "M11", Characteristic, 2,
    >                                             Dimension, 10 );;
    gap> gens:= AtlasGenerators( info.identifier );;
    gap> ccls:= AtlasProgram( "M11", gens.standardization, "classes" );
    rec( groupname := "M11", identifier := [ "M11", "M11G1-cclsW1", 1 ], 
      outputs := [ "1A", "2A", "3A", "4A", "5A", "6A", "8A", "8B", "11A", 
          "11B" ], program := <straight line program>, 
      standardization := 1, version := "1" )
    gap> reps:= ResultOfStraightLineProgram( ccls.program, gens.generators );;
  
  
  If  we  would  need  only  a few class representatives, we could use the GAP
  library  function  RestrictOutputsOfSLP (Reference: RestrictOutputsOfSLP) to
  create a straight line program that computes only specified outputs. Here is
  an example where only the class representatives of order eight are computed.
  
    Example  
    gap> ord8prg:= RestrictOutputsOfSLP( ccls.program,
    >                   Filtered( [ 1 .. 10 ], i -> ccls.outputs[i][1] = '8' ) );
    <straight line program>
    gap> ord8reps:= ResultOfStraightLineProgram( ord8prg, gens.generators );;
    gap> List( ord8reps, m -> Position( reps, m ) );
    [ 7, 8 ]
  
  
  Let us check that the class representatives have the right orders.
  
    Example  
    gap> List( reps, Order ) = OrdersClassRepresentatives( tbl );
    true
  
  
  From  the  class representatives, we can compute the Brauer character we had
  started  with.  This  Brauer  character  is  defined  on  all classes of the
  2-modular  table. So we first pick only those representatives, using the GAP
  function  GetFusionMap  (Reference:  GetFusionMap);  in  this  situation, it
  returns the class fusion from the Brauer table into the ordinary table.
  
    Example  
    gap> fus:= GetFusionMap( modtbl, tbl );
    [ 1, 3, 5, 9, 10 ]
    gap> modreps:= reps{ fus };;
  
  
  Then   we   call   the   GAP   function   BrauerCharacterValue   (Reference:
  BrauerCharacterValue),  which  computes  the Brauer character value from the
  matrix given.
  
    Example  
    gap> char:= List( modreps, BrauerCharacterValue );
    [ 10, 1, 0, -1, -1 ]
    gap> Position( Irr( modtbl ), char );
    2
  
  
  
  2.4-2 Example: Permutation and Matrix Representations
  
  The  second  example  shows  the computation of a permutation representation
  from a matrix representation. We work with the 10-dimensional representation
  used  above,  and  consider the action on the 2^10 vectors of the underlying
  row space.
  
    Example  
    gap> grp:= Group( gens.generators );;
    gap> v:= GF(2)^10;;
    gap> orbs:= Orbits( grp, AsList( v ) );;
    gap> List( orbs, Length );
    [ 1, 396, 55, 330, 66, 165, 11 ]
  
  
  We  see  that  there  are  six  nontrivial  orbits,  and  we can compute the
  permutation actions on these orbits directly using Action (Reference: Action
  homomorphisms).  However,  for  larger  examples,  one cannot write down all
  orbits  on  the  row  space,  so  one  has to use another strategy if one is
  interested in a particular orbit.
  
  Let  us  assume  that we are interested in the orbit of length 11. The point
  stabilizer  is  the  first maximal subgroup of M_11, thus the restriction of
  the representation to this subgroup has a nontrivial fixed point space. This
  restriction can be computed using the AtlasRep package.
  
    Example  
    gap> gens:= AtlasGenerators( "M11", 6, 1 );;
  
  
  Now computing the fixed point space is standard linear algebra.
  
    Example  
    gap> id:= IdentityMat( 10, GF(2) );;
    gap> sub1:= Subspace( v, NullspaceMat( gens.generators[1] - id ) );;
    gap> sub2:= Subspace( v, NullspaceMat( gens.generators[2] - id ) );;
    gap> fix:= Intersection( sub1, sub2 );
    <vector space of dimension 1 over GF(2)>
  
  
  The final step is of course the computation of the permutation action on the
  orbit.
  
    Example  
    gap> orb:= Orbit( grp, Basis( fix )[1] );;
    gap> act:= Action( grp, orb );;  Print( act, "\n" );
    Group( [ ( 1, 2)( 4, 6)( 5, 8)( 7,10), ( 1, 3, 5, 9)( 2, 4, 7,11) ] )
  
  
  Note  that  this  group  is  not equal to the group obtained by fetching the
  permutation  representation  from  the  database. This is due to a different
  numbering  of  the  points, thus the groups are permutation isomorphic, that
  is, they are conjugate in the symmetric group on eleven points.
  
    Example  
    gap> permgrp:= Group( AtlasGenerators( "M11", 1 ).generators );;
    gap> Print( permgrp, "\n" );
    Group( [ ( 2,10)( 4,11)( 5, 7)( 8, 9), (1,4,3,8)(2,5,6,9) ] )
    gap> permgrp = act;
    false
    gap> IsConjugate( SymmetricGroup(11), permgrp, act );
    true
  
  
  
  2.4-3 Example: Outer Automorphisms
  
  The  straight  line  programs  for  applying outer automorphisms to standard
  generators  can  of course be used to define the automorphisms themselves as
  GAP mappings.
  
    Example  
    gap> DisplayAtlasInfo( "G2(3)", IsStraightLineProgram );
    Programs for G = G2(3):    (all refer to std. generators 1)
    -----------------------
    - class repres.            
    - presentation             
    - repr. cyc. subg.         
    - std. gen. checker        
    - automorphisms:
      2                        
    - maxes (all 10):
       1:  U3(3).2             
       2:  U3(3).2             
       3:  (3^(1+2)+x3^2):2S4  
       4:  (3^(1+2)+x3^2):2S4  
       5:  L3(3).2             
       6:  L3(3).2             
       7:  L2(8).3             
       8:  2^3.L3(2)           
       9:  L2(13)              
      10:  2^(1+4)+:3^2.2      
    gap> prog:= AtlasProgram( "G2(3)", "automorphism", "2" ).program;;
    gap> info:= OneAtlasGeneratingSetInfo( "G2(3)", Dimension, 7 );;
    gap> gens:= AtlasGenerators( info ).generators;;
    gap> imgs:= ResultOfStraightLineProgram( prog, gens );;
  
  
  If we are not suspicious whether the script really describes an automorphism
  then  we  should tell this to GAP, in order to avoid the expensive checks of
  the    properties    of    being   a   homomorphism   and   bijective   (see
  Section 'Reference: Creating Group Homomorphisms'). This looks as follows.
  
    Example  
    gap> g:= Group( gens );;
    gap> aut:= GroupHomomorphismByImagesNC( g, g, gens, imgs );;
    gap> SetIsBijective( aut, true );
  
  
  If  we  are  suspicious whether the script describes an automorphism then we
  might have the idea to check it with GAP, as follows.
  
    Example  
    gap> aut:= GroupHomomorphismByImages( g, g, gens, imgs );;
    gap> IsBijective( aut );
    true
  
  
  (Note  that  even for a comparatively small group such as G_2(3), this was a
  difficult task for GAP before version 4.3.)
  
  Often one can form images under an automorphism α, say, without creating the
  homomorphism  object.  This  is  obvious  for the standard generators of the
  group G themselves, but also for generators of a maximal subgroup M computed
  from  standard  generators of G, provided that the straight line programs in
  question  refer to the same standard generators. Note that the generators of
  M  are  given  by evaluating words in terms of standard generators of G, and
  their  images  under  α  can be obtained by evaluating the same words at the
  images under α of the standard generators of G.
  
    Example  
    gap> max1:= AtlasProgram( "G2(3)", 1 ).program;;
    gap> mgens:= ResultOfStraightLineProgram( max1, gens );;
    gap> comp:= CompositionOfStraightLinePrograms( max1, prog );;
    gap> mimgs:= ResultOfStraightLineProgram( comp, gens );;
  
  
  The  list  mgens  is the list of generators of the first maximal subgroup of
  G_2(3),  mimgs  is  the  list  of images under the automorphism given by the
  straight  line  program  prog.  Note  that  applying the program returned by
  CompositionOfStraightLinePrograms                                (Reference:
  CompositionOfStraightLinePrograms)  means to apply first prog and then max1.
  Since   we   have  already  constructed  the  GAP  object  representing  the
  automorphism, we can check whether the results are equal.
  
    Example  
    gap> mimgs = List( mgens, x -> x^aut );
    true
  
  
  However, it should be emphasized that using aut requires a huge machinery of
  computations  behind the scenes, whereas applying the straight line programs
  prog  and  max1 involves only elementary operations with the generators. The
  latter  is  feasible  also for larger groups, for which constructing the GAP
  automorphism might be too hard.
  
  
  2.4-4 Example: Using Semi-presentations and Black Box Programs
  
  Let  us  suppose  that  we  want to restrict a representation of the Mathieu
  group  M_12  to a non-maximal subgroup of the type L_2(11). The idea is that
  this  subgroup  can  be found as a maximal subgroup of a maximal subgroup of
  the  type  M_11,  which  is  itself  maximal  in  M_12. For that, we fetch a
  representation of M_12 and use a straight line program for restricting it to
  the first maximal subgroup, which has the type M_11.
  
    Example  
    gap> info:= OneAtlasGeneratingSetInfo( "M12", NrMovedPoints, 12 );
    rec( charactername := "1a+11a", constituents := [ 1, 2 ], 
      contents := "core", groupname := "M12", id := "a", 
      identifier := [ "M12", [ "M12G1-p12aB0.m1", "M12G1-p12aB0.m2" ], 1, 
          12 ], isPrimitive := true, maxnr := 1, p := 12, rankAction := 2,
      repname := "M12G1-p12aB0", repnr := 1, size := 95040, 
      stabilizer := "M11", standardization := 1, transitivity := 5, 
      type := "perm" )
    gap> gensM12:= AtlasGenerators( info.identifier );;
    gap> restM11:= AtlasProgram( "M12", "maxes", 1 );;
    gap> gensM11:= ResultOfStraightLineProgram( restM11.program,
    >                                           gensM12.generators );
    [ (3,9)(4,12)(5,10)(6,8), (1,4,11,5)(2,10,8,3) ]
  
  
  Now  we  cannot  simply  apply  a  straight line program for a group to some
  generators, since they are not necessarily standard generators of the group.
  We check this property using a semi-presentation for M_11, see 6.1-7.
  
    Example  
    gap> checkM11:= AtlasProgram( "M11", "check" );
    rec( groupname := "M11", identifier := [ "M11", "M11G1-check1", 1, 1 ]
        , program := <straight line decision>, standardization := 1, 
      version := "1" )
    gap> ResultOfStraightLineDecision( checkM11.program, gensM11 );
    true
  
  
  So  we are lucky that applying the appropriate program for M_11 will give us
  the required generators for L_2(11).
  
    Example  
    gap> restL211:= AtlasProgram( "M11", "maxes", 2 );;
    gap> gensL211:= ResultOfStraightLineProgram( restL211.program, gensM11 );
    [ (3,9)(4,12)(5,10)(6,8), (1,11,9)(2,12,8)(3,6,10) ]
    gap> G:= Group( gensL211 );;  Size( G );  IsSimple( G );
    660
    true
  
  
  In  this  case, we could also use the information that is stored about M_11,
  as follows.
  
    Example  
    gap> DisplayAtlasInfo( "M11", IsStraightLineProgram );
    Programs for G = M11:    (all refer to std. generators 1)
    ---------------------
    - presentation                                        
    - repr. cyc. subg.                                    
    - std. gen. finder                                    
    - class repres.:
      (direct)                                            
      (composed)                                          
    - maxes (all 5):
      1:  A6.2_3                                          
      1:  A6.2_3                                  (std. 1)
      2:  L2(11)                                          
      2:  L2(11)                                  (std. 1)
      3:  3^2:Q8.2                                        
      4:  S5                                              
      4:  S5                                      (std. 1)
      5:  2.S4                                            
    - standardizations of maxes:
      from 1st max., version 1 to A6.2_3, std. 1          
      from 2nd max., version 1 to L2(11), std. 1          
      from 4th max., version 1 to A5.2, std. 1            
    - std. gen. checker:
      (check)                                             
      (pres)                                              
  
  
  The entry std.1 in the line about the maximal subgroup of type L_2(11) means
  that   a  straight  line  program  for  computing  standard  generators  (in
  standardization 1) of the subgroup. This program can be fetched as follows.
  
    Example  
    gap> restL211std:= AtlasProgram( "M11", "maxes", 2, 1 );;
    gap> ResultOfStraightLineProgram( restL211std.program, gensM11 );
    [ (3,9)(4,12)(5,10)(6,8), (1,11,9)(2,12,8)(3,6,10) ]
  
  
  We  see  that we get the same generators for the subgroup as above. (In fact
  the  second  approach  first  applies  the  same  program  as  is  given  by
  restL211.program,  and  then  applies  a  program  to  the results that does
  nothing.)
  
  Usually  representations  are not given in terms of standard generators. For
  example,  let  us  take  the  M_11  type  group returned by the GAP function
  MathieuGroup (Reference: MathieuGroup).
  
    Example  
    gap> G:= MathieuGroup( 11 );;
    gap> gens:= GeneratorsOfGroup( G );
    [ (1,2,3,4,5,6,7,8,9,10,11), (3,7,11,8)(4,10,5,6) ]
    gap> ResultOfStraightLineDecision( checkM11.program, gens );
    false
  
  
  If  we  want to compute an L_2(11) type subgroup of this group, we can use a
  black  box  program  for  computing  standard generators, and then apply the
  straight line program for computing the restriction.
  
    Example  
    gap> find:= AtlasProgram( "M11", "find" );
    rec( groupname := "M11", identifier := [ "M11", "M11G1-find1", 1, 1 ],
      program := <black box program>, standardization := 1, 
      version := "1" )
    gap> stdgens:= ResultOfBBoxProgram( find.program, Group( gens ) );;
    gap> List( stdgens, Order );
    [ 2, 4 ]
    gap> ResultOfStraightLineDecision( checkM11.program, stdgens );
    true
    gap> gensL211:= ResultOfStraightLineProgram( restL211.program, stdgens );;
    gap> List( gensL211, Order );
    [ 2, 3 ]
    gap> G:= Group( gensL211 );;  Size( G );  IsSimple( G );
    660
    true
  
  
  Note  that  applying the black box program several times may yield different
  group  elements,  because  computations of random elements are involved, see
  ResultOfBBoxProgram  (6.2-4).  All what the black box program promises is to
  construct standard generators, and these are defined only up to conjugacy in
  the automorphism group of the group in question.
  
  
  2.4-5 Example: Using the GAP Library of Tables of Marks
  
  The  GAP  Library  of  Tables  of  Marks  (the  GAP package TomLib, [NMP18])
  provides,  for  many  almost  simple  groups,  information  for constructing
  representatives  of  all conjugacy classes of subgroups. If this information
  is   compatible   with  the  standard  generators  of  the  ATLAS  of  Group
  Representations  then  we can use it to restrict any representation from the
  ATLAS  to  prescribed  subgroups.  This  is  useful  in particular for those
  subgroups  for  which  the  ATLAS  of  Group Representations itself does not
  contain a straight line program.
  
    Example  
    gap> tom:= TableOfMarks( "A5" );
    TableOfMarks( "A5" )
    gap> info:= StandardGeneratorsInfo( tom );
    [ rec( ATLAS := true, description := "|a|=2, |b|=3, |ab|=5", 
          generators := "a, b", 
          script := [ [ 1, 2 ], [ 2, 3 ], [ 1, 1, 2, 1, 5 ] ], 
          standardization := 1 ) ]
  
  
  The  true value of the component ATLAS indicates that the information stored
  on  tom  refers  to  the standard generators of type 1 in the ATLAS of Group
  Representations.
  
  We  want  to  restrict  a  4-dimensional integral representation of A_5 to a
  Sylow 2 subgroup of A_5, and use RepresentativeTomByGeneratorsNC (Reference:
  RepresentativeTomByGeneratorsNC) for that.
  
    Example  
    gap> info:= OneAtlasGeneratingSetInfo( "A5", Ring, Integers, Dimension, 4 );;
    gap> stdgens:= AtlasGenerators( info.identifier );
    rec( charactername := "4a", constituents := [ 4 ], contents := "core",
      dim := 4, 
      generators := 
        [ 
          [ [ 1, 0, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 1, 0, 0 ], 
              [ -1, -1, -1, -1 ] ], 
          [ [ 0, 1, 0, 0 ], [ 0, 0, 0, 1 ], [ 0, 0, 1, 0 ], 
              [ 1, 0, 0, 0 ] ] ], groupname := "A5", id := "", 
      identifier := [ "A5", "A5G1-Zr4B0.g", 1, 4 ], 
      repname := "A5G1-Zr4B0", repnr := 14, ring := Integers, size := 60, 
      standardization := 1, type := "matint" )
    gap> orders:= OrdersTom( tom );
    [ 1, 2, 3, 4, 5, 6, 10, 12, 60 ]
    gap> pos:= Position( orders, 4 );
    4
    gap> sub:= RepresentativeTomByGeneratorsNC( tom, pos, stdgens.generators );
    <matrix group of size 4 with 2 generators>
    gap> GeneratorsOfGroup( sub );
    [ [ [ 1, 0, 0, 0 ], [ -1, -1, -1, -1 ], [ 0, 0, 0, 1 ], 
          [ 0, 0, 1, 0 ] ], 
      [ [ 1, 0, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 1, 0, 0 ], 
          [ -1, -1, -1, -1 ] ] ]
  
  
  
  2.4-6 Example: Index 770 Subgroups in M_22
  
  The  sporadic simple Mathieu group M_22 contains a unique class of subgroups
  of  index  770  (and  order  576).  This can be seen for example using GAP's
  Library of Tables of Marks.
  
    Example  
    gap> tom:= TableOfMarks( "M22" );
    TableOfMarks( "M22" )
    gap> subord:= Size( UnderlyingGroup( tom ) ) / 770;
    576
    gap> ord:= OrdersTom( tom );;
    gap> tomstabs:= Filtered( [ 1 .. Length( ord ) ], i -> ord[i] = subord );
    [ 144 ]
  
  
  The  permutation  representation  of  M_22  on  the  right  cosets of such a
  subgroup S is contained in the ATLAS of Group Representations.
  
    Example  
    gap> DisplayAtlasInfo( "M22", NrMovedPoints, 770 );
    Representations for G = M22:    (all refer to std. generators 1)
    ----------------------------
    12: G <= Sym(770) rank 9, on cosets of (A4xA4):4 < 2^4:A6
  
  
  Now we verify the information shown about the point stabilizer and about the
  maximal overgroups of S in M_22.
  
    Example  
    gap> maxtom:= MaximalSubgroupsTom( tom );
    [ [ 155, 154, 153, 152, 151, 150, 146, 145 ], 
      [ 22, 77, 176, 176, 231, 330, 616, 672 ] ]
    gap> List( tomstabs, i -> List( maxtom[1], j -> ContainedTom( tom, i, j ) ) );
    [ [ 0, 10, 0, 0, 0, 0, 0, 0 ] ]
  
  
  We  see that the only maximal subgroups of M_22 that contain S have index 77
  in  M_22.  According  to the ATLAS of Finite Groups, these maximal subgroups
  have  the  structure  2^4:A_6.  From  that and from the structure of A_6, we
  conclude that S has the structure 2^4:(3^2:4).
  
  Alternatively,  we  look at the permutation representation of degree 770. We
  fetch  it  from  the  ATLAS  of  Group Representations. There is exactly one
  nontrivial  block  system  for this representation, with 77 blocks of length
  10.
  
    Example  
    gap> g:= AtlasGroup( "M22", NrMovedPoints, 770 );
    <permutation group of size 443520 with 2 generators>
    gap> allbl:= AllBlocks( g );;
    gap> List( allbl, Length );
    [ 10 ]
  
  
  Furthermore, GAP computes that the point stabilizer S has the structure (A_4
  × A_4):4.
  
    Example  
    gap> stab:= Stabilizer( g, 1 );;
    gap> StructureDescription( stab : nice );
    "(A4 x A4) : C4"
    gap> blocks:= Orbit( g, allbl[1], OnSets );;
    gap> act:= Action( g, blocks, OnSets );;
    gap> StructureDescription( Stabilizer( act, 1 ) );
    "(C2 x C2 x C2 x C2) : A6"
  
  
  
  2.4-7 Example: Index 462 Subgroups in M_22
  
  The  ATLAS  of  Group  Representations contains three degree 462 permutation
  representations of the group M_22.
  
    Example  
    gap> DisplayAtlasInfo( "M22", NrMovedPoints, 462 );
    Representations for G = M22:    (all refer to std. generators 1)
    ----------------------------
    7: G <= Sym(462a) rank 5, on cosets of 2^4:A5 < 2^4:A6
    8: G <= Sym(462b) rank 8, on cosets of 2^4:A5 < L3(4), 2^4:S5
    9: G <= Sym(462c) rank 8, on cosets of 2^4:A5 < L3(4), 2^4:A6
  
  
  The  point  stabilizers  in  these  three representations have the structure
  2^4:A_5.  Using  GAP's  Library  of  Tables of Marks, we can show that these
  stabilizers are exactly the three classes of subgroups of order 960 in M_22.
  For that, we first verify that the group generators stored in GAP's table of
  marks  coincide  with  the  standard  generators  used by the ATLAS of Group
  Representations.
  
    Example  
    gap> tom:= TableOfMarks( "M22" );
    TableOfMarks( "M22" )
    gap> genstom:= GeneratorsOfGroup( UnderlyingGroup( tom ) );;
    gap> checkM22:= AtlasProgram( "M22", "check" );
    rec( groupname := "M22", identifier := [ "M22", "M22G1-check1", 1, 1 ]
        , program := <straight line decision>, standardization := 1, 
      version := "1" )
    gap> ResultOfStraightLineDecision( checkM22.program, genstom );
    true
  
  
  There are indeed three classes of subgroups of order 960 in M_22.
  
    Example  
    gap> ord:= OrdersTom( tom );;
    gap> tomstabs:= Filtered( [ 1 .. Length( ord ) ], i -> ord[i] = 960 );
    [ 147, 148, 149 ]
  
  
  Now  we  compute  representatives  of  these  three  classes  in  the  three
  representations  462a, 462b, and 462c. We see that each of the three classes
  occurs as a point stabilizer in exactly one of the three representations.
  
    Example  
    gap> atlasreps:= AllAtlasGeneratingSetInfos( "M22", NrMovedPoints, 462 );
    [ rec( charactername := "1a+21a+55a+154a+231a", 
          constituents := [ 1, 2, 5, 7, 9 ], contents := "core", 
          groupname := "M22", id := "a", 
          identifier := 
            [ "M22", [ "M22G1-p462aB0.m1", "M22G1-p462aB0.m2" ], 1, 462 ],
          isPrimitive := false, p := 462, rankAction := 5, 
          repname := "M22G1-p462aB0", repnr := 7, size := 443520, 
          stabilizer := "2^4:A5 < 2^4:A6", standardization := 1, 
          transitivity := 1, type := "perm" ), 
      rec( charactername := "1a+21a^2+55a+154a+210a", 
          constituents := [ 1, [ 2, 2 ], 5, 7, 8 ], contents := "core", 
          groupname := "M22", id := "b", 
          identifier := 
            [ "M22", [ "M22G1-p462bB0.m1", "M22G1-p462bB0.m2" ], 1, 462 ],
          isPrimitive := false, p := 462, rankAction := 8, 
          repname := "M22G1-p462bB0", repnr := 8, size := 443520, 
          stabilizer := "2^4:A5 < L3(4), 2^4:S5", standardization := 1, 
          transitivity := 1, type := "perm" ), 
      rec( charactername := "1a+21a^2+55a+154a+210a", 
          constituents := [ 1, [ 2, 2 ], 5, 7, 8 ], contents := "core", 
          groupname := "M22", id := "c", 
          identifier := 
            [ "M22", [ "M22G1-p462cB0.m1", "M22G1-p462cB0.m2" ], 1, 462 ],
          isPrimitive := false, p := 462, rankAction := 8, 
          repname := "M22G1-p462cB0", repnr := 9, size := 443520, 
          stabilizer := "2^4:A5 < L3(4), 2^4:A6", standardization := 1, 
          transitivity := 1, type := "perm" ) ]
    gap> atlasreps:= List( atlasreps, AtlasGroup );;
    gap> tomstabreps:= List( atlasreps, G -> List( tomstabs,
    > i -> RepresentativeTomByGenerators( tom, i, GeneratorsOfGroup( G ) ) ) );;
    gap> List( tomstabreps, x -> List( x, NrMovedPoints ) );
    [ [ 462, 462, 461 ], [ 460, 462, 462 ], [ 462, 461, 462 ] ]
  
  
  More   precisely,   we   see   that  the  point  stabilizers  in  the  three
  representations  462a, 462b, 462c lie in the subgroup classes 149, 147, 148,
  respectively, of the table of marks.
  
  The  point  stabilizers in the representations 462b and 462c are isomorphic,
  but not isomorphic with the point stabilizer in 462a.
  
    Example  
    gap> stabs:= List( atlasreps, G -> Stabilizer( G, 1 ) );;
    gap> List( stabs, IdGroup );
    [ [ 960, 11358 ], [ 960, 11357 ], [ 960, 11357 ] ]
    gap> List( stabs, PerfectIdentification );
    [ [ 960, 2 ], [ 960, 1 ], [ 960, 1 ] ]
  
  
  The  three  representations  are  imprimitive.  The containment of the point
  stabilizers  in maximal subgroups of M_22 can be computed using the table of
  marks of M_22.
  
    Example  
    gap> maxtom:= MaximalSubgroupsTom( tom );
    [ [ 155, 154, 153, 152, 151, 150, 146, 145 ], 
      [ 22, 77, 176, 176, 231, 330, 616, 672 ] ]
    gap> List( tomstabs, i -> List( maxtom[1], j -> ContainedTom( tom, i, j ) ) );
    [ [ 21, 0, 0, 0, 1, 0, 0, 0 ], [ 21, 6, 0, 0, 0, 0, 0, 0 ], 
      [ 0, 6, 0, 0, 0, 0, 0, 0 ] ]
  
  
  We see:
  
      The point stabilizers in 462a (subgroups in the class 149 of the table
        of  marks) are contained only in maximal subgroups in class 154; these
        groups have the structure 2^4:A_6.
  
      The  point  stabilizers  in  462b  (subgroups  in  the  class 147) are
        contained  in  maximal  subgroups  in  the  classes 155 and 151; these
        groups have the structures L_3(4) and 2^4:S_5, respectively.
  
      The  point  stabilizers  in  462c  (subgroups  in  the  class 148) are
        contained in maximal subgroups in the classes 155 and 154.
  
  We  identify the supergroups of the point stabilizers by computing the block
  systems.
  
    Example  
    gap> bl:= List( atlasreps, AllBlocks );;
    gap> List( bl, Length );
    [ 1, 3, 2 ]
    gap> List( bl, l -> List( l, Length ) );
    [ [ 6 ], [ 21, 21, 2 ], [ 21, 6 ] ]
  
  
  Note  that the two block systems with blocks of length 21 for 462b belong to
  the same supergroups (of the type L_3(4)); each of these subgroups fixes two
  different subsets of 21 points.
  
  The  representation 462a is multiplicity-free, that is, it splits into a sum
  of pairwise nonisomorphic irreducible representations. This can be seen from
  the  fact  that  the  rank  of this permutation representation (that is, the
  number  of  orbits  of  the  point  stabilizer)  is  five;  each permutation
  representation with this property is multiplicity-free.
  
  The other two representations have rank eight. We have seen the ranks in the
  overview that was shown by DisplayAtlasInfo (3.5-1) in the beginning. Now we
  compute the ranks from the permutation groups.
  
    Example  
    gap> List( atlasreps, RankAction );
    [ 5, 8, 8 ]
  
  
  In  fact  the  two  representations  462b and 462c have the same permutation
  character. We check this by computing the possible permutation characters of
  degree 462 for M_22, and decomposing them into irreducible characters, using
  the character table from GAP's Character Table Library.
  
    Example  
    gap> t:= CharacterTable( "M22" );;
    gap> perms:= PermChars( t, 462 );
    [ Character( CharacterTable( "M22" ),
      [ 462, 30, 3, 2, 2, 2, 3, 0, 0, 0, 0, 0 ] ), 
      Character( CharacterTable( "M22" ),
      [ 462, 30, 12, 2, 2, 2, 0, 0, 0, 0, 0, 0 ] ) ]
    gap> MatScalarProducts( t, Irr( t ), perms );
    [ [ 1, 1, 0, 0, 1, 0, 1, 0, 1, 0, 0, 0 ], 
      [ 1, 2, 0, 0, 1, 0, 1, 1, 0, 0, 0, 0 ] ]
  
  
  In   particular,   we   see   that   the   rank  eight  characters  are  not
  multiplicity-free.