% This file was created automatically from extend.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  extend.msk                GAP documentation             Thomas Breuer
%%
%H  $Id: extend.msk,v 1.13 2004/03/19 16:35:47 gap Exp $
%%
%Y  Copyright (C) 2002, Lehrstuhl D fuer Mathematik, RWTH Aachen, Germany
%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Private Extensions of the AtlasRep Package}

It may be interesting to use the functions of the {\GAP} interface also
for representations or straight line programs that are *not* part of the
{\ATLAS} of Group Representations.
This chapter describes how to achieve this.

Note that the features described in this chapter can be used only if the
system program `ls' is available.

The main idea is that users can notify directories containing the ``private''
data files, which may consist of
\beginlist
\item{1.}
new representations and straight line programs for groups that are declared
already in the ``official'' {\ATLAS} of Group Representations,
\item{2.}
the declaration of groups that are not declared in the ``official'' {\ATLAS}
of Group Representations,
and representations and straight line programs for them, and
\item{3.}
the definition of new kinds of representations and straight line programs.
\endlist

The first two kinds are dealt with in~"Adding a Private Data Directory"
and~"The Effect of Private Extensions on the User Interface".
The last is sketched in~"Data Types", technical details are described
in~"Data Types Used in the Atlas of Group Representations".

Finally, an example of using private extensions is given
in~"An Example of Extending the AtlasRep Package".


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Adding a Private Data Directory}

After the AtlasRep package has been loaded into the {\GAP} session,
one can add private data.
However, one should *not* add private files to the local data
directories of the package, or modify files in these directories.
It should be noted that a data file is fetched from a server only if
the local data directories do not contain a file with this name,
independent of the contents of the files.
(As a consequence, corrupted files in the local data directories are
*not* automatically replaced by a correct server file.)



\>AtlasOfGroupRepresentationsNotifyPrivateDirectory( <dirname>[, <dirid>] ) F

Let <dirname> be a string denoting the name of a directory,
such that `Directory( <dirname> )' is the {\GAP} object describing this
directory (see~"ref:Directory" in the {\GAP} Reference Manual).
This means that <dirname> can be an absolute path or a path relative to
the home directory of the user (starting with a tilde character `~')
or a path relative to the directory where {\GAP} was started.

If the second argument <dirid> is given, it must be a string.
This value will be used in the `identifier' components of the records
that are returned by interface functions
(see~"Accessing Data of the AtlasRep Package") for data contained in the
directory with name <dirname>.
Note that the directory name may be different in different {\GAP}
sessions or for different users who want to access the same data,
whereas the `identifier' components shall be independent of such
differences.
The default for <dirid> is <dirname>.

`AtlasOfGroupRepresentationsNotifyPrivateDirectory' notifies the data in
the directory with name <dirname> to the AtlasRep package.
First the pair `[ <dirname>, <dirid> ]' is added to the global variable
`AtlasOfGroupRepresentationsInfo.private'.
If the directory contains a file with the name `toc.g' then this file
is read;
this file is useful for adding new group names (see~"AGRGNAN"),
for adding field information for characteristic zero representations
(see~"AGRFLD"),
or for adding new data types (see~"Data Types").
Next the table of contents of the private directory is built from the
list of files contained in (subdirectories of) the private directory.

Only those files are considered whose names match an admissible format
(see~"Filenames Used in the Atlas of Group Representations"
and~"Data Types").
Filenames that are already contained in another data directory of the
AtlasRep package are ignored, and messages about these filenames are
printed if the info level of `InfoAtlasRep' (see~"InfoAtlasRep") is
at least $1$.

Note that this implies that the files of the ``official''
(i.e. non-private) data directories have priority over files in private
directories.

If the directory contains files for groups whose names have not been
declared before and if the info level of `InfoAtlasRep' is at least $1$
then a message about these names is printed.

The function returns `true' if none of the filenames with admissible
format in the directory is contained in other data directories
and if the data belongs to groups whose names have been declared.
Otherwise `false' is returned.



For convenience, the user may collect the notifications of private data
directories in the file `.gaprc'
(see~"ref:The .gaprc file" in the {\GAP} Reference Manual).

Several of the sanity checks for the official part of the AtlasRep package
make sense also for private extensions,
see~"Sanity Checks for the Atlas of Group Representations" for more
information.

\>AtlasOfGroupRepresentationsForgetPrivateDirectory( <dirid> ) F

If <dirid> is the identifier of a private data directory that has been
notified with `AtlasOfGroupRepresentationsNotifyPrivateDirectory'
(see~"AtlasOfGroupRepresentationsNotifyPrivateDirectory")
then `AtlasOfGroupRepresentationsForgetPrivateDirectory' removes the
directory from the list of notified private directories;
this means that from then on, the data in this directory cannot be
accessed anymore in the current session.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{The Effect of Private Extensions on the User Interface}

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

In this case, `DisplayAtlasInfo' (see~"DisplayAtlasInfo") lists the private
representations and straight line programs in the same way as the
``official'' data, except that private parts are marked with the string
stored in the component `markprivate' of `AtlasOfGroupRepresentationsInfo'
(see~"AtlasOfGroupRepresentationsInfo");
by default, this is a star `*'.
The ordering of representations listed by `DisplayAtlasInfo'
(and referred to by `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~"The User Interface of the AtlasRep Package",
the only difference is that also the private data can be accessed.
In particular the ``free format'' `<groupname>G<i>-X<descr>W<n>' for straight
line programs (see~"Filenames Used in the Atlas of Group Representations")
may be used in private directories;
the data can be accessed with `AtlasStraightLineProgram'
(see~"AtlasStraightLineProgram"), where the last two arguments are
the strings `"other"' and <descr>.

If also private data types are introduced (see~"Data Types") then
additional columns or rows can appear in the output of `DisplayAtlasInfo',
and new inputs can become meaningful for all interface functions.
Examples for these changes can be found
in~"An Example of Extending the AtlasRep Package".


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Data Types}

Each representation or straight line program that is administrated by the
AtlasRep package belongs to a unique *data type*.
Informally, examples of data types are ``permutation representation'',
``matrix representation over the integers'', or ``straight line program for
computing class representatives''.

The idea is that for each data type, there can be
\beginlist
\item{-}
    a column of its own in the output produced by `DisplayAtlasInfo'
    when called without arguments or with only argument a list of
    group names (see~"DisplayAtlasInfo"),
\item{-}
    a line format of its own for the output produced by `DisplayAtlasInfo'
    when called with first argument a group name (see~"DisplayAtlasInfo"),
\item{-}
    an input format of its own for `AtlasStraightLineProgram'
    (see~"AtlasStraightLineProgram"),
\item{-}
    an input format of its own for `OneAtlasGeneratingSetInfo'
    (see~"OneAtlasGeneratingSetInfo"), and
\item{-}
    specific tests for the data of this data type.
\endlist

Formally, a data type is defined by a record whose components are used by
the interface functions.  The details are described
in~"Data Types Used in the Atlas of Group Representations".


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{An Example of Extending the AtlasRep Package}

Let us assume that the directory `privdir' contains two subdirectories
`C4' and `S5' (one could choose other names for these subdirectories),
with data for the cyclic group $C_4$ of order $4$
and for the symmetric group $S_5$ on $5$ points, respectively.
Note that it is obvious what the term ``standard generators'' means for
the group $C_4$.

Further let us assume that `privdir' contains the following files.
\beginitems
`C4G1-p4B0.m1' &
    a faithful permutation representation of $C_4$ on $4$ points,

`C4G1-max1W1' &
    the straight line program that returns the square of its unique input,

`C4G1-a2W1' &
    the straight line program that applies an outer automorphism to its
    unique input,

`C4G1-XtestW1' &
    the straight line program that returns the square of its unique input,

`S5G1-p2B0.m1' and `S5G1-p2B0.m2' &
    the permutation representation of the commutator factor group of $S_5$,
    on $2$ points.
\enditems

The directory and the files can be created as follows.

% The example is documented in the test file `tst/extend.tst'.
% Note that we cannot process the following examples only if the
% system program `ls' is available, so we omit them from `docxpl.tst'.
\begintt
gap> pkg:= Filename( DirectoriesPackageLibrary( "atlasrep", "" ), "" );;
gap> prv:= Filename( Directory( pkg ), "privdir" );;
gap> if IsExistingFile( prv ) <> true then
>      Exec( Concatenation( "mkdir ", prv ) );
>    fi;
gap> priv:= Filename( Directory( prv ), "C4" );;
gap> if IsExistingFile( priv ) <> true then
>      Exec( Concatenation( "mkdir ", priv ) );
>    fi;
gap> privdir:= Directory( priv );;
gap> PrintTo( Filename( privdir, "C4G1-p4B0.m1" ),
>             MeatAxeString( [ (1,2,3,4) ], 4 ) );
gap> PrintTo( Filename( privdir, "C4G1-max1W1" ),
>             "inp 1\npwr 2 1 2\noup 1 2\n" );
gap> PrintTo( Filename( privdir, "C4G1-XtestW1" ),
>             "inp 1\npwr 2 1 2\noup 1 2\n" );
gap> PrintTo( Filename( privdir, "C4G1-a2W1" ),
>             "inp 1\npwr 3 1 2\noup 1 2\n" );
gap> PrintTo( Filename( privdir, "C4G1-Ar1aB0.g" ),
>             "return rec( generators:= [ [[E(4)]] ] );\n" );
gap> priv:= Filename( Directory( prv ), "S5" );;
gap> if IsExistingFile( priv ) <> true then
>      Exec( Concatenation( "mkdir ", priv ) );
>    fi;
gap> privdir:= Directory( priv );;
gap> PrintTo( Filename( privdir, "S5G1-p2B0.m1" ),
>             MeatAxeString( [ (1,2) ], 2 ) );
gap> PrintTo( Filename( privdir, "S5G1-p2B0.m2" ),
>             MeatAxeString( [ (1,2) ], 2 ) );
\endtt

The official part of the AtlasRep package does not contain information
about $C_4$, so we first notify this group, in the file `privdir/toc.g'.
(The group $S_5$ is known with name `A5.2' in the official part of the
AtlasRep package, so it need not be notified.)
Then we notify the private directory.

\begintt
gap> PrintTo( Filename( Directory( prv ), "toc.g" ),
>             "AGRGNAN(\"C4\",\"C4\");\n" );
gap> AtlasOfGroupRepresentationsNotifyPrivateDirectory( prv, "priv" );
true
\endtt

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

\begintt
gap> DisplayAtlasInfo( "C4" );
Representations for G = C4:    (all refer to std. generators 1)
---------------------------
1: G <= Sym(4)*
2: G <= GL(1a,C)*

Straight line programs for G = C4:    (all refer to std. generators 1)
----------------------------------
available maxes of G:  [ 1 ]*
available automorphisms:  [ "2" ]*
available other scripts:  [ "test" ]*
gap> DisplayAtlasInfo( "A5.2", NrMovedPoints, 2 );
Representations for G = A5.2:    (all refer to std. generators 1)
-----------------------------
4: G <= Sym(2)*
gap> info:= OneAtlasGeneratingSetInfo( "C4" );
rec( identifier := [ [ "priv", "C4" ], [ "C4/C4G1-p4B0.m1" ], 1, 4 ] )
gap> AtlasGeneratord( info.identifier );
rec( generators := [ (1,2,3,4) ], standardization := 1, 
  identifier := [ [ "priv", "C4" ], [ "C4/C4G1-p4B0.m1" ], 1, 4 ] )
gap> AtlasStraightLineProgram( "C4", "maxes", 1 );
rec( program := <straight line program>, standardization := 1, 
  identifier := [ [ "priv", "C4" ], "C4/C4G1-max1W1", 1 ] )
gap> AtlasGenerators( "C4", 1 );
rec( generators := [ (1,2,3,4) ], standardization := 1, 
  identifier := [ [ "priv", "C4" ], [ "C4/C4G1-p4B0.m1" ], 1, 4 ] )
gap> AtlasStraightLineProgram( "C4", "other", "test" );
rec( program := <straight line program>, standardization := 1, 
  identifier := [ [ "priv", "C4" ], "C4/C4G1-XtestW1", 1 ] )
\endtt

For checking the data in the private directory,
we apply some of the sanity checks
(see~"Sanity Checks for the Atlas of Group Representations").

\begintt
gap> AtlasOfGroupRepresentationsTestWords( "priv" );
true
gap> AtlasOfGroupRepresentationsTestFileHeaders( "priv" );
true
\endtt

Finally, we ``uninstall'' the private directory, and then remove the data.
(Also the group name `C4' is removed this way, which is an advantage of
using a `toc.g' file over calling `AGRGNAN' directly.)

\begintt
gap> AtlasOfGroupRepresentationsForgetPrivateDirectory( "priv" );
gap> Exec( Concatenation( "rm -rf ", prv ) );
\endtt


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E

