<!-- #################################################################### -->
<!-- ##                                                                ## -->
<!-- ##  resclaux.xml      ResClasses documentation       Stefan Kohl  ## -->
<!-- ##                                                                ## -->
<!-- #################################################################### -->

<Chapter Label="ch:InstallationAndAuxiliaryFunctions">
<Heading>Installation and Auxiliary Functions</Heading>

<!-- #################################################################### -->

<Section Label="sec:Requirements">
<Heading>Requirements</Heading>

This version of &ResClasses; needs at least &GAP;&nbsp;4.9.0,
<Package>Polycyclic</Package>&nbsp;2.11&nbsp;<Cite Key="Polycyclic"/>,
&GAPDoc;&nbsp;1.5.1&nbsp;<Cite Key="GAPDoc"/> and
<Package>Utils</Package>&nbsp;0.40&nbsp;<Cite Key="Utils"/>.
It can be used on all platforms for which &GAP; is available.
&ResClasses; is completely written in the &GAP; language and does
neither contain nor require external binaries.

</Section>

<!-- #################################################################### -->
<Section Label="sec:Installation">

<Heading>Installation</Heading>

Like any other &GAP; package, &ResClasses; is usually installed in the
<F>pkg</F> subdirectory of the &GAP; distribution. This is accomplished by
extracting the distribution file in this directory. By default,
the package &ResClasses; is autoloaded. If you have switched autoloading
of packages off, you can load &ResClasses; via
<C>LoadPackage( "resclasses" );</C>.

</Section>

<!-- #################################################################### -->

<Section Label="sec:TheTestingRoutines">
<Heading>The testing routines</Heading>

<ManSection>
  <Func Name="ResClassesTest" Arg=""/>
  <Returns>
    <C>true</C> if no errors were found, and <C>false</C> otherwise.
  </Returns>
  <Description>
    Performs tests of the &ResClasses; package.
    Errors, i.e. differences to the correct results of the test computations,
    are reported. The processed test files are in the directory
    <F>pkg/resclasses/tst</F>.
  </Description>
</ManSection>

<ManSection>
  <Func Name="ResClassesTestExamples" Arg=""/>
  <Returns> nothing. </Returns>
  <Description>
    Runs all examples in the manual of the &ResClasses; package,
    and reports any differences between the actual output and the
    output printed in the manual.
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

<Section Label="sec:PreparingForDistribution">
<Heading>Utilities for preparing the package for distribution</Heading>

<ManSection>
  <Func Name="ResClassesBuildManual" Arg=""/>
  <Returns> nothing. </Returns>
  <Description>
    This function is a development tool which builds the manual of the
    &ResClasses; package in the file formats &LaTeX;, PDF, HTML and
    ASCII text.
    This is accomplished using the &GAPDoc; package by Frank Lübeck and
    Max Neunhöffer. Building the manual is possible only on UNIX-type
    systems and requires PDF&LaTeX;.
    As all files generated by this function are included in the
    distribution file anyway, users will not need it.
  </Description>
</ManSection>

<ManSection>
  <Func Name="ConvertPackageFilesToUNIXLineBreaks" Arg="package"/>
  <Returns> nothing. </Returns>
  <Description>
    This function is a development tool which converts the text files
    of package <A>package</A> from Windows- to UNIX line breaks.
    Here <A>package</A> is assumed to be either <C>"resclasses"</C>
    or <C>"rcwa"</C>.
  </Description>
</ManSection>

<ManSection>
  <Func Name="RemoveTemporaryPackageFiles" Arg="package"/>
  <Returns> nothing. </Returns>
  <Description>
    This function is a development tool which cleans up the temporary
    files of package <A>package</A>. Here <A>package</A> is assumed to
    be either <C>"resclasses"</C> or <C>"rcwa"</C>.
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

<Section Label="sec:LogToDatedFile">
<Heading>Creating timestamped logfiles</Heading>

<ManSection>
  <Func Name="LogToDatedFile" Arg="directory"/>
  <Returns> the full pathname of the created logfile. </Returns>
  <Description>
    This function opens a logfile in the specified directory;
    the name of the logfile has the form of a timestamp, i.e.
    <C>year-month-day hour-minute-second.log.</C>
    If &GAP; is already in logging mode, the old logfile is closed
    before the new one is opened. <P/>

    The availability of this function depends on that the package
    <Package>IO</Package>&nbsp;<Cite Key="IO"/> is installed and compiled.
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

<Section Label="sec:SendEmailAndEmailLogFile">
<Heading>DownloadFile, SendEmail and EmailLogFile</Heading>

<ManSection>
  <Func Name="DownloadFile" Arg="url"/>
  <Returns>
    the contents of the file with URL <A>url</A> in the form of a string
    if that file exists and the download was successful, and <C>fail</C>
    otherwise.
  </Returns>
  <Description>
    As most system-related functions, <C>DownloadFile</C> works only under
    UNIX / Linux. Also the computer must of course be connected to the
    Internet.
  </Description>
