[m-rev.] for review: added examples to mercury/extras/gator/README

[Samrith UONG]

For review by Ralph or Julien.

Estimated hours taken: 2

mercury/extras/gator/README:
        Show examples of configuration files in gator's README file, to
        give the reader a better idea of what is required to set up
        gator.

Index: README
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/extras/gator/README,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 README
--- README      13 Feb 2006 01:42:02 -0000      1.1.1.1
+++ README      15 Feb 2006 04:15:10 -0000
@@ -7,8 +7,8 @@
 to determine which ones to apply, especially since different options may
 work better with different programs or different inputs.  This program
 attempts to find the optimal set of optimisation flags to be passed to
-mmc(1).  It works using a genetic algorithm; see the following URLs for
-details on how genetic algorithms work:
+the compiler.  It works using a genetic algorithm; see the following
+URLs for details on how genetic algorithms work:

              http://en.wikipedia.org/wiki/Genetic_algorithm
      http://www.cs.cmu.edu/Groups/AI/html/faqs/ai/genetic/top.html
@@ -31,9 +31,11 @@
 third column contains the "genotype" of an individual, which is the list
 of compiler options that are passed to the compiler.

-The program is intended to be general enough to test different programs,
-as well as different programming languages and compilers.  The following
-sections describe how to configure gator to do this.
+By default, the program is configured to optimise a simple "hello world"
+program written in Mercury.  However, the program is intended to be
+general enough to test different programs, as well as different
+programming languages and compilers.  The following sections describe
+how to configure gator to do this.

 2 Configuring for your network

@@ -73,6 +75,34 @@
        path$i: the path to the directory containing the compiler.  This
                is pre-pended to $PATH in the evaluate script.

+The hosts in gator.conf are accessed using ssh(1) and ssh-agent(1).  It
+is necessary to have SSH keys set up on each of these hosts.  See the
+following URL for details on how to use ssh-agent(1):
+
+                   http://mah.everybody.org/docs/ssh
+
+As an example, suppose we are setting up gator to run on a network
+containing two hosts named "jupiter" and "saturn".
+
+       num_hosts=2
+
+       host1=jupiter
+       workspace1=$HOME/mercury/extras/gator
+       benchmarks1=/home/jupiter/samrith/mercury/samples
+       path1=/home/jupiter/public/mercury-latest/i686-pc-linux-gnu/bin
+
+       host2=saturn
+       workspace2=$HOME/mercury/extras/gator
+       benchmarks2=/home/saturn/samrith/mercury/samples
+       path2=/home/saturn/public/mercury-latest/i686-pc-linux-gnu/bin
+
+In this example, $workspace1 and $workspace2 are both the same path, and
+are on the same NFS-mounted filesystem.  All of the workspaces may be on
+the same filesystem, although they don't have to be.  However, the
+benchmark directories must be separate directories, so that separate
+builds can be done on each host.  In this example, $benchmarks1 and
+$benchmarks2 are located on their host's local filesystems.
+
 3 Configuring for your software

 The evaluate.conf file allows the user to change the benchmarking
@@ -105,6 +135,31 @@

        run$i: the command used to run the program.

+As an example, suppose we want to change the program being optimised.
+The new program is in "benchmarks/progs/ray/proj.m", rather than
+"mercury/samples/hello.m".  The first thing that needs to be done is to
+copy the program's source code to each of the hosts.  Then, the
+gator.conf file needs to be modified.  The new file is similar to the
+example given above, except that the $benchmarks1 and $benchmarks2
+directories are different:
+
+       benchmarks1=/home/jupiter/samrith/benchmarks
+       benchmarks2=/home/saturn/samrith/benchmarks
+
+The evaluate.conf file would look like this:
+
+       num_progs=1
+
+       prog1="$benchmarks"/progs/ray/proj
+       clean1="mmc --make proj.realclean; rm -rf Mercury"
+       compile1="mmc --make -O0 $flags proj"
+       run1="./proj -f 100 -S -s 0.4 2 -a 0.1 dh.scene 140 140 0 0 0 >dh.ppm"
+
+The example above gives just one Mercury program.  The default
+evolve.conf file is set up for just one Mercury program, so if more
+programs or different compilers are used, it is necessary to modify
+evolve.conf (see section 4 for details).
+
 4 Configuring parameters for the genetic operators

 If the intention is to, for example, optimise for space instead of time,
@@ -118,14 +173,14 @@
 be read by io.read/3.

 The first term contains the "Weightings" used by phenotype.fitness/2.
-This parameter is coupled with the number of programs being tested (by
-default 5, see section 3 on evaluate.conf).  For each program, there are
-three measurements taken by the software:  the time taken to compile,
-the resulting executable size and the time taken to run the executable.
+This parameter is coupled with the number of programs being tested (see
+section 3 on evaluate.conf).  For each program, there are three
+measurements taken by the software:  the time taken to compile, the
+resulting executable size and the time taken to run the executable.
 Because of this, the list must be of length $num_progs * 3.

-The following examples give cause gator to search for a set of flags
-that will compile in the least amount of time,
+The following examples cause gator to search for a set of flags that
+will compile five programs in the least amount of time,

                        [ 1.0, 1.0, 1.0, 1.0, 1.0,
                          0.0, 0.0, 0.0, 0.0, 0.0,
@@ -147,6 +202,16 @@
 the compiler.  This is used by genotype.mutation/5, which toggles a
 random flag in an individual's genotype.

+Suppose the evaluate.conf file (see section 3 for details) specifies two
+programs, both of which are compiled with gcc(1).  In this case, the
+first term would need to be a list of length $num_progs * 3 = 2 * 3 = 6.
+The second term would need to contain a list of gcc optimisation
+options, rather than mmc options.
+
+       [ 0.5, 0.5, 0.0, 0.0, 1.0, 1.0 ].
+
+       [ "-fbranch-probabilities", "-fcaller-saves", "-fcprop-registers" ].
+
 5 Further modifying the genetic operators

 The genetic operators themselves can be modified directly.  They are

--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------