extend.xml

<!-- %W  extend.xml      GAP 4 package AtlasRep             Thomas Breuer -->
<!-- %Y  Copyright 2002, Lehrstuhl D f�r Mathematik, RWTH Aachen, Germany -->


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Chapter Label="chap:Private Extensions">
<Heading>Private Extensions of the <Package>AtlasRep</Package> Package
</Heading>

It may be interesting to use the functions of the &GAP; interface also
for representations or programs that are <E>not</E> part of the
&ATLAS; of Group Representations.
This chapter describes how to achieve this.

<P/>

The main idea is that users can notify directories containing the
<Q>private</Q> data files, which may consist of

<Enum>
<Item>
  new faithful representations and programs for groups
  that are declared already in the <Q>official</Q>
  &ATLAS; of Group Representations,
</Item>
<Item>
  the declaration of groups that are not declared in the <Q>official</Q>
  &ATLAS; of Group Representations,
  and representations and programs for them, and
</Item>
<Item>
  the definition of new kinds of representations and programs.
</Item>
</Enum>

<P/>

The first two issues are dealt with in
Section&nbsp;<Ref Sect="sect:Adding a Private Data Directory"/>
and Section&nbsp;<Ref Sect="sect:Effect of Private Extensions"/>.
The last is described in
Section&nbsp;<Ref Sect="sect:Data Types Used in the AGR"/>.

<P/>

Finally, an example of using private extensions is given in
Section&nbsp;<Ref Sect="sect:An Example of Extending AtlasRep"/>.

<P/>

Several of the sanity checks for the official part of the
<Package>AtlasRep</Package> package make sense also for private extensions,
see Section&nbsp;<Ref Sect="sect:AGR Sanity Checks"/>
for more information.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Adding a Private Data Directory">
<Heading>Adding a Private Data Directory</Heading>

<#Include Label="[3]{access}">
<#Include Label="AtlasOfGroupRepresentationsNotifyPrivateDirectory">
<#Include Label="AtlasOfGroupRepresentationsForgetPrivateDirectory">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Effect of Private Extensions">
<Heading>The Effect of Private Extensions on the User Interface</Heading>

First suppose that only new groups or new data for known groups are added.

<P/>

In this case, <Ref Func="DisplayAtlasInfo"/> lists the private
representations and programs in the same way as the
<Q>official</Q> data, except that private parts are marked with the string
stored in the component <C>markprivate</C> of
<Ref Var="AtlasOfGroupRepresentationsInfo"/>;
by default, this is a star <C>*</C>.
The ordering of representations listed by <Ref Func="DisplayAtlasInfo"/>
(and referred to by <Ref Func="AtlasGenerators"/>) will in general change
when private directories are notified.
If several private directories are used then the ordering of data may depend
on the ordering of notifications.
For the other interface functions described in
Chapter&nbsp;<Ref Chap="chap:The User Interface of the AtlasRep Package"/>,
the only difference is that also the private data can be accessed.
In particular the <Q>free format</Q>
<C><A>groupname</A>G<A>i</A>-X<A>descr</A>W<A>n</A></C>
for straight line programs
(see Section&nbsp;<Ref Sect="sect:Filenames Used in the AGR"/>)
may be used in private directories;
the data can be accessed with <Ref Func="AtlasProgram"/>,
where the last two arguments are the strings <C>"other"</C> and <A>descr</A>.

<P/>

If also private data types are introduced
(see Section&nbsp;<Ref Sect="sect:Data Types Used in the AGR"/>)
then additional columns or rows can appear in the output of
<Ref Func="DisplayAtlasInfo"/>,
and new inputs can become meaningful for all interface functions.
Examples for these changes can be found in
Section&nbsp;<Ref Sect="sect:An Example of Extending AtlasRep"/>.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:An Example of Extending AtlasRep">
<Heading>An Example of Extending the <Package>AtlasRep</Package> Package
</Heading>

In the beginning we set the info level of <Ref InfoClass="InfoAtlasRep"/>
to <M>1</M>.

<Example><![CDATA[
gap> level:= InfoLevel( InfoAtlasRep );;
gap> SetInfoLevel( InfoAtlasRep, 1 );
]]></Example>

Let us assume that the directory <F>privdir</F> contains
data for the cyclic group <M>C_4</M> of order <M>4</M>
and for the alternating group <M>A_5</M> on <M>5</M> points, respectively.
Note that it is obvious what the term <Q>standard generators</Q> means for
the group <M>C_4</M>.

<P/>

Further let us assume that <F>privdir</F> contains the following files.

<List>
<Mark><F>C4G1-p4B0.m1</F></Mark>
<Item>
    a faithful permutation representation of <M>C_4</M> on <M>4</M> points,
</Item>
<Mark><F>C4G1-max1W1</F></Mark>
<Item>
    the straight line program that returns the square of its unique input,
