
<!-- %W  interfac.xml    GAP 4 package AtlasRep             Thomas Breuer -->


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Chapter Label="chap:The User Interface of the AtlasRep Package">
<Heading>The User Interface of the &AtlasRep; Package</Heading>

The <E>user interface</E> is the part of the &GAP; interface that allows one
to display information about the current contents of the database and to
access individual data (perhaps by downloading them,
see Section&nbsp;<Ref Sect="subsect:AtlasRepAccessRemoteFiles"/>).
The corresponding functions are described in this chapter.
See Section&nbsp;<Ref Sect="sect:Examples of Using the AtlasRep Package"/>
for some small examples how to use the functions of the interface.

<P/>

Data extensions of the &AtlasRep; package are regarded as another
part of the &GAP; interface,
they are described in Chapter&nbsp;<Ref Chap="chap:Private Extensions"/>.
Finally, the low level part of the interface is described in
Chapter&nbsp;<Ref Chap="chap:Technicalities of the AtlasRep Package"/>.

<!-- Note that we need not load the packages AtlasRep, CTblLib, TomLib
     because they have been loaded already in the Tutorial chapter. -->


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Downloading AtlasRep Data">
<Heading>Downloading &AtlasRep; Data</Heading>

Those functions from the package that access data from the web &ATLAS;
may have to download these data if they are not (yet) stored locally.
It may happen that downloads are not successful, for example if one is
offline or if the remote data are temporarily not reachable.
In these cases, functions such as
<Ref Func="AtlasGroup" Label="for various arguments"/> return <K>fail</K>.

<P/>

In order to inspect the reason for a failed download,
one can set the info level of <Ref Var="InfoAtlasRep"/> to at least <C>2</C>
and try again.

<P/>

It may make sense to restrict the time for downloads,
using the <Q>timeout</Q> feature of <Ref Oper="Download" BookName="utils"/>.
An upper bound for the number of seconds which may be spent on
the download of a file can be set globally via the user preference
<C>DownloadMaxTime</C>
(see <Ref Subsect="User preference DownloadMaxTime" BookName="utils"/>)
of the <Package>utils</Package> package.
The default is the value <C>0</C> which means that there is no upper bound.
For individual function calls, this preference can be overwritten
via the global option <C>maxTime</C>, where the value is again the maximal
number of seconds.
The following example is realistic if the data in question are not yet
stored locally and if your internet connection is not very fast.

<Log><![CDATA[
gap> AtlasGroup( "B", Characteristic, 5 : maxTime:= 1 );
fail
gap> AtlasGroup( "B", Characteristic, 5 : maxTime:= 5 );
<matrix group of size 4154781481226426191177580544000000 with 2 generators>
]]></Log>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Accessing vs. Constructing Representations">
<Heading>Accessing vs. Constructing Representations</Heading>

Note that <E>accessing</E> the data means in particular
that it is <E>not</E> the aim of this package to <E>construct</E>
representations from known ones.
For example, if at least one permutation representation for a group <M>G</M>
is stored but no matrix representation in a positive characteristic <M>p</M>,
say, then <Ref Func="OneAtlasGeneratingSetInfo"/>
returns <K>fail</K> when it is asked for a description of an available set of
matrix generators for <M>G</M> in characteristic <M>p</M>,
although such a representation can be obtained by reduction modulo <M>p</M>
of an integral matrix representation,
which in turn can be constructed from any permutation representation.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Group Names Used in the AtlasRep Package">
<Heading>Group Names Used in the &AtlasRep; Package</Heading>

<!-- The section title is referenced in htm/data/overview.htm. -->
<Alt Only="HTML"><![CDATA[<a id="sect:groupnames"/>]]></Alt>

When you access data via the &AtlasRep; package,
you specify the group in question by an admissible <E>name</E>.
Thus it is essential to know these names,
which are called <E>the &GAP; names</E> of the group in the following.

<P/>

For a group <M>G</M>, say, whose character table is available in
&GAP;'s Character Table Library (see <Cite Key="CTblLib"/>),
the admissible names of <M>G</M> are the admissible names
of this character table.
One such name is the 
<Ref Attr="Identifier" Label="for character tables" BookName="ref"/> value
of the character table,
see&nbsp;<Ref Subsect="Admissible Names for Character Tables in CTblLib" BookName="ctbllib"/>.
This name is usually very similar to the name used in the
&ATLAS; of Finite Groups <Cite Key="CCN85"/>.
For example,
<C>"M22"</C> is a &GAP; name of the Mathieu group <M>M_{22}</M>,
<C>"12_1.U4(3).2_1"</C> is a &GAP; name of <M>12_1.U_4(3).2_1</M>,
the two names <C>"S5"</C> and <C>"A5.2"</C> are &GAP; names of
the symmetric group <M>S_5</M>,
and the two names <C>"F3+"</C> and <C>"Fi24'"</C> are &GAP; names of
the simple Fischer group <M>Fi_{24}^\prime</M>.

