% This file was created automatically from atlasrep.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  atlasrep.msk              GAP documentation             Thomas Breuer
%%
%H  $Id: atlasrep.msk,v 1.49 2004/04/02 16:36:57 gap Exp $
%%
%Y  Copyright (C) 2001, Lehrstuhl D fuer Mathematik, RWTH Aachen, Germany
%%


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

The aim of the {\GAP}~4 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://web.mat.bham.ac.uk/atlas/v2.0}

The AtlasRep package consists of this database
(see~"An Atlas of Group Representations")
and a {\GAP} interface
(see~"The GAP Interface to the Atlas of Group Representations");
the latter is extended by further information available via the internet
(see~"Web Services for the AtlasRep Package").

Information about installing and customizing the package can be found
in the sections~"Local or Remote Installation of the AtlasRep Package",
"Installing the AtlasRep Package",
"Maintaining the Local Data of the AtlasRep Package",
"User Parameters for the AtlasRep Package",
"Loading the AtlasRep Package", and
"Extending the Atlas Database".

Finally, the sections~"What's New in Version 1.2?"
and~"What's New in Version 1.1?" list the changes w.r.t. previous releases
of the package,
and Section~"Acknowledgements" acknowledges contributions of
non-authors to the package.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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}, \cite{SWW00},
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).

\indextt{MeatAxe}\indextt{Magma}

The information was computed and composed using computer algebra systems
such as {\MeatAxe} (see~\cite{Rin98}), Magma (see~\cite{CP96}), 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{AtlasRep} 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}

\index{C-{\MeatAxe}}
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} 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}~4 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{Web Services for the AtlasRep Package}

