% This file was created automatically from atlasrep.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  atlasrep.msk           GAP documentation                Thomas Breuer
%%
%H  $Id: atlasrep.msk,v 1.17 2001/01/22 18:12:08 gap Exp $
%%
%Y  Copyright (C) 2001, Lehrstuhl D fuer Mathematik, RWTH Aachen, Germany
%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Introduction to the AtlasRep Package}

The aim of the {\GAP} share package AtlasRep is to provide a link between
{\GAP} and the ``{\ATLAS} of Group Representations'',
a database that comprises representations of many almost simple groups
and information about their maximal subgroups.
This database has been available independent of {\GAP}
at~\URL{http://www.mat.bham.ac.uk/atlas}

The AtlasRep package consists of this database and a {\GAP} interface.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{An Atlas of Group Representations}

The Atlas of Group Representations consists of matrices over various rings,
permutations, and shell scripts encoding so-called straight line programs
\index{straight line program}
(see~\cite{BSW01} and~"ref:Straight Line Programs" in the {\GAP} Reference
Manual).
These programs can be used to compute certain elements in a group $G$
from its standard generators
(see~\cite{Wil96} and~"ref:Standard Generators of Groups" in the {\GAP}
Reference Manual) of $G$,
for example generators of maximal subgroups of $G$
or representatives of conjugacy classes of $G$.

The {\ATLAS} of Group Representations has been prepared by Robert Wilson,
Peter Walsh, Jonathan Tripp, Ibrahim Suleiman, Stephen Rogers,
Richard Parker, Simon Norton, Steve Linton, and John Bray
(in reverse alphabetical order).

The information was computed and composed using computer algebra systems
such as {\MeatAxe} (see~\cite{Rin98}),\indextt{MeatAxe}
Magma (see~\cite{CP96}),\indextt{Magma}
and {\GAP} (in reverse alphabetical order).
Part of the constructions have been documented in the literature on
almost simple groups, or the results have been used in such publications,
see for example the references in~\cite{CCN85} and~\cite{BN95}.

If you use the {\ATLAS} of Group Representations to solve a problem then
please send a short email to~\Mailto{R.A.Wilson@bham.ac.uk} about it.
The {\ATLAS} of Group Representations database should be referenced
with the entry~\cite{AGR} in the bibliography of this manual.

If your work made use of functions of the {\GAP} interface
(see~"The GAP Interface to the Atlas of Group Representations")
then you should also reference this interface,
via the entry~\cite{Bre01} in the bibliography of this manual.

For referencing the {\GAP} system in general,
use the entry~\cite{GAP4} in the bibliography of this manual.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{The GAP Interface to the Atlas of Group Representations}

The {\GAP} interface to the {\ATLAS} of Group Representations consists of
essentially two parts.
First, there is the *user interface* which allows the user to get an overview
of the contents of the database, and to access the data in {\GAP} format;
this is described in Chapter~"The User Interface of the AtlasRep Package".
Second, there is *administrational information*
which is important only for users interested in the actual implementation
(e.~g., for modifying the package) or in using it together with the
C-{\MeatAxe}\index{C-{\MeatAxe}} standalone (see~\cite{Rin98});
this is described in Chapter~"Technicalities of the AtlasRep Package".

Information concerning the C-{\MeatAxe}, including the manual~\cite{Rin98},
can be found at~\URL{http://www.math.rwth-aachen.de/LDFM/homes/MTX}

A {\GAP} Share Package that provides access to the functionality of the
C-{\MeatAxe} is in preparation.

The {\GAP} interface should be regarded as preliminary.
Hopefully it will become more user-friendly when the
{\ATLAS} of Group Representations will be integrated into a larger {\GAP}
database of groups and their representations, character tables, and
tables of marks.

The interface and this manual have been provided by Thomas Breuer.
Comments, bug reports, and hints for improving the interface
can be sent to~\Mailto{sam@math.rwth-aachen.de}.
% There is a reference to this statement in
% Chapter~"The User Interface of the AtlasRep Package".


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Local or Remote Installation of the AtlasRep Share Package}

There are two possibilities to install the AtlasRep share package.
\beginitems
*Local installation* &
    You can install the whole database physically as a part of the local
    copy of {\GAP};
    the uncompressed data will require at least half a gigabyte of disk
    space.

*Remote installation* &
    If your computer is connected to a network that provides access to
    the {\ATLAS} data (for example the internet) then you can
    alternatively install just the functions of the package.
    It is then left to these functions to fetch the requested data
    automatically from remote servers\index{remote access}\index{servers}
    when they are required for the first time;
    these data are then stored in the local copy, later access to them
    needs no network transfer.
\enditems

The latter possibility is presently not used by other {\GAP} packages,
so it may be regarded as an important feature of the AtlasRep package.
Anyhow it requires a few sentences of explanation.

The possibility of a remote installation reflects in particular the fact
that the {\ATLAS} of Group Representations is designed as an *open database*,
it is expected to grow.
As soon as the developers of the {\ATLAS} of Group Representations add
new information to the servers,
these data become available in remote installations of the package
after updating the corresponding table of contents.
Within a {\GAP} session, one can update this table of contents using
`ReloadAtlasTableOfContents' (see~"ReloadAtlasTableOfContents").
For convenience, one can also use the `maketoc' script in the `etc'
directory of the package for regular updating the file `atlasprm.g'
in the `gap' directory of the package; the file `atlasprm.g' is read
whenever the AtlasRep package is loaded, this file is used as
table of contents of the servers before `ReloadAtlasTableOfContents'
is called for the first time in the current {\GAP} session.

Currently there is just one remote server.
As soon as new servers become available, or a server name is changed
(see~"Global Variables Used by the AtlasRep Package"),
which makes it necessary to adjust the installation of the AtlasRep package,
this will be announced in the {\GAP} Forum
(see~"tut:Further Information about GAP" in the {\GAP} Tutorial).
The same holds when upgrades of the package become available.
Additionally, the {\GAP} servers will provide this information.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing the AtlasRep Share Package}

To install the AtlasRep share package unpack the archive file in a
directory in the `pkg' directory of your local copy of {\GAP}~4.
This might be the `pkg' directory of the {\GAP}~4 home directory,
see Section~"ref:Installing Share Packages"
of the {\GAP}~4 Reference Manual for details.
It is however also possible to keep an additional `pkg' directory
in your private directories,
see~"ref:Installing a Share Package in your home directory"
of the {\GAP}~4 Reference Manual.
The latter possibility *must* be chosen if you do not have write access
to the {\GAP} root directory.
% previous paragraph inspired by the corresponding section of the GRAPE
% package

The package consists entirely of {\GAP} code plus a few scripts,
no external binaries need to be compiled.

Both dvi and PostScript versions of the AtlasRep manual are available
(as `manual.dvi' and `manual.ps' respectively) in the `doc' directory
of the home directory of AtlasRep.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{More About Installing the AtlasRep Share Package}

When {\GAP} uses the feature to access files on remote servers,
it calls the system programs `perl', `awk', `ftp', and `ls';
the relevant scripts can be found in the `etc' directory of the package.
This works under UNIX, but may cause problems when used with other
operating systems.
For example, in principle the system programs needed are available for
MS-Windows, but it may require some work to install them.

A further change may be useful if in principle there is a network connection
to a remote server but {\GAP} shall not attempt to access remote data.
In this case, the value of the `remote' component of the global variable
`AtlasOfGroupRepresentationsInfo' (see~"AtlasOfGroupRepresentationsInfo")
should be set from the default `true' to `false';
this affects only the file `atlasprm.g' in the `gap' directory of the
package.

% how to add servers?

Independent of the default value of `AtlasOfGroupRepresentationsInfo'
(see~"AtlasOfGroupRepresentationsInfo"),
each user can individually change the `remote' and `servers' components
of this record, for example using a `.gaprc' file
(see~"ref:The .gaprc file" in the {\GAP} Reference Manual).
Note that if in the {\GAP} installation, the `remote' value is set to `false'
then it might be impossible to actually store files fetched from a remote
server in the data directories of the installed package;
in such cases, it is advisable for the user in question to install the
package or just its data directories in a private directory,
see~"ref:Installing a Share Package in your home directory" in the {\GAP}
Reference Manual for details.
Removing entries from the `servers' list means to disable access to the
corresponding servers.
Adding entries makes of course sense only if corresponding servers really
exist, for example in a local network.

For checking the installation, one can run the tests in the files
`atlasrep.tst' and `docxpl.tst' in the `tst' directory of the package
(see~"Sanity Checks for the Atlas of Group Representations" for details).


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Loading the AtlasRep Share Package}

The AtlasRep package may be loaded automatically when {\GAP} is started,
or it has to be loaded within {\GAP} as follows.
\begintt
gap> RequirePackage( "atlasrep" );
\endtt
See~"ref:Loading a Share Package" in the {\GAP} Reference Manual
for details about these alternatives.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Extending the Atlas Database}

Users who have computed new representations that might be interesting for
inclusion into the {\ATLAS} of Group representations can send the data in
question to~\Mailto{R.A.Wilson@bham.ac.uk}.

Local extensions of the database by ``private'' representations and
straight line programs are currently not supported.

In particular, one should *not* add private files to the local data
directories, 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.)


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Acknowledgements}

The perl script for fetching remote data has been kindly provided by
Frank L{\accent127 u}beck and Max Neunh{\accent127 o}ffer.


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