</Item>
<Mark><F>C4G1-a2W1</F></Mark>
<Item>
    the straight line program that raises its unique input to the third
    power,
</Item>
<Mark><F>C4G1-XtestW1</F></Mark>
<Item>
    the straight line program that returns the square of its unique input,
</Item>
<Mark><F>A5G1-p60B0.m1</F> and <F>A5G1-p60B0.m2</F></Mark>
<Item>
    the regular permutation representation of <M>A_5</M>.
</Item>
</List>

<P/>

The directory and the files can be created as follows.

<P/>

<Example><![CDATA[
gap> prv:= DirectoryTemporary( "privdir" );;
gap> FileString( Filename( prv, "C4G1-p4B0.m1" ),
>                MeatAxeString( [ (1,2,3,4) ], 4 ) );;
gap> FileString( Filename( prv, "C4G1-max1W1" ),
>                "inp 1\npwr 2 1 2\noup 1 2\n" );;
gap> FileString( Filename( prv, "C4G1-XtestW1" ),
>                "inp 1\npwr 2 1 2\noup 1 2\n" );;
gap> FileString( Filename( prv, "C4G1-a2W1" ),
>                "inp 1\npwr 3 1 2\noup 1 2\n" );;
gap> FileString( Filename( prv, "C4G1-Ar1aB0.g" ),
>                "return rec( generators:= [ [[E(4)]] ] );\n" );;
gap> points:= Elements( AlternatingGroup( 5 ) );;
gap> FileString( Filename( prv, "A5G1-p60B0.m1" ),
>      MeatAxeString( [ Permutation( (1,2)(3,4), points, OnRight ) ], 60 ) );;
gap> FileString( Filename( prv, "A5G1-p60B0.m2" ),
>      MeatAxeString( [ Permutation( (1,3,5), points, OnRight ) ], 60 ) );;
]]></Example>

<P/>

(We could also introduce intermediate directories <F>C4</F> and <F>A5</F>,
say, each with the data for one group only.
Here we do not show this because creating directories programmatically
seems to be possible only with the &GAP; package <Package>IO</Package>.)

<P/>

The official part of the <Package>AtlasRep</Package> package does not contain
information about <M>C_4</M>,
so we first notify this group, in the file <F>privdir/toc.g</F>.
Besides the name of the group, we store the following information:
the group order, the number of (classes of) maximal subgroups,
their orders, their structures, and describing data about the two
permutation representations.
(The group <M>A_5</M> is known with name <C>A5</C> in the official part
of the <Package>AtlasRep</Package> package,
so it cannot be notified again.)

<P/>

<Example><![CDATA[
gap> FileString( Filename( prv, "toc.g" ), Concatenation( [
>        "AGR.GNAN(\"C4\",\"C4\");\n",
>        "AGR.GRS(\"C4\",4);\n",
>        "AGR.MXN(\"C4\",1);\n",
>        "AGR.MXO(\"C4\",[2]);\n",
>        "AGR.MXS(\"C4\",[\"C2\"]);\n",
>        "AGR.API(\"C4G1-p4B0\",[1,4,\"imprim\",\"1 < C2\"]);\n",
>        "AGR.API(\"A5G1-p60B0\",[1,60,\"imprim\",\"1 < A4\"]);\n",
>        ] ) );;
]]></Example>

<P/>

Then we notify the private directory.

<P/>

<Example><![CDATA[
gap> AtlasOfGroupRepresentationsNotifyPrivateDirectory( prv, "priv", true );
true
]]></Example>

<P/>

Now we can use the interface functions for accessing the data in the
private directory.

<P/>

