technica.xml

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


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

This chapter describes those parts of the &GAP; interface to the
&ATLAS; of Group Representations that do not belong to the user interface
(cf.&nbsp;Chapter&nbsp;<Ref Chap="chap:The User Interface of the AtlasRep Package"/>).
<P/>
Besides global variables used for administrational purposes
(see Section&nbsp;<Ref Sect="sect:Global Variables Used by the AtlasRep Package"/>)
and several sanity checks
(see Section&nbsp;<Ref Sect="sect:AGR Sanity Checks"/>),
they can be regarded as
the interface between the data actually contained in the files and
the corresponding &GAP; objects
(see
Section&nbsp;<Ref Sect="sect:How to Customize the Access to Data files"/>,
<Ref Sect="sect:Reading and Writing MeatAxe Format Files"/>,
<Ref Sect="sect:Reading and Writing Atlas Straight Line Programs"/>,
and&nbsp;<Ref Sect="sect:Data Types Used in the AGR"/>),
and the interface between the remote and the local version of the database
(see Section&nbsp;<Ref Sect="sect:Filenames Used in the AGR"/>
and&nbsp;<Ref Sect="sect:The Tables of Contents of the AGR"/>).
The former interface contains functions to read and write files in
&MeatAxe; format, which may be interesting for users familiar with
&MeatAxe; standalones (see for example&nbsp;<Cite Key="CMeatAxe"/>).
Other low level functions may be undocumented in the sense that they are
not described in this manual.
Users interested in them may look at the actual implementation in the
<F>gap</F> directory of the package,
but it may happen that this will be changed
in future versions of the package.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Global Variables Used by the AtlasRep Package">
<Heading>Global Variables Used by the <Package>AtlasRep</Package> Package
</Heading>

For debugging purposes, the functions from the &GAP; interface to the
&ATLAS; of Group Representations print information depending on the info
level of the info classes <Ref InfoClass="InfoAtlasRep"/>,
<Ref InfoClass="InfoCMeatAxe"/>, and <Ref InfoClass="InfoBBox"/>
(cf.&nbsp;<Ref Sect="Info Functions" BookName="ref"/>).

<P/>

The info level of an info class can be changed using
<Ref Func="SetInfoLevel" BookName="ref"/>.
For example, the info level of <Ref InfoClass="InfoAtlasRep"/> can be set
to the nonnegative integer <A>n</A> using
<C>SetInfoLevel( InfoAtlasRep, <A>n</A> )</C>.

<P/>

Information about files being read can be obtained by setting the
value of the global variable <C>InfoRead1</C>
to <Ref Func="Print" BookName="ref"/>.

<P/>

<#Include Label="InfoAtlasRep">
<#Include Label="InfoCMeatAxe">
<#Include Label="InfoBBox">

<P/>

<ManSection>
<Var Name="CMeatAxe.FastRead"/>

<Description>
If this component is bound and has the value <K>true</K> then
<Ref Func="ScanMeatAxeFile"/> reads text files via
<Ref Func="StringFile" BookName="gapdoc"/>.
Otherwise each file containing a matrix over a finite field is read line by
line via <Ref Func="ReadLine" BookName="ref"/>,
and the &GAP; matrix is constructed line by line, in a compressed
representation
(see&nbsp;<Ref Sect="Row Vectors over Finite Fields" BookName="ref"/>
and&nbsp;<Ref Sect="Matrices over Finite Fields" BookName="ref"/>),
which makes it possible to read large matrices in a reasonable amount
of space.
The <Ref Func="StringFile" BookName="gapdoc"/> approach is faster
but needs more intermediate space when text files containing
matrices over finite fields are read.
</Description>
</ManSection>

<P/>

<#Include Label="AGR">
<#Include Label="AtlasOfGroupRepresentationsInfo">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:How to Customize the Access to Data files">
<Heading>How to Customize the Access to Data files</Heading>

<#Include Label="AccessFunctionsDefault">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Reading and Writing MeatAxe Format Files">
<Heading>Reading and Writing MeatAxe Format Files</Heading>

<Index Subkey="MeatAxe format">matrix</Index>
<Index Subkey="MeatAxe format">permutation</Index>

<#Include Label="ScanMeatAxeFile">
<#Include Label="MeatAxeString">
<#Include Label="FFList">
<#Include Label="CMtxBinaryFFMatOrPerm">
<#Include Label="FFMatOrPermCMtxBinary">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Reading and Writing Atlas Straight Line Programs">
<Heading>Reading and Writing &ATLAS; Straight Line Programs</Heading>

<#Include Label="ScanStraightLineProgram">
<#Include Label="AtlasStringOfProgram">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Data Types Used in the AGR">
<Heading>Data Types Used in the &ATLAS; of Group Representations</Heading>

Each representation or program that is administrated by the
<Package>AtlasRep</Package> package belongs to a unique <E>data type</E>.
Informally, examples of data types are
<Q>permutation representation</Q>,
<Q>matrix representation over the integers</Q>, or
<Q>straight line program for computing class representatives</Q>.

<P/>

The idea is that for each data type, there can be
<List>
<Item>
  a column of its own in the output produced by
  <Ref Func="DisplayAtlasInfo"/>
  when called without arguments or with only argument a list of
  group names,
</Item>
<Item>
  a line format of its own for the output produced by
  <Ref Func="DisplayAtlasInfo"/>
  when called with first argument a group name,
</Item>
<Item>
  an input format of its own for <Ref Func="AtlasProgram"/>,
</Item>
<Item>
  an input format of its own for <Ref Func="OneAtlasGeneratingSetInfo"/>,
  and
</Item>
<Item>
  specific tests for the data of this data type;
  these functions are used by the global tests described in
  Section&nbsp;<Ref Sect="sect:AGR Sanity Checks"/>.
</Item>
</List>

<P/>

Formally, a data type is defined by a record whose components are used by
the interface functions.
The details are described in the following.

<#Include Label="AGRDeclareDataType">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:Filenames Used in the AGR">
<Heading>Filenames Used in the &ATLAS; of Group Representations</Heading>

<#Include Label="[1]{access}">

<P/>

<#Include Label="AGRParseFilenameFormat">
<#Include Label="AGRFileContents">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:The Tables of Contents of the AGR">
<Heading>The Tables of Contents of the &ATLAS; of Group Representations
</Heading>

<#Include Label="toc">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:AGR Sanity Checks">
<Heading>Sanity Checks for the &ATLAS; of Group Representations</Heading>

<#Include Label="tests">

</Section>


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

</Chapter>