atlasrep.xml

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


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


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Installing the AtlasRep Package">
<Heading>Installing the <Package>AtlasRep</Package> Package</Heading>

To install the package, unpack the archive file in a
directory in the <F>pkg</F> directory of your local copy of &GAP;&nbsp;4.
This might be the <F>pkg</F> directory of the &GAP;&nbsp;4 root directory,
see&nbsp;<Ref Sect="Installing a GAP Package" BookName="ref"/>
for details.
It is however also possible to keep an additional <F>pkg</F> directory
in your private directories,
see Section&nbsp;<Ref Sect="GAP Root Directories" BookName="ref"/>.
The latter possibility <E>must</E> be chosen if you do not have write access
to the &GAP; root directory.

<P/>

Data files that are available from an earlier version
of the package are in principle kept;
see&nbsp;<Ref
Func="AtlasOfGroupRepresentationsTestTableOfContentsRemoteUpdates"/>
for necessary updates.

<P/>

If it is likely that one will work offline, it makes sense to install the
<Q>starter archive</Q> that can be downloaded from the package's homepage.

<P/>

The package consists entirely of &GAP; code,
no external binaries need to be compiled for the package itself.
However, if the &GAP; package <Package>IO</Package> <Cite Key="IO"/>
<Index>IO package</Index>
is used to access remote data files
(see Section&nbsp;<Ref Sect="subsect:Accessing data files with wget or IO"/>)
then its external binary must be available.

<P/>

After unpacking the package archive,
the write permissions for those directories should be checked
into which users will download files.
Every user can customize these paths via a user preference,
see Section <Ref Subsect="subsect:AtlasRepDataDirectory"/>,
the defaults are the subdirectories
<F>datagens</F> and <F>dataword</F> of the package directory.
The recommended permissions under UNIX for the default directories
are set as follows.

<P/>

<Log><![CDATA[
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
]]></Log>

<P/>

<#Include Label="[1]{testinst.g}">

<P/>

PDF, HTML, and text versions of the package manual are available
in the <F>doc</F> directory of the package.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Maintaining the Local Data of the AtlasRep Package">
<Heading>Maintaining the Local Data of the <Package>AtlasRep</Package>
Package</Heading>

<!-- The section title is referenced in index.html. -->
<Alt Only="HTML"><![CDATA[<a id="sect:maintain"/>]]></Alt>

The current <E>table of contents</E> of the database is contained in
the file <F>gap/atlasprm.g</F> of the <Package>AtlasRep</Package> package.
This file is read by default when the package is loaded.
It may happen that new data files have been added to the servers since the
last release of the <Package>AtlasRep</Package> package,
thus it is useful to update the table of contents of the package
from time to time.

<P/>

For that, one can fetch the most recent version of the file
<F>gap/atlasprm.g</F> from the home page of the package
(see Section&nbsp;<Ref Sect="sect:Web Services for the AtlasRep Package"/>),
either by calling&nbsp;<Ref Func="ReloadAtlasTableOfContents"/>
in a &GAP; session
or <Q>by hand</Q>.
In the latter case, the new file can then be read into the &GAP; session via
<Ref Func="ReplaceAtlasTableOfContents"/>.
<#Include Label="ATLASREP_TOCFILE">

<P/>

Users who have write access to the directory where the
<Package>AtlasRep</Package> package is
installed can alternatively use the <F>maketoc</F> script in the <F>etc</F>
directory of the package for regularly updating the file
<F>gap/atlasprm.g</F>.
Users without this write access can store the new file in a different place,
and read it with <Ref Func="ReplaceAtlasTableOfContents"/>.

<P/>

<#Include Label="ReloadAtlasTableOfContents">
<#Include Label="StoreAtlasTableOfContents">
<#Include Label="ReplaceAtlasTableOfContents">
<#Include Label="AGRTestTableOfContentsRemoteUpdates">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:User Parameters for the AtlasRep Package">
<Heading>User Parameters for the <Package>AtlasRep</Package> Package</Heading>

This section lists global parameters for which it might make sense
to change their defaults by assignments to global variables
(see <Ref Func="AtlasOfGroupRepresentationsUserParameters"/>
for an overview of these parameters)
or using &GAP;'s user preferences
(see <Ref Subsect="Configuring User preferences" BookName="ref"/>).


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="subsect:Local or remote access">
<Heading>Local or Remote Access</Heading>

<Index>local access</Index>
<Index>remote access</Index>
<Index>servers</Index>
There are two possibilities to use the <Package>AtlasRep</Package> package.

<P/>

<List>
<Mark><E>Local access only (offline)</E></Mark>
<Item>
    You can restrict the access to the data that are actually stored in
    the local installation of &GAP;.