<Example><![CDATA[
gap> DisplayAtlasInfo( [ "C4" ] );
group | # | maxes | cl | cyc | out | fnd | chk | prs
------+---+-------+----+-----+-----+-----+-----+----
C4*   | 2 |     1 |    |     |   2 |     |     |    
gap> DisplayAtlasInfo( "C4" );
Representations for G = C4:    (all refer to std. generators 1)
---------------------------
1: G <= Sym(4)*   rank 4, on cosets of 1 < C2
2: G <= GL(1a,C)* 

Programs for G = C4:    (all refer to std. generators 1)
--------------------
automorphisms:
  2*
maxes (all 1):
  1*:  C2
other scripts:
  "test"*
gap> DisplayAtlasInfo( "C4", IsPermGroup, true );
Representations for G = C4:    (all refer to std. generators 1)
---------------------------
1: G <= Sym(4)* rank 4, on cosets of 1 < C2
gap> DisplayAtlasInfo( "C4", IsMatrixGroup );
Representations for G = C4:    (all refer to std. generators 1)
---------------------------
2: G <= GL(1a,C)* 
gap> DisplayAtlasInfo( "C4", Dimension, 2 );
gap> DisplayAtlasInfo( "A5", NrMovedPoints, 60 );
Representations for G = A5:    (all refer to std. generators 1)
---------------------------
4: G <= Sym(60)* rank 60, on cosets of 1 < A4
gap> info:= OneAtlasGeneratingSetInfo( "C4" );
rec( groupname := "C4", id := "", 
  identifier := [ [ "priv", "C4" ], [ "C4G1-p4B0.m1" ], 1, 4 ], 
  isPrimitive := false, p := 4, rankAction := 4, 
  repname := "C4G1-p4B0", repnr := 1, size := 4, 
  stabilizer := "1 < C2", standardization := 1, transitivity := 1, 
  type := "perm" )
gap> AtlasGenerators( info.identifier );
rec( generators := [ (1,2,3,4) ], groupname := "C4", id := "", 
  identifier := [ [ "priv", "C4" ], [ "C4G1-p4B0.m1" ], 1, 4 ], 
  isPrimitive := false, p := 4, rankAction := 4, 
  repname := "C4G1-p4B0", repnr := 1, size := 4, 
  stabilizer := "1 < C2", standardization := 1, transitivity := 1, 
  type := "perm" )
gap> AtlasProgram( "C4", 1 );
rec( groupname := "C4", 
  identifier := [ [ "priv", "C4" ], "C4G1-max1W1", 1 ], 
  program := <straight line program>, size := 2, standardization := 1,
  subgroupname := "C2" )
gap> AtlasProgram( "C4", "maxes", 1 );
rec( groupname := "C4", 
  identifier := [ [ "priv", "C4" ], "C4G1-max1W1", 1 ], 
  program := <straight line program>, size := 2, standardization := 1,
  subgroupname := "C2" )
gap> AtlasProgram( "C4", "maxes", 2 );
fail
gap> AtlasGenerators( "C4", 1 );
rec( generators := [ (1,2,3,4) ], groupname := "C4", id := "", 
  identifier := [ [ "priv", "C4" ], [ "C4G1-p4B0.m1" ], 1, 4 ], 
  isPrimitive := false, p := 4, rankAction := 4, 
  repname := "C4G1-p4B0", repnr := 1, size := 4, 
  stabilizer := "1 < C2", standardization := 1, transitivity := 1, 
  type := "perm" )
gap> AtlasGenerators( "C4", 2 );
rec( dim := 1, generators := [ [ [ E(4) ] ] ], groupname := "C4", 
  id := "a", identifier := [ [ "priv", "C4" ], "C4G1-Ar1aB0.g", 1, 1 ]
    , repname := "C4G1-Ar1aB0", repnr := 2, size := 4, 
  standardization := 1, type := "matalg" )
gap> AtlasGenerators( "C4", 3 );
fail
gap> AtlasProgram( "C4", "other", "test" );
rec( groupname := "C4", 
  identifier := [ [ "priv", "C4" ], "C4G1-XtestW1", 1 ], 
  program := <straight line program>, standardization := 1 )
]]></Example>

<P/>

We can restrict the data shown by <Ref Func="DisplayAtlasInfo"/> to the
private directory, as follows.

<P/>

<Example><![CDATA[
gap> DisplayAtlasInfo( "contents", "priv" );
group                    | # | maxes | cl | cyc | out | fnd | chk | p*
-------------------------+---+-------+----+-----+-----+-----+-----+--*
A5*                      | 1 |       |    |     |     |     |     |  *
C4*                      | 2 |     1 |    |     |   2 |     |     |  *
]]></Example>

<P/>

For checking the data in the private directory,
we apply the relevant sanity checks
(see Section&nbsp;<Ref Sect="sect:AGR Sanity Checks"/>).

<P/>

<Example><![CDATA[
gap> if not IsBound( AGR.Test ) then
>      ReadPackage( "atlasrep", "gap/test.g" );
>    fi;
gap> AGR.Test.Words( "priv" );
true
gap> AGR.Test.FileHeaders( "priv" );
true
gap> AGR.Test.Files( "priv" );
true
gap> AGR.Test.BinaryFormat( "priv" );
true
gap> AGR.Test.Primitivity( "priv" );
true
gap> AGR.Test.Characters( "priv" );
true
]]></Example>

<P/>

Finally, we <Q>uninstall</Q> the private directory,
and reset the info level that had been set to <M>1</M> in the beginning.
(Also the group name <C>C4</C> is removed this way, which is an advantage of
using a <F>toc.g</F> file over calling <C>AGRGNAN</C> directly.),
Note that we need not remove the data in the temporary directory,
&GAP; will do this automatically.

<P/>

<Example><![CDATA[
gap> AtlasOfGroupRepresentationsForgetPrivateDirectory( "priv" );
gap> SetInfoLevel( InfoAtlasRep, level );
]]></Example>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->

</Chapter>