#############################################################################
##
#W  test.gd              GAP 4 package `atlasrep'               Thomas Breuer
##
#H  @(#)$Id: test.gd,v 1.32 2004/03/23 09:33:46 gap Exp $
##
#Y  Copyright (C)  2001,  Lehrstuhl D fuer Mathematik,  RWTH Aachen,  Germany
##
##  This file contains the declaration of functions to test the data
##  available in the {\ATLAS} of Group Representations.
##
##  1. Sanity Checks for the Atlas of Group Representations
##     (These checks are performed when `tst/testall.g' is read.)
##  2. Further Tests
##     (These checks are *not* performed automatically when
##     `tst/testall.g' is read since they require server access
##     or are very time consuming.
##
Revision.( "atlasrep/gap/test_gd" ) :=
    "@(#)$Id: test.gd,v 1.32 2004/03/23 09:33:46 gap Exp $";


#############################################################################
##
##  1. Sanity Checks for the Atlas of Group Representations
##     (These checks are performed when `tst/testall.g' is read.)
#1
##  The fact that the {\ATLAS} of Group Representations is designed as an
##  open database
##  (see~"Local or Remote Installation of the AtlasRep Package")
##  makes it especially desirable to have consistency checks available
##  which can be run automatically
##  whenever new data are added by the developers of the {\ATLAS}.
##  These checks can also be used for the private extensions of the package
##  (see Chapter~"Private Extensions of the AtlasRep Package").
##
##  The file `testall.g' in the `tst' directory of the package contains
##  `ReadTest' (see~"ref:ReadTest" in the {\GAP} Reference Manual) statements
##  for executing a collection of such sanity checks;
##  one can run them by starting {\GAP} in the `tst' directory,
##  and then calling `Read( \"testall.g\" )'.
##  If no problem occurs then {\GAP} prints only lines starting with one of
##  the following.
##  \begintt
##  + $Id:
##  + GAP4stones:
##  \endtt
##
##  The functions available to perform these tests and detailed information
##  about them can be found in the files `test.gd' and `test.gi' in the `gap'
##  directory of the package.
##
##  All these tests apply only to the *local* table of contents
##  (see~"The Tables of Contents of the Atlas of Group Representations"),
##  that is, only those data files are checked that are actually available
##  in the local {\GAP} installation.
##  No files are fetched from servers during these tests.
##
##  The examples in this manual form a part of these tests,
##  they are collected in the file `docxpl.tst' in the `tst' directory of the
##  package.
##


#############################################################################
##
#F  AtlasOfGroupRepresentationsTestWords( <tocid> )
##
##  Called with one argument <tocid>, a string,
##  `AtlasOfGroupRepresentationsTestWords' reads all straight line programs
##  that are stored in the directory with identifier <tocid>
##  (see~"AtlasOfGroupRepresentationsNotifyPrivateDirectory"),
##  using `ScanStraightLineProgram' (see~"ScanStraightLineProgram"),
##  and then runs the program on group generators.
##  The contents of the local `dataword' directory can be checked by entering
##  `\"local\"'.
##  The return value is `false' if an error occurs, otherwise `true'.
##
DeclareGlobalFunction( "AtlasOfGroupRepresentationsTestWords" );


#############################################################################
##
#F  AtlasOfGroupRepresentationsTestFileHeaders( [<tocid>[, <groupname>]] )
##
##  First suppose that `AtlasOfGroupRepresentationsTestFileHeaders' is called
##  with two arguments <tocid>, the identifier of a directory
##  (see~"AtlasOfGroupRepresentationsNotifyPrivateDirectory"), and
##  <groupname>, a component name in the table of contents of the directory.
##  The function checks for those data files for <groupname> in the <tocid>
##  directory that are in {\MeatAxe} text format whether the filename and the
##  header line are consistent;
##  it checks the data file in {\GAP} format whether the file name is
##  consistent with the contents of the file.
##
##  If only one argument <tocid> is given then all representations
##  available for <groupname> are checked with the three argument version.
##
##  If only one argument <tocid> is given then all available groups in the
##  directory with identifier <tocid> are checked;
##  the contents of the local `dataword' directory can be checked by entering
##  `\"local\"', which is also the default for <tocid>.
##
##  In all cases, the return value is `false' if an error occurred,
##  and `true' otherwise.
##
DeclareGlobalFunction( "AtlasOfGroupRepresentationsTestFileHeaders" );


#############################################################################
##
#F  AtlasOfGroupRepresentationsTestStandardization()
#F  AtlasOfGroupRepresentationsTestStandardization( <groupname> )
##
##  Currently it is just checked whether all generating sets corresponding to
##  the same set of standard generators have the same element orders.
##
##  *@As soon as the definition of standard generators becomes transparent
##  in {\GAP}, more should be done!@*
##
DeclareGlobalFunction( "AtlasOfGroupRepresentationsTestStandardization" );