</ManSection>

<ManSection>
  <Func Name="SendEmail" Arg="sendto, copyto, subject, text"/>
  <Returns>
    zero if everything worked correctly, and a system error number otherwise.
  </Returns>
  <Description>
    Sends an e-mail with subject <A>subject</A> and body <A>text</A> to the
    addresses in the list <A>sendto</A>, and copies it to those in the list
    <A>copyto</A>. The first two arguments must be lists of strings, and
    the latter two must be strings. <P/>

    As most system-related functions, <C>SendEmail</C> works only under
    UNIX / Linux. Also the computer must of course be connected to the
    Internet.
  </Description>
</ManSection>

<ManSection>
  <Func Name="EmailLogFile" Arg="addresses"/>
  <Returns>
    zero if everything worked correctly, and a system error number otherwise.
  </Returns>
  <Description>
    Sends the current log file by e-mail to <A>addresses</A>, if &GAP; is in
    logging mode and one is working under UNIX / Linux, and does nothing
    otherwise. The argument <A>addresses</A> must be either a list of e-mail
    addresses or a single e-mail address. Long log files are abbreviated,
    i.e. if the log file is larger than 64KB, then any output is truncated
    at 1KB, and if the log file is still longer than 64KB afterwards, it is
    truncated at&nbsp;64KB.
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

<Section Label="sec:BitmapPictures">
<Heading>Creating bitmap pictures</Heading>

&ResClasses; provides functions to generate bitmap picture files from
suitable pixel matrices and vice versa. The author has successfully tested
this feature both under Linux and under Windows, and the generated pictures
can be processed further with many common graphics programs:

<ManSection>
  <Func Name="SaveAsBitmapPicture"
        Arg="picture, filename" Label="picture, filename"/>
  <Returns> nothing. </Returns>
  <Description>
    Writes the pixel matrix <A>picture</A> to a bitmap- (bmp-)
    picture file named <A>filename</A>. The filename should include
    the entire pathname.

    The argument <A>picture</A> can be a GF(2) matrix, in which case a
    monochrome picture file is generated. In this case, zeros stand for
    black pixels and ones stand for white pixels.

    The argument <A>picture</A> can also be an integer matrix, in which case
    a 24-bit true color picture file is generated. In this case, the entries
    of the matrix are supposed to be integers <M>n = 65536 \cdot red + 256
    \cdot green + blue</M> in the range <M>0, \dots, 2^{24}-1</M> specifying
    the RGB values of the colors of the pixels. <P/>

    <Index Key="LoadBitmapPicture" Subkey="filename">
      <C>LoadBitmapPicture</C>
    </Index>

    The picture can be read back into &GAP; by the function
    <C>LoadBitmapPicture(<A>filename</A>)</C>.
<Example>
<![CDATA[
gap> color   := n->32*(n mod 8)+256*32*(Int(n/8) mod 8)+65536*32*Int(n/64);;
gap> picture := List([1..512],y->List([1..512],x->color(Gcd(x,y)-1)));;
gap> SaveAsBitmapPicture(picture,Filename(DirectoryTemporary(),"gcd.bmp"));
]]>
</Example>
  </Description>
</ManSection>

<ManSection>
  <Func Name="DrawLineNC"
        Arg="pic, x1, y1, x2, y2, color, width"
        Label="pic, x1, y1, x2, y2, color, width"/>
  <Returns> nothing. </Returns>
  <Description>
    Draws a line on picture <A>pic</A> from (<A>x1</A>,<A>y1</A>)
    to (<A>x2</A>,<A>y2</A>), with color <A>color</A> and of width
    <A>width</A>.
<Example>
<![CDATA[
gap> picture := NullMat(100,100)+2^24-1;;
gap> DrawLineNC(picture,30,20,70,80,255,8);                 
gap> SaveAsBitmapPicture(picture,Filename(DirectoryTemporary(),
>                        "example.bmp"));
]]>
</Example>
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

<Section Label="sec:UtilityFunctions">
<Heading>Some general utility functions</Heading>

&ResClasses; provides a few small utility functions and -operations
which can be used in a more general context.
They are described in this section. <P/>

<Index Key="PositionsSublist"><C>PositionsSublist</C></Index>

There is an operation <C>PositionsSublist(<A>list</A>,<A>sub</A>)</C>
which returns the list of positions at which <A>sub</A> occurs as a sublist
of <A>list</A>.

<Example>
<![CDATA[
gap> PositionsSublist([1,2,6,2,7,2,7,2,3,1,6,2,7,2,8],[2,7,2]);
[ 4, 6, 12 ]
gap> PositionsSublist([1,2,3,4,3,2,1],[1,3,5]);
[  ]
gap> PositionsSublist("This is an example, isn't it?","is");   
[ 3, 6, 21 ]
]]>
</Example>