</Item>
<Mark><E>Remote access (online)</E></Mark>
<Item>
    If your computer is connected to a network that provides access to
    the &ATLAS; data (for example the internet) then the functions of the
    package may fetch the requested data automatically from remote servers
    when they are required for the first time;
    these data are then by default stored in the local copy,
    so later access to them needs no network transfer.
</Item>
</List>

<P/>

The latter possibility is presently not used by other &GAP; packages,
so it may be regarded as an important feature of the
<Package>AtlasRep</Package> package.
Anyhow it requires a few words of explanation.

<P/>

The possibility of online access reflects in particular the fact
that the &ATLAS; of Group Representations is designed
as an <E>open database</E>, 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 &GAP; when remote access is enabled,
after one has updated the corresponding table of contents
(see Section&nbsp;<Ref Sect="sect:Maintaining the Local Data of the AtlasRep Package"/>).

<P/>

Remote access is enabled if and only if the value of the <C>remote</C>
component of the global variable
<Ref Var="AtlasOfGroupRepresentationsInfo"/> is <K>true</K>.
If one wants to work offline, i.e., if one does <E>not</E> want &GAP;
to attempt accessing remote data
then this value must be set to <K>false</K>.

<P/>

Conversely, if the default value of the <C>remote</C> component
in your &GAP; installation is <K>false</K>
then changing this value to <K>true</K> may be not successful.
First, it might be the case that no server is reachable.
And second, if one can in principle <E>download</E> files from a server then
it might be impossible to actually <E>store</E> these files 
in the data directories of the installed package;
in this case, it is advisable to install the whole package
or just its data directories in a private directory,
see&nbsp;<Ref Sect="GAP Root Directories" BookName="ref"/> for details.

</Subsection>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="subsect:Adding and Removing Servers">
<Heading>Adding and Removing Servers</Heading>

When access to remote data is enabled
(see Section&nbsp;<Ref Sect="subsect:Local or remote access"/>)
then the available servers are given by the <C>servers</C> component
of the global variable <Ref Var="AtlasOfGroupRepresentationsInfo"/>.

<P/>

<E>Removing</E> entries from this list means to disable access to the
corresponding servers,
<E>adding</E> entries makes the corresponding servers available.
Of course the latter makes sense only if the new servers really exist,
for example in a local network.

<P/>

Currently there is just one remote server.
As soon as other servers become available, or a server name is changed
which makes it necessary to adjust the <C>servers</C> component,
this will be announced in the &GAP; Forum, cf.
<Ref Sect="Further Information about GAP" BookName="tut"/>.
The same holds when upgrades of the package become available.

</Subsection>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="subsect:Accessing data files with wget or IO">
<Heading>Accessing Data Files with the &GAP; Package <Package>IO</Package>
or with <F>wget</F></Heading>

<#Include Label="IO_or_wget">

</Subsection>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="subsect:Compressed or uncompressed data files">
<Heading>Compressed or Uncompressed Data Files</Heading>

When used with UNIX, &GAP; can read <F>gzip</F>ped files,
see&nbsp;<Ref Sect="Saving and Loading a Workspace" BookName="ref"/>.
If the component <C>compress</C>
<Index Key ="compress"><C>compress</C></Index>
of <Ref Var="AtlasOfGroupRepresentationsInfo"/> has the value <K>true</K>
then each &MeatAxe; format file that is fetched from a remote
server is afterwards compressed with <F>gzip</F>.
<Index Key ="gzip"><F>gzip</F></Index>
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&nbsp;1.5.1 there were about
<M>8\,400</M> data files in &MeatAxe; format,
which needed about <M>1\,400</M> MB in uncompressed text format
and about <M>275</M> MB in compressed text format.
The default value for the component <C>compress</C> is <K>false</K>.

</Subsection>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="subsect:Customizing DisplayAtlasInfo">
<Heading>Customizing <C>DisplayAtlasInfo</C></Heading>

The way how <Ref Func="DisplayAtlasInfo"/> shows the requested overview
is controlled by the component <C>displayFunction</C>
of <Ref Var="AtlasOfGroupRepresentationsInfo"/>.
The default value is <Ref Func="Print" BookName="ref"/>,
other useful values are <Ref Func="PrintFormattedString" BookName="gapdoc"/>
and <C>AGR.Pager</C>;
the latter calls <Ref Func="Pager" BookName="ref"/> with the <C>formatted</C>
option, which is necessary for switching off &GAP;'s automatic line breaking.

</Subsection>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="subsect:Customizing the Access to Data files">
<Heading>Customizing the Access to Data Files</Heading>

