<!-- #################################################################### -->
<!-- ##                                                                ## -->
<!-- ##  rcwaaux.xml         RCWA documentation           Stefan Kohl  ## -->
<!-- ##                                                                ## -->
<!-- #################################################################### -->

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

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

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

This version of &RCWA; needs at least &GAP;&nbsp;4.7.0,
&ResClasses;&nbsp;3.4.0,
<Package>GRAPE</Package>&nbsp;4.3&nbsp;<Cite Key="GRAPE"/>,
<Package>Polycyclic</Package>&nbsp;2.6&nbsp;<Cite Key="Polycyclic"/> and
&GAPDoc;&nbsp;1.4&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 on all platforms for which &GAP; is available.
It is completely written in the &GAP; language and does neither
contain nor require external binaries. In particular, possible warnings
concerning missing binaries issued by other packages when loading &RCWA;
can safely 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: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:TheTestingRoutines">
<Heading>The testing routines</Heading>

<ManSection>
  <Func Name="RCWATestInstall" Arg=""/>
  <Returns> nothing. </Returns>
  <Description>
    Performs a nontrivial computation to check whether an installation of
    &RCWA; appears to work. Errors, i.e. differences to the correct results
    of the test computation, are reported. The processed test file is
    <F>pkg/rcwa/tst/testinstall.tst</F>.
  </Description>
</ManSection>

<ManSection>
  <Func Name="RCWATestAll" Arg=""/>
  <Returns> nothing. </Returns>
  <Description>
    Runs the full test suite of the &RCWA; package.
    Any differences to the supposed results of the test computations
    are reported. The processed test file is
    <F>pkg/rcwa/tst/testall.g</F>. <P/>

    Please note that the test suite is a tool for developing.
    The tests are deliberately very volatile to allow to spot possible
    problems of any kind also in other packages or in the &GAP; Library.
    For this reason you may see reports of differences
    which simply reflect improved methods in other packages or in the
    &GAP; Library (for example an object may already know more of its
    attributes or properties than it is expected to, or an object may
    be represented in a better way), or which are caused by changes of
    the way certain objects are printed, and which are therefore harmless.
    However if the correct and the actual output look different
    mathematically or if you see error messages or if &GAP; crashes,
    then something went wrong. Also, reports about significantly
    increased run times of individual commands as well as run times of
    test files which are much longer than the predicted times shown
    may indicate a problem.
  </Description>
</ManSection>

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

</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: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 commands 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:BitmapPictures">
<Heading>Utility functions for 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="LoadBitmapPicture" Subkey="filename">
      <C>LoadBitmapPicture</C>
    </Index>

    The picture can be read back into &GAP; by the function
    <C>LoadBitmapPicture(<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>

&RCWA; also provides functions for steganography in bitmap pictures:

<ManSection>
  <Func Name="EncryptIntoBitmapPicture"
        Arg="picturefile, cleartextfile, passphrase"
        Label="picturefile, cleartextfile, passphrase"/>
  <Func Name="DecryptFromBitmapPicture"
        Arg="picturefile, cleartextfile, passphrase"
        Label="picturefile, cleartextfile, passphrase"/>
  <Returns> nothing. </Returns>
  <Description>
    The first function encrypts the contents of the textfile named
    <A>cleartextfile</A> into the image from the file named
    <A>picturefile</A>, using the passphrase <A>passphrase</A>.
    The modified image is written to a file whose name is derived from
    <A>picturefile</A> by appending the string <C>-out</C>. <P/>
  
    The second function decrypts an encoded text from the file named
    <A>picturefile</A> using the passphrase <A>passphrase</A>, and writes
    the obtained cleartext to a file named <A>cleartextfile</A>. <P/>
  
    These steganographic utility functions are designed for security rather
    than speed, and are intended to be used for texts of the order of
    magnitude of what one would normally write into the body of an e-mail
    -- encoding about 100kb into a picture of usual size should be still
    convenient, while the functions are definitely not suitable for
    encoding entire backups or the like. <P/>
  
    <C>Info</C> messages on the progress of the encryption / decryption
    are given at <C>InfoLevel</C> 2 of <C>InfoRCWA</C>. 
  </Description>
</ManSection>

</Section>

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

<Section Label="sec:ConvertingLogfilesToHTML">
<Heading>Converting GAP logfiles to HTML</Heading>

&RCWA; provides a routine to convert &GAP; logfiles to HTML.

<ManSection>
  <Func Name="Log2HTML" Arg="logfilename" Label="logfilename"/>
  <Returns> nothing. </Returns>
  <Description>
    This function converts the &GAP; logfile <A>logfilename</A> to HTML.
    The extension of the input file must be <C>*.log</C>. The name of the
    output file is the same as the one of the input file except that the
    extension <C>*.log</C> is replaced by <C>*.html</C>.
    There is a sample CSS file in <File>rcwa/doc/gaplog.css</File>,
    which you can adjust to your taste.
  </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="QuotientsList"><C>QuotientsList</C></Index>
<Index Key="FloatQuotientsList"><C>FloatQuotientsList</C></Index>

&RCWA; provides a couple of small utility functions which can be used in
a more general context. They are described in this section. <P/>

The utility functions for groups and group elements are
<C>GeneratorsAndInverses(<A>G</A>)</C> which returns a list of generators
of <A>G</A> and their inverses, the function
<C>EpimorphismByGenerators(<A>G</A>,<A>H</A>)</C> which 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> which 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>, and the function
<C>AllProducts(<A>l</A>,<A>k</A>)</C> which returns the list of
all products of <A>k</A> entries of the list&nbsp;<A>l</A>. <P/>

The utility functions for lists are <C>DifferencesList(<A>l</A>)</C> and
<C>QuotientsList(<A>l</A>)</C>, which return the list of differences
respectively quotients of consecutive entries of the list&nbsp;<A>l</A>, and
the function <C>FloatQuotientsList(<A>l</A>)</C>, which returns the list of
floating point approximations of the latter. <P/>

<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>

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/>

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

Yet another utility function is <C>AssignGlobals(<A>rec</A>)</C> which
takes as argument a record <A>rec</A> and assigns its components to global
variables of the same (i.e. the component's) names. <P/>

<Index Key="AllSmoothIntegers"><C>AllSmoothIntegers</C></Index>
<Index Key="ExponentOfPrime"><C>ExponentOfPrime</C></Index>
<Index Key="LaTeXStringFactorsInt"><C>LaTeXStringFactorsInt</C></Index>

Finally, the function <C>AllSmoothIntegers(<A>maxp</A>,<A>maxn</A>)</C>
returns a list of all integers less than or equal to <A>maxn</A> which do
not have prime divisors exceeding <A>maxp</A>, the function
<C>ExponentOfPrime(<A>n</A>,<A>p</A>)</C> returns the exponent of the
prime <A>p</A> in the prime factorization of <A>n</A>, and the function
<C>LaTeXStringFactorsInt(<A>n</A>)</C> returns the prime factorization
of an integer <A>n</A> as a string in &LaTeX; format.

</Section>

</Chapter>

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