<P/>

When a &GAP; name is required as an input of a package function,
this input is case insensitive.
For example, both <C>"A5"</C> and <C>"a5"</C> are valid arguments of
<Ref Func="DisplayAtlasInfo"/>.

<P/>

Internally, for example as part of filenames
(see Section&nbsp;<Ref Sect="sect:Filenames Used in the AGR"/>),
the package uses names that may differ from the &GAP; names;
these names are called <E>&ATLAS;-file names</E>.
For example, <C>"A5"</C>, <C>"TE62"</C>, and <C>"F24"</C> are
&ATLAS;-file names.
Of these, only <C>"A5"</C> is also a &GAP; name, but the other two are not;
corresponding &GAP; names are <C>"2E6(2)"</C> and <C>"Fi24'"</C>,
respectively.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Standard Generators Used in AtlasRep">
<Heading>Standard Generators Used in the &AtlasRep; Package</Heading>

For the general definition of <E>standard generators</E> of a group,
see <Cite Key="Wil96"/>.
<!-- or
Section&nbsp;<Ref Sect="Standard Generators of Groups" BookName="tomlib"/>. -->

<P/>

Several <E>different</E> standard generators may be defined for a group,
the definitions for each group that occurs in the
&ATLAS; of Group Representations can be found at

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

When one specifies the standardization,
the <M>i</M>-th set of standard generators is denoted by the number <M>i</M>.
Note that when more than one set of standard generators is defined for
a group, one must be careful to use <E>compatible standardization</E>.
For example, the straight line programs, straight line decisions and
black box programs in the database refer to a specific standardization
of their inputs.
That is, a straight line program for computing generators of a certain
subgroup of a group <M>G</M> is defined only for a specific set of standard
generators of <M>G</M>, and applying the program to matrix or permutation
generators of <M>G</M> but w.&nbsp;r.&nbsp;t.&nbsp;a different
standardization may yield unpredictable results.
Therefore the results returned by the functions described in this chapter
contain information about the standardizations they refer to.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Class Names Used in the AtlasRep Package">
<Heading>Class Names Used in the &AtlasRep; Package</Heading>

For each straight line program (see&nbsp;<Ref Func="AtlasProgram"/>)
that is used to compute lists of class representatives,
it is essential to describe the classes in which these elements lie.
Therefore, in these cases the records returned by the function
<Ref Func="AtlasProgram"/> contain a component <C>outputs</C>
with value a list of <E>class names</E>.

<P/>

Currently we define these class names only for simple groups and
certain extensions of simple groups,
see Section&nbsp;<Ref Subsect="subsect:Definition of ATLAS Class Names"/>.
The function <Ref Func="AtlasClassNames"/> can be used to compute the list
of class names from the character table in the &GAP; Library.

<#Include Label="classnames">
<#Include Label="AtlasClassNames">
<#Include Label="AtlasCharacterNames">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Accessing Data of the AtlasRep Package">
<Heading>Accessing Data via &AtlasRep;</Heading>

The examples shown in this section refer to the situation
that no extensions have been notified,
and to a perhaps outdated table of contents.
That is, the current version of the database may contain more information
than is shown here.

<P/>

<#Include Label="DisplayAtlasInfo">
<#Include Label="AtlasGenerators">
<#Include Label="AtlasProgram">
<#Include Label="AtlasProgramInfo">
<#Include Label="OneAtlasGeneratingSetInfo">
<#Include Label="AllAtlasGeneratingSetInfos">
<#Include Label="AtlasGroup">
<#Include Label="AtlasSubgroup">
<#Include Label="AtlasRepInfoRecord">
<#Include Label="EvaluatePresentation">
<#Include Label="StandardGeneratorsData">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Browse and AtlasRep">
<Heading><Package>Browse</Package> Applications Provided by &AtlasRep;</Heading>

The functions <Ref Func="BrowseMinimalDegrees"/>,
<Ref Func="BrowseBibliographySporadicSimple"/>,
and <Ref Func="BrowseAtlasInfo" BookName="Browse"/> 
(an alternative to <Ref Func="DisplayAtlasInfo"/>)
are available only if
the &GAP; package <Package>Browse</Package> (see <Cite Key="Browse"/>)
is loaded.

<#Include Label="BrowseMinimalDegrees">
<#Include Label="BrowseBibliographySporadicSimple">

</Section>


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

</Chapter>