#############################################################################
##
#F  AtlasOfGroupRepresentationsMatalgInfo()
##
##  This function checks whether the representations mentioned in the list
##  `AtlasOfGroupRepresentationsInfo.fieldinfo' are available according to
##  the table of contents,
##  and computes the `fieldinfo' string for those representations of the
##  types `matalg' and `quat' that are available and for which no entry has
##  been stored yet.
##  The return value is a string that can be used as a part of the file
##  `atlasprm.g'.
##
##  (Note that the availability and correctness of the `fieldinfo' entry for
##  each characteristic zero representation actually available is checked via
##  the `TestFileHeaders' function in the type records for these
##  representations.
##  This check is performed in `AtlasOfGroupRepresentationsTestFileHeaders'.)
##
DeclareGlobalFunction( "AtlasOfGroupRepresentationsMatalgInfo" );


#############################################################################
##
#F  AtlasOfGroupRepresentationsTestTableOfContentsContainment()
##
##  It is checked whether the local table of contents is a subset of the
##  currently stored version of the table of contents of the server.
##  The return value is the list of names of all those files in the local
##  data directories that have to be removed. 
##  For the files in the local data directories that are not part of the
##  remote data, information lines are printed.
##
DeclareGlobalFunction(
    "AtlasOfGroupRepresentationsTestTableOfContentsContainment" );


#############################################################################
##
##  2. Further Tests
##     (These checks are *not* performed automatically when
##     `tst/testall.g' is read since they require server access
##     or are very time consuming.
##


#############################################################################
##
#F  AtlasOfGroupRepresentationsTestTableOfContentsRemoteUpdates()
##
##  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.
##
DeclareGlobalFunction(
    "AtlasOfGroupRepresentationsTestTableOfContentsRemoteUpdates" );


#############################################################################
##
#F  AtlasOfGroupRepresentationsToDoInMakeTOC( <flags>, <filename> )
##
##  This function is called in the script `etc/maketoc' of the AtlasRep
##  package.
##  It calls `ReloadAtlasTableOfContents' with argument `\"remote\"' and then
##  appends the current header of the package file `gap/atlasprm.g' and the
##  output of `StringOfAtlasTableOfContents( \"remote\" )' to the file with
##  name <filename>.
##
##  If the list <flags> contains the string `\"-v\"' then the level of
##  `InfoAtlasRep' is set to $3$ in the beginning.
##
##  If the list <flags> contains the string `\"-test\"' then the functions
##  `AtlasOfGroupRepresentationsTestTableOfContentsContainment' and
##  `AtlasOfGroupRepresentationsTestTableOfContentsRemoteUpdates' are called
##  after the modified file <filename> has been read.
##
DeclareGlobalFunction( "AtlasOfGroupRepresentationsToDoInMakeTOC" );


#############################################################################
##
#F  AtlasOfGroupRepresentationsTestFiles( [<tocid>[,<groupname>]] )
##
##  `AtlasOfGroupRepresentationsTestFiles' is an analogue of
##  `AtlasOfGroupRepresentationsTestFileHeaders'
##  (see~"AtlasOfGroupRepresentationsTestFileHeaders").
##  The function does not check if the first line of a {\MeatAxe} file is
##  consistent with the filename
##  but checks whether reading the files with `ScanMeatAxeFile' returns
##  non-`fail' results.
##
##  In all cases, the return value is `false' if an error occurred,
##  and `true' otherwise.
##
DeclareGlobalFunction( "AtlasOfGroupRepresentationsTestFiles" );


#############################################################################
##
#F  AtlasOfGroupRepresentationsTestClassScripts()
#F  AtlasOfGroupRepresentationsTestClassScripts( <groupname> )
##
##  First suppose that `AtlasOfGroupRepresentationsTestClassScripts' is
##  called with one argument <groupname>, the name of a component in
##  `AtlasOfGroupRepresentationsInfo.TableOfContents.( "local" )'.
##  If the {\GAP} table library contains an ordinary character table with
##  `Identifier' value the {\GAP} name corresponding to <groupname> then
##  it is checked whether all those straight line programs for this group
##  that return class representatives are consistent with the character table
##  in the sense that the class names used occur for the table, and that the
##  element orders and centralizer orders for the classes are correct.
##
##  If no argument is given then all available groups are checked with the
##  one argument version.
##
##  In all cases, the return value is `false' if an error occurred,
##  and `true' otherwise.
##
DeclareGlobalFunction( "AtlasOfGroupRepresentationsTestClassScripts" );


#############################################################################
##
#F  AtlasOfGroupRepresentationsTestCycToCcls()
#F  AtlasOfGroupRepresentationsTestCycToCcls( <groupname> )
##
##  First suppose that `AtlasOfGroupRepresentationsTestCycToCcls' is
##  called with one argument <groupname>, the name of a component in
##  `AtlasOfGroupRepresentationsInfo.TableOfContents.( "local" )'.
##  If the {\GAP} table library contains an ordinary character table with
##  `Identifier' value the {\GAP} name corresponding to <groupname> then
##  it is checked whether there is a straight line program for computing
##  representatives of cyclic subgroups such that the straight line program
##  for computing class representatives from the outputs is missing and can
##  be computed automatically; in this case the missing script is printed
##  if the level of `InfoAtlasRep' is at least $1$.
##
##  If no argument is given then all available groups are checked with the
##  one argument version.
##
##  In all cases, the return value is `false' if at least one script is
##  missing, and `true' otherwise.
##
DeclareGlobalFunction( "AtlasOfGroupRepresentationsTestCycToCcls" );


#############################################################################
##
#E