By default, local data files are stored in the subdirectories <F>datagens</F>
and <F>dataword</F> of the directory given by the user preference
<C>AtlasRepDataDirectory</C>
(see Section <Ref Subsect="subsect:AtlasRepDataDirectory"/>),
and the files are exactly the text files provided on the servers.
However, a more flexible approach may be useful.

<P/>

First, one may want to use <E>different file formats</E>,
for example the &MeatAxe; binary files that are provided by the servers
parallel to the &MeatAxe; text files.
Second, one may want to use <E>a different directory structure</E>,
for example the same structure as used on the servers
&ndash;this makes sense for example if a local mirror of a server
is available, because then one can read the server files directly,
without transferring/copying them to another directory.

<P/>

As a consequence, one would like to customize the meaning of the following
three access steps.

<P/>

<List>
<Mark>Are the required files locally available?</Mark>
<Item>
  The required files may have a different name or a different path,
  and the data can be available in one file or can be distributed to several
  files.
</Item>
<Mark>How can a file be made locally available?</Mark>
<Item>
  A different server file may be fetched
  or some postprocessing may be required.
</Item>
<Mark>How is the data of a file accessed by &GAP;?</Mark>
<Item>
  A different function may be needed to read the file.
</Item>
</List>

<P/>

Details how to achieve these customizations can be found in Section
<Ref Sect="sect:How to Customize the Access to Data files"/>.

</Subsection>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="subsect:Reading large matrices over finite fields">
<Heading>Reading Large Matrices over Finite Fields</Heading>

Matrices over finite fields in &GAP; can be represented in a compressed
format that needs less space than the corresponding text file.
Such a &MeatAxe; format text file can be read by
<Ref Func="ScanMeatAxeFile"/> 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 <M>4\,370</M> by <M>4\,370</M> matrix over the field
with two elements 
(as occurs for an irreducible representation of the Baby Monster) requires
less than <M>3</M> MB space in &GAP; but the corresponding &MeatAxe; format
text file is more than <M>19</M> 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 by setting the global variable
<Ref Var="CMeatAxe.FastRead"/> to <K>true</K> or <K>false</K>, respectively.

<P/>

Note that this parameter is meaningful only when 
<Ref Func="ScanMeatAxeFile"/> is used.
It has no effect for example if &MeatAxe; binary files are read,
cf.&nbsp;<Ref Func="FFMatOrPermCMtxBinary"/>.

</Subsection>

<#Include Label="AtlasOfGroupRepresentationsShowUserParameters">

<#Include Label="AtlasRepDataDirectory">
<#Include Label="WriteMeatAxeFilesOfMode2">
<#Include Label="BaseOfMeatAxePermutation">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Web Services for the AtlasRep Package">
<Heading>Web Services for the <Package>AtlasRep</Package> Package</Heading>

The home page of the <Package>AtlasRep</Package> package is

<P/>
<URL>&ATLASREPHOME;</URL>.
<P/>

Besides package archives and introductory package information, it provides

<P/>

<List>
<Item>
  the current file with the <E>table of contents</E>
  (the file <F>gap/atlasprm.g</F> of the package, see
  <URL>&ATLASREPHOME;/atlasprm.g</URL>),
  cf.&nbsp;<Ref Func="ReloadAtlasTableOfContents"/>,
</Item>
<Item>
  a <E>starter archive</E>
  containing many small representations and programs
  (see <URL>&ATLASREPHOME;/atlasrepdata.tar.gz</URL>),
</Item>
<Item>
  the list of <E>changes of server files</E> in HTML format
  (see <URL>&ATLASREPHOME;/htm/data/changes.htm</URL>),
  cf.&nbsp;<Ref Func="AtlasOfGroupRepresentationsTestTableOfContentsRemoteUpdates"/>,
  and
</Item>
<Item>
  an <E>overview of the data</E> available via the &GAP; interface to the
  &ATLAS; of Group Representations, in HTML format (see
  <URL>&ATLASREPHOME;/htm/data/overview.htm</URL>);
  this is similar to the information shown by <Ref Func="DisplayAtlasInfo"/>,
  further information can be found on the home page of the &ATLAS;,
  see &ATLASSERVER;.
</Item>
</List>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Extending the Atlas Database">
<Heading>Extending the &ATLAS; Database</Heading>

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&nbsp;&WILSONMAIL;.

<P/>

It is also possible to store <Q>private</Q> representations and programs
in local directories,
and to use them in the same way as the <Q>official</Q> data.
See Chapter&nbsp;<Ref Chap="chap:Private Extensions"/> for details.

</Section>


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

</Chapter>