<Index Key="EquivalenceClasses"
       Subkey="for a list and a function computing a class invariant">
  <C>EquivalenceClasses</C>
</Index>
<Index Key="EquivalenceClasses"
       Subkey="for a list and a function describing an equivalence relation">
  <C>EquivalenceClasses</C>
</Index>

Also there are methods <C>EquivalenceClasses(<A>l</A>,<A>inv</A>)</C>
and <C>EquivalenceClasses(<A>l</A>,<A>rel</A>)</C> which decompose
a list&nbsp;<A>l</A> into equivalence classes under an equivalence
relation. The equivalence relation is given either as a function <A>inv</A>
computing a class invariant of a given list entry or as a function <A>rel</A>
which takes as arguments two list entries and returns either <C>true</C>
or <C>false</C> depending on whether the arguments belong to the same
equivalence class or not. <P/>

<Example>
<![CDATA[
gap> EquivalenceClasses([2..50],n->Length(Factors(n))); 
[ [ 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47 ], 
  [ 4, 6, 9, 10, 14, 15, 21, 22, 25, 26, 33, 34, 35, 38, 39, 46, 49 ], 
  [ 8, 12, 18, 20, 27, 28, 30, 42, 44, 45, 50 ], [ 16, 24, 36, 40 ], 
  [ 32, 48 ] ]
gap> EquivalenceClasses(AsList(AlternatingGroup(4)),
>                       function ( g, h )
>                         return IsConjugate(SymmetricGroup(4),g,h);
>                       end);
[ [ (2,3,4), (2,4,3), (1,2,3), (1,2,4), (1,3,2), (1,3,4), (1,4,2), 
      (1,4,3) ], [ (1,2)(3,4), (1,3)(2,4), (1,4)(2,3) ], [ () ] ]
]]>
</Example>

<Index Key="GraphClasses"><C>GraphClasses</C></Index>
<Index Key="AllGraphs"><C>AllGraphs</C></Index>
<Index Key="IdGraphNC"><C>IdGraphNC</C></Index>

Further, there is an operation <C>GraphClasses(<A>n</A>)</C> which returns
a list of isomorphism classes of graphs with vertices <M>1, 2, \dots, n</M>,
and an operation <C>AllGraphs(<A>n</A>)</C> which returns a list of
representatives of these classes.
The graphs are represented as lists of edges, where each edge is a list of
the two vertices it connects, and they are ordered by ascending number
of edges. Given a graph <A>graph</A> with <A>n</A> vertices, the operation
<C>IdGraphNC(<A>graph</A>,GraphClasses(<A>n</A>))</C> returns the index
<C>i</C> such that <A>graph</A> lies in <C>GraphClasses(<A>n</A>)[i]</C>.
For reasons of efficiency, <C>IdGraphNC</C> performs no argument checks. <P/>

<Example>
<![CDATA[
gap> GraphClasses(3);
[ [ [  ] ], [ [ [ 1, 2 ] ], [ [ 2, 3 ] ], [ [ 1, 3 ] ] ], 
  [ [ [ 1, 2 ], [ 1, 3 ] ], [ [ 1, 2 ], [ 2, 3 ] ], 
      [ [ 1, 3 ], [ 2, 3 ] ] ], [ [ [ 1, 2 ], [ 1, 3 ], [ 2, 3 ] ] ] ]
gap> List(last,Length); # sizes of classes
[ 1, 3, 3, 1 ]
gap> AllGraphs(4);
[ [  ], [ [ 1, 2 ] ], [ [ 1, 2 ], [ 1, 3 ] ], [ [ 1, 2 ], [ 3, 4 ] ], 
  [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ] ], [ [ 1, 2 ], [ 1, 3 ], [ 2, 3 ] ], 
  [ [ 1, 2 ], [ 1, 3 ], [ 2, 4 ] ], 
  [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 3 ] ], 
  [ [ 1, 2 ], [ 1, 3 ], [ 2, 4 ], [ 3, 4 ] ], 
  [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 3 ], [ 2, 4 ] ], 
  [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 3 ], [ 2, 4 ], [ 3, 4 ] ] ]
gap> List(last,Length); # numbers of edges
[ 0, 1, 2, 2, 3, 3, 3, 4, 4, 5, 6 ]
gap> IdGraphNC([[1,3],[1,8],[3,8]],GraphClasses(4)); # a triangle graph
6
gap> AllGraphs(4)[last];
[ [ 1, 2 ], [ 1, 3 ], [ 2, 3 ] ]
]]>
</Example>

</Section>

<!-- #################################################################### -->

</Chapter>

<!-- #################################################################### -->
