# Copyright (C) 2007, 2013 Dominik Dahlem <Dominik.Dahlem@gmail.com>
#  
# This file is free software; as a special exception the author gives
# unlimited permission to copy and/or distribute it, with or without 
# modifications, as long as this notice is preserved.
# 
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

1) General Approach
 * I used GNU autotools to maintain this project:
   autoconf version 2.61
   automake version 1.10

 * Getopt was used to parse command-line parameters.  A help message
   can be displayed by specifying "-?" or "-h" to the command-line of
   the executable.

 * The framework was implemented in a portable way. I.e., it can be
   compiled as a serial or parallel (MPI) application.

2) Configuration
 * The project ships with a configure script generated by
   autotools. The following options are supported:

   * --enable-debug : enables debugging information. Though, it does
     not synchronize in the case of MPI.

   * --enable-mpi : enables mpi. This requires mpi to be known to the
     system. In the HPC lab set CFLAGS=-I/usr/lib/mpich/include

   * --enable-test : enables the unit tests. However, the unit tests
     can only be executed as a serial application and therefore
     require MPI to be disabled.

   * --enable-lcov : enables the lcov coverage report generation. lcov
     uses gcov to instrument the code and transforms the result into a
     snazzy html page. For lcov to work, the test flag has to be
     enabled as well.

   * --enable-gsl : enables GSL. Alternatively to the drand48() random
     number generator, GSL can be used instead. Initially, GSL was
     used as default, but then it was discovered that the lab
     computers don't have the gsl libraries installed. I decided to
     keep GSL as an option anyway. If GSL is not enabled the random
     seed for the default drand48/lrand48 functions can be set via the
     command-line.

3) Make
 * Installing the application was not considered. 
   * To build the project with MPI support do:

   ./configure --enable-mpi
   make

   * To build the application with debugging information do:

   ./configure --enable-debug
   make

   * To build the application with GSL support do:

   ./configure --enable-gsl
   make

   * Or all three.

   * To build the tests and run the coverage analysis do:

   ./configure --enable-test --enable-gcov
   make
   make lcov

4) Project layout
 * The framework is built as a library in src/ga/framework. It can be
   either compiled as a parallel application or serial
   application. The main executable is in src/ga/main.

   - src
      - ga/framework
      - ga/main

 * A Doxygen configuration file is provided to generate the code
   documentation in HTML. doxygen support is integrated into the makefiles.
   Run: make doxygen-run

   - doc
      - doxygen
         - html

 * The coverage report based on lcov/gcov is supplied in the coverage folder.

   - coverage
      - lcov-reports/html

5) Remarks on the approach
 * The application accepts a number of command-line arguments (see
   help output) to configure the number of generations, the size of
   the population, the number of bits representing a chromosome, the
   mutation rate, and the seed for the *rand48 functions.

 * The command-line arguments are parsed with getopt and verified once
   they are parsed. The verification ensures that the ranges of the
   input parameters are correct. In case of a verification failure an
   error message presented to the user.

 * The chromosomes are represented as unsigned short dynamic
   arrays. I've chosen this approach, because I considered splitting
   the chromosome up into possibly two or more ints/longs as too
   awkward to process.

 * I implemented a binary-to-gray code conversion and vice-versa. The
   gray code conversion provides the "adjacency property" to the
   mutation operation. That means that a single bit mutation results
   in adjacent integer numbers in the binary representation. In
   contrast successive integers are usually many bit flips away in the
   binary representation. Additionally, mutations on the gray code
   representation allows the numbers to roll over from 0 to the
   highest number (vice-versa). Hollstien [1] investigated this
   property in his PhD thesis.

6) Bibliography
[1] R. Hollstien, Artificial Genetic Adaptation in Computer Control
    Systems, PhD, University of Michigan, 1971.