The home page of the AtlasRep package is
\URL{http://www.math.rwth-aachen.de/~Thomas.Breuer/atlasrep}

Besides package archives and introductory package information, it provides
\beginlist
\item{-}
  the current file with the *table of contents* (`gap/atlasprm.g'),
  which is needed for those who use `wget' for accessing data files
  (see~"User Parameters for the AtlasRep Package"),
\item{-}
  the list of *changes of server files* in HTML format
  (cf.~"Maintaining the Local Data of the AtlasRep Package"), and
\item{-}
  an *overview of the data* available via the {\GAP} interface to the
  {\ATLAS} of Group Representations, in HTML format;
  this is similar to the information shown by `DisplayAtlasInfo'
  (see~"DisplayAtlasInfo");
  further information can be found on the home page of the {\ATLAS}
  (see the introduction to this chapter).
\endlist


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

\index{remote access}\index{servers}

There are two possibilities to install the AtlasRep package.
\beginitems
*Local installation* &
    You can install the whole database physically as a part of the local
    copy of {\GAP}; see~"User Parameters for the AtlasRep Package"
    for the amount of disk space needed in this case.

*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 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
This is controlled by the component `remote' of the global variable
`AtlasOfGroupRepresentationsInfo' (see~"AtlasOfGroupRepresentationsInfo").

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
(see~"Updating the Tables of Contents of the AtlasRep Package").

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 Package}

To install the 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 a GAP Package"
of the {\GAP}~4 Reference Manual for details.
It is however also possible to keep an additional `pkg' directory
in your private directories,
see Section~"ref:GAP Root 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.

Data files (in the directories `pkg/atlasrep/datagens' and
`pkg/atlasrep/dataword') that are available from an earlier version of the
package are in principle kept;
see~"AtlasOfGroupRepresentationsTestTableOfContentsRemoteUpdates" for
necessary updates.

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

If one wants to use the remote installation of the package
(see~"Local or Remote Installation of the AtlasRep Package"),
one needs either `wget' or the perl module `libnet'.%
\index{perl}%
\index{wget}

Most Linux distributions provide the perl module `libnet' via add-ons.
(The module is called `libnet-perl' in Debian Linux and `perl-libnet' in
RedHat Linux.)
In the case that the `libnet' module is missing on your machine,
use `man perlmodinstall' for information on how to install it;
if you have to adjust the environment variable `PERLLIB',
call `man perlrun' for details.

If one does not want to use the remote installation of the package
then the value of the component `remote' of the global variable
`AtlasOfGroupRepresentationsInfo' (see~"AtlasOfGroupRepresentationsInfo")
must be set to `false'.
For this variant the system program `ls' is needed, so currently this
may be not available for example under the Windows operating system.

After unpacking the archive, it should be checked whether the subdirectories
`datagens' and `dataword' of the `atlasrep' directory have write permissions
for those users who will download files from the servers.
The recommended permissions under UNIX are set as follows.

\begintt
you@unix> chmod 1777 atlasrep/data*
you@unix> ls -ld atlasrep/data*
drwxrwxrwt   3 you      you          1024 Oct 31 12:34 datagens
drwxrwxrwt   3 you      you          1024 Oct 31 12:34 dataword
\endtt

For checking the installation of the package, you should start {\GAP},
load the package (see~"Loading the AtlasRep Package"), and then call
\begintt
gap> ReadPackage( "atlasrep", "tst/testinst.g" );
\endtt
If the installation is o.k.~then the {\GAP} prompt appears without
anything else being printed;
otherwise the output lines tell you what should be changed.

More testfiles are available in the `tst' directory of the package
(see~"Sanity Checks for the Atlas of Group Representations" for details).



Both dvi and pdf versions of the package manual are available
(as `manual.dvi' and `manual.pdf' respectively) in the `doc' directory
of the package,
an HTML version can be found in the `htm' directory.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Maintaining the Local Data of the AtlasRep Package}

It may be useful if a system administrator runs the following function
from time to time, and then removes the files listed in the printed
messages.
(Other users may not have the permissions to remove files.)

\>AtlasOfGroupRepresentationsTestTableOfContentsRemoteUpdates( ) F

It is checked whether files in the local data directories must be updated
because of changes of the corresponding files in the remote data
directories.
(Such changes are restricted to bugfixes, their number is expected to be
very small.
A list of all changes of data files on the server is available in the
internet, see~"Web Services for the AtlasRep Package".)

For each local file that must be updated,
a line of the following form is printed.
\begintt
#I  update local file `...'
\endtt

\index{touch}
The necessity of updating a file is detected from the fact that the time
of its last modification on the server is later than that of the local
copy.
(This means that `touch'ing files in the local directories will cheat
this function.)

The return value is the list of names of all files that need to be
updated.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{User Parameters for the AtlasRep Package}

This section lists some global parameters which can be set by users.

*Accessing data files with perl or wget*

\index{perl}
\index{wget}
When {\GAP} uses the feature to access files on remote servers,
it calls one of the system programs `perl' or `wget'.
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;
hints for that can be found on the homepage of the AtlasRep package
(see~"Web Services for the AtlasRep Package").

The `perl' alternative is used by default because only with this
variant the listing of the current server contents is possible
(see~"Updating the Tables of Contents of the AtlasRep Package").
One can inhibit this (and hence force using `wget')
by setting the component `wget' of `AtlasOfGroupRepresentationsInfo'
(see~"AtlasOfGroupRepresentationsInfo") to `true';
this is necessary in the case that the perl module `libnet' is not available.

*Local or remote access*

One 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'.

%T how to add servers?

Independent of the default value of `AtlasOfGroupRepresentationsInfo'
(see~"AtlasOfGroupRepresentationsInfo"),
each user can individually change the `remote', `servers', and `wget'
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:GAP Root 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.

*Compressed or uncompressed data files*

When used with UNIX, {\GAP} can read `gzip'ped files
(see~"ref:Saving and Loading a Workspace" in the {\GAP} Reference Manual).
If the component `compress' of `AtlasOfGroupRepresentationsInfo' has the
value `true' then each {\MeatAxe} format file that is fetched from a remote
server is afterwards compressed with `gzip'.
\index{gzip}
\indextt{compress}
This saves a lot of space if many {\MeatAxe} format files are accessed.
(Note that data files in other formats are very small.)
For example, at the time of the release of version 1.2 there were about
$7\,000$ data files in {\MeatAxe} format, which needed $1\,300$ MB in
uncompressed and about $230$ MB in compressed form.
The default value for the component `compress' is `false'.

*Reading large matrices over finite fields*

Matrices over finite fields in {\GAP} can be represented in a compressed
format that needs less space than the corresponding text file.
Such a file can be read either line by line (which is the default)
or as a whole; the latter is faster but needs more space than the former.
For example, a $4\,370$ by $4\,370$ matrix over the field with $2$ elements 
(as occurs for an irreducible representation of the Baby Monster) requires
less than $3$ MB space in {\GAP} but the corresponding text file is more
than $19$ MB large, which means that when one reads the file with the
fast variant, {\GAP} will temporarily grow by more than this value.
One can change the mode via the global variable `CMeatAxe.FastRead'
(see~"Global Variables Used by the AtlasRep Package").

*Updates of the table of contents*

For replacing the package file with the table of contents by the current
version, see~"Updating the Tables of Contents of the AtlasRep Package".


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

The AtlasRep package may be loaded automatically when {\GAP} is started,
or it has to be loaded within {\GAP} as follows.
\beginexample
gap> LoadPackage( "atlasrep" );
true
\endexample
See~"ref:Loading a GAP 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}.

It is also possible to store ``private'' representations and
straight line programs in local directories, and to use them
in the same way as the ``official'' data.
See Chapter~"Private Extensions of the AtlasRep Package" for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{What's New in Version 1.2?}

Not much.

The release of Version~1.2 became necessary first of all
in order to provide a package version that is compatible with {\GAP}~4.4,
since some cross-references into the {\GAP} Reference Manual were broken
due to changes of section names.
Additionally, several web addresses concerning the package itself
were changed and thus had to be adjusted.

This opportunity was used
\beginlist
\item{--}
to upgrade the administrational part for
loading the package to the mechanism that is recommended for {\GAP}~4.4,

\item{--}
to extend the test suite, 
which now covers more consistency checks using
the {\GAP} Character Table Library~\cite{CTblLib},

\item{--}
to make the function `ScanMeatAxeFile' more robust, due to the fact that
the {\GAP} function `PermList' now returns `fail' instead of
raising an error,

\item{--}
to change the way how representations with prescribed properties are
accessed (the new function `OneAtlasGeneratingSetInfo' is now preferred to
the former `OneAtlasGeneratingSet', and `AllAtlasGeneratingSetInfos'
has been added in order to provide programmatic access in parallel to the
human readable descriptions printed by `DisplayAtlasInfo'),

\item{--}
and last but not least to include the current table of contents of the
underlying database.
\endlist

For AtlasRep users, the new feature of {\GAP}~4.4 is particularly
interesting that due to better kernel support, reading large matrices
over finite fields is now faster than it was in {\GAP}~4.3.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{What's New in Version 1.1?}

The biggest change w.r.t.~Version~1.1 is the addition of private extensions
(see Chapter~"Private Extensions of the AtlasRep Package").
It includes a new ``free format'' for straight line programs
(see~"The Effect of Private Extensions on the User Interface").
Unfortunately, this feature requires the system program `ls',
so it may be not available for example under the Windows operating system.

In order to admit the addition of other types of data,
the implementation of several functions has been changed.
Data types are described in~"Data Types" and
"Data Types Used in the Atlas of Group Representations".
An example of a new data type are quaternionic representations
(see~"Filenames Used in the Atlas of Group Representations").
The user interface itself
(see Chapter~"The User Interface of the AtlasRep Package")
remained the same.

\index{perl}
\index{wget}
As an alternative to `perl', one can use `wget' now for transferring data
files (see~"User Parameters for the AtlasRep Package").

Data files can be read much more efficiently in {\GAP}~4.3 than in
{\GAP}~4.2.
In Version~1.1 of the AtlasRep package, this feature is used for reading
matrices and permutations in {\MeatAxe} text format with `ScanMeatAxeFile'
(see~"ScanMeatAxeFile").
As a consequence, (at least) {\GAP}~4.3 is required for AtlasRep Version~1.1.

\index{gzip}
The new `compress' component of the global variable
`AtlasOfGroupRepresentationsInfo' (see~"AtlasOfGroupRepresentationsInfo")
allows one to store data files automatically in `gzip'ped form.

For matrix representations in characteristic zero, invariant forms and
generators for the centralizer algebra are now accessible in {\GAP} if they
are contained in the source files --this information had been ignored in
Version~1.0
(see~"AtlasOfGroupRepresentationsTestTableOfContentsRemoteUpdates" for
necessary updates).

Additional information is now available via the internet
(see~"Web Services for the AtlasRep Package").

The update facilities have been extended
(see~"Updating the Tables of Contents of the AtlasRep Package").

The manual is now distributed also in pdf and HTML format; on the other hand,
the PostScript format manual is no longer contained in the archives.

Apart from these changes,
a few minor bugs in the handling of {\MeatAxe} files have been fixed,
typos in the documentation have been corrected,
and the syntax checks for {\ATLAS} straight line programs
(see~"Reading and Writing Atlas Straight Line Programs") have been improved.


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

The perl script%
\index{perl}
for fetching remote data has been kindly provided by
Frank L{\accent127 u}beck and Max Neunh{\accent127 o}ffer.
Thanks also to Greg Gamble and Alexander Hulpke for technical hints
concerning ``standard'' perl.
Ulrich Kaiser helped with preparing the package for Windows.

The idea of supporting private extensions of the package
(see Chapter~"Private Extensions of the AtlasRep Package")
is due to Klaus Lux.
He used a preliminary version of AtlasRep Version~1.1,
and helped to fix several bugs.


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

