<!-- #################################################################### -->
<!-- ##                                                                ## -->
<!-- ##  rcwaaux.xml         RCWA documentation           Stefan Kohl  ## -->
<!-- ##                                                                ## -->
<!-- ##  $Id: rcwaaux.xml,v 1.50 2007/09/06 16:18:19 stefan Exp $      ## -->
<!-- ##                                                                ## -->
<!-- #################################################################### -->

<Chapter Label="ch:InstallationAndAuxiliaryFunctions">
<Heading>Installation and auxiliary functions</Heading>

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

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

The &RCWA; package needs at least &GAP;&nbsp;4.4.7, &ResClasses;&nbsp;2.5.1,
<Package>GRAPE</Package>&nbsp;4.0&nbsp;<Cite Key="GRAPE"/>,
<Package>Polycyclic</Package>&nbsp;2.1&nbsp;<Cite Key="Polycyclic"/> and
&GAPDoc;&nbsp;1.0&nbsp;<Cite Key="GAPDoc"/>. With possible exception of
the most recent version of &ResClasses;, all needed packages are already
present in an up-to-date standard &GAP; installation.
The &RCWA; package can be used under UNIX, under Windows and on the
MacIntosh. It is completely written in the &GAP; language and does neither
contain nor require external binaries. In particular, warnings concerning
missing binaries issued by <Package>GRAPE</Package> or other packages
can savely be ignored.

</Section>

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

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

Like any other &GAP; package, &RCWA; must be installed in the <F>pkg</F>
subdirectory of the &GAP; distribution. This is accomplished by extracting
the distribution file in this directory. If you have done this, you can
load the package as usual via <C>LoadPackage( "rcwa" );</C>.

</Section>

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

<Section Label="sec:TheInfoClass">
<Heading>The Info class of the package</Heading>

<ManSection>
  <InfoClass Name="InfoRCWA"/>
  <Description>
    This is the Info class of the <Package>RCWA</Package> package.
    See section <E>Info Functions</E> in the &GAP;
    Reference Manual for a description of the Info mechanism.
    For convenience: <C>RCWAInfo(</C><A>n</A><C>)</C> is a shorthand for
    <C>SetInfoLevel(InfoRCWA</C>,<A>n</A><C>)</C>.
    <Index Key="RCWAInfo"><C>RCWAInfo</C></Index>
  </Description>
</ManSection>

</Section>

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

<Section Label="sec:TheTestingRoutine">
<Heading>The testing routine</Heading>

<ManSection>
  <Func Name="RCWATest" Arg=""/>
  <Returns> Nothing. </Returns>
  <Description>
    Performs tests of the &RCWA; 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/rcwa/tst</F>.
  </Description>
</ManSection>

</Section>

</Chapter>

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

<Section Label="sec:BuildingTheManual">
<Heading>Building the manual</Heading>

The following routine is a development tool. As all files it generates
are included in the distribution file anyway, users will not need it.

<ManSection>
  <Func Name="RCWABuildManual" Arg=""/>
  <Returns> Nothing. </Returns>
  <Description>
    This function builds the manual of the &RCWA; 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 systems
    and requires PDF&LaTeX;.
  </Description>
</ManSection>

</Section>

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

<Section Label="sec:BitmapPictures">
<Heading>Loading and saving bitmap pictures</Heading>

&RCWA; provides functions to create 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 produced 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="ReadFromBitmapPicture" Subkey="filename">
      <C>ReadFromBitmapPicture</C>
    </Index>

    The picture can be read back into &GAP; by the function
    <C>ReadFromBitmapPicture(<A>filename</A>)</C>.
<Log>
<![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,"~/images/gcd.bmp");
]]>
</Log>
  </Description>
</ManSection>

</Section>

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

<Section Label="sec:RunningDemonstrations">
<Heading>Running demonstrations</Heading>

&RCWA; provides a routine to run demonstrations of its functionality or
of other features of &GAP;. It is intended for being used in talks.

<ManSection>
  <Func Name="RunDemonstration" Arg="filename" Label="filename"/>
  <Returns> Nothing. </Returns>
  <Description>
    This function executes the code in the file named <A>filename</A>.
    It shows a command and the corresponding output, waits for a keystroke,
    shows the next command and the corresponding output, waits again for
    a keystroke, and so on until the end of the file.
    The demonstration can be stopped by pressing&nbsp;<C>q</C>.
    The function is adapted from the function <C>Demonstration</C> in the
    file <File>lib/demo.g</File> of the main &GAP; distribution. 
  </Description>
</ManSection>

</Section>

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

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

<Index Key="GeneratorsAndInverses" Subkey="for a group">
  <C>GeneratorsAndInverses</C>
</Index>
<Index Key="EpimorphismByGenerators" Subkey="for two groups">
  <C>EpimorphismByGenerators</C>
</Index>
<Index Key="ListOfPowers"><C>ListOfPowers</C></Index>
<Index Key="AllProducts"><C>AllProducts</C></Index>
<Index Key="DifferencesList"><C>DifferencesList</C></Index>
<Index Key="FloatQuotients"><C>FloatQuotients</C></Index>
<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>

&RCWA; introduces a couple of small utility functions which can be used in
a more general context: The function <C>GeneratorsAndInverses(<A>G</A>)</C>
returns a list of generators of <A>G</A> and their inverses,
<C>EpimorphismByGenerators(<A>G</A>,<A>H</A>)</C> is
a shorthand for <C>GroupHomomorphismByImages(<A>G</A>,<A>H</A>,
GeneratorsOfGroup(<A>G</A>),GeneratorsOfGroup(<A>H</A>))</C>
(there is also an <C>NC</C> version of this), the function
<C>ListOfPowers(<A>g</A>,<A>exp</A>)</C> returns the list
<C>[<A>g</A>,<A>g</A>&circum;2,...,<A>g</A>&circum;<A>exp</A>]</C>
of powers of&nbsp;<A>g</A>, the function
<C>AllProducts(<A>l</A>,<A>k</A>)</C> returns the list of
all products of <A>k</A> entries of the list&nbsp;<A>l</A>,
the function <C>DifferencesList(<A>l</A>)</C> returns the list of
differences of consecutive entries of the list&nbsp;<A>l</A>, and
the function <C>FloatQuotients(<A>l</A>)</C> returns the list of
floating point approximations of quotients of consecutive entries
of the list&nbsp;<A>l</A>. <P/>

There are also 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.

</Section